Gitea/Forgejo Backend

Gitea and its fork Forgejo are lightweight, self-hosted Git services that are easy to set up and use. Sveltia CMS offers comprehensive support for Gitea/Forgejo repositories, enabling efficient content management.

Requirements

• Gitea 1.24, Forgejo 12.0 or later.
• A Gitea or Forgejo account.
• A Gitea or Forgejo repository to store your content.
• Sveltia CMS installed in your project.

Breaking change from Netlify/Decap CMS

Sveltia CMS requires newer versions of Gitea/Forgejo than Netlify/Decap CMS did to leverage enhanced, high-performance API capabilities. For security reasons, it’s recommended to use the latest stable versions of Gitea/Forgejo.

CSP Settings

If your site uses a Content Security Policy (CSP), You may need to update it to allow requests to Gitea or Forgejo. See the CSP documentation for more details.

Configuration

The base configuration for the Gitea/Forgejo backend is straightforward. You need to specify the name of the backend as gitea and provide the repo option with the format owner/repo, where owner is your Gitea/Forgejo username or organization name, and repo is the repository name.

YAML

backend:
  name: gitea
  repo: user/repo

TOML

[backend]
name = "gitea"
repo = "user/repo"

JSON

{
  "backend": {
    "name": "gitea",
    "repo": "user/repo"
  }
}

JavaScript

{
  backend: {
    name: "gitea",
    repo: "user/repo",
  },
}

Instance URL

By default, Sveltia CMS uses the public Gitea instance at https://gitea.com. If you use a self-hosted Gitea or Forgejo instance or a hosting service like Codeberg, you need to set the base_url and api_root options in your backend configuration to point to your server URL.

YAML

backend:
  name: gitea
  repo: owner/repo
  base_url: https://gitea.example.com
  api_root: https://gitea.example.com/api/v1

TOML

[backend]
name = "gitea"
repo = "owner/repo"
base_url = "https://gitea.example.com"
api_root = "https://gitea.example.com/api/v1"

JSON

{
  "backend": {
    "name": "gitea",
    "repo": "owner/repo",
    "base_url": "https://gitea.example.com",
    "api_root": "https://gitea.example.com/api/v1"
  }
}

JavaScript

{
  backend: {
    name: "gitea",
    repo: "owner/repo",
    base_url: "https://gitea.example.com",
    api_root: "https://gitea.example.com/api/v1",
  },
}

For Codeberg, use the following settings:

YAML

backend:
  name: gitea
  repo: owner/repo
  base_url: https://codeberg.org
  api_root: https://codeberg.org/api/v1

TOML

[backend]
name = "gitea"
repo = "owner/repo"
base_url = "https://codeberg.org"
api_root = "https://codeberg.org/api/v1"

JSON

{
  "backend": {
    "name": "gitea",
    "repo": "owner/repo",
    "base_url": "https://codeberg.org",
    "api_root": "https://codeberg.org/api/v1"
  }
}

JavaScript

{
  backend: {
    name: "gitea",
    repo: "owner/repo",
    base_url: "https://codeberg.org",
    api_root: "https://codeberg.org/api/v1",
  },
}

The API version for Gitea/Forgejo is v1, so make sure to include /api/v1 in the api_root option.

Breaking change from Netlify/Decap CMS

In Netlify/Decap CMS, the default origin of the base_url and api_root backend options is set to https://try.gitea.io (test instance). In Sveltia CMS, we changed it to https://gitea.com (public free service). In most cases, anyway, you need to set these options explicitly to point to your own Gitea/Forgejo instance.

Authentication

TIP

If you plan to only work with your local repository, you don’t need to set up authentication.

Access Token (Quick Start)

If you or a small team of developers are the only users of your CMS instance, you can use an access token for authentication. This method is straightforward and doesn’t require setting up an OAuth app.

Just click the “Sign In with Token” button on the login screen and enter your token. The prompt dialog will provide a link to the token generation page on Gitea/Forgejo with the required scopes pre-selected.

PKCE Authorization (Recommended)

To use PKCE authorization with Sveltia CMS, you need to register a new OAuth app on Gitea/Forgejo and update your Sveltia CMS configuration file accordingly. Here’s how:

1. Follow the instructions in the Gitea or Forgejo documentation to create a new OAuth application.
2. Set the Redirect URI to your CMS admin URL, e.g., https://your-domain.com/admin/.
3. Uncheck the Confidential option.
4. Copy the Client ID of your registered OAuth app.

Then, update your Sveltia CMS configuration file to include the app_id option with your Client ID:

YAML

backend:
  name: gitea
  repo: owner/repo
  app_id: YOUR_CLIENT_ID

TOML

[backend]
name = "gitea"
repo = "owner/repo"
app_id = "YOUR_CLIENT_ID"

JSON

{
  "backend": {
    "name": "gitea",
    "repo": "owner/repo",
    "app_id": "YOUR_CLIENT_ID"
  }
}

JavaScript

{
  backend: {
    name: "gitea",
    repo: "owner/repo",
    app_id: "YOUR_CLIENT_ID",
  },
}

Users’ OAuth tokens will be automatically renewed as needed, so there’s no need to worry about token expiration.

Features

Git LFS

Git Large File Storage (LFS) is supported out of the box in the Gitea/Forgejo backend. Just make sure to enable LFS in your repository settings. For more information, refer to the official documentation for Gitea or Forgejo.

GraphQL

GraphQL support is not available for Gitea/Forgejo repositories. Sveltia CMS uses the REST API to interact with Gitea/Forgejo.

Commit Signing

Commit signing is supported in Gitea/Forgejo repositories, but you may need to configure it on your server. Please refer to the Gitea documentation or Forgejo documentation for more details on setting up commit signing.

Service Status Checking

Service status checking is not available for Gitea/Forgejo repositories. If you are experiencing issues connecting to your Gitea/Forgejo instance, please verify the server status manually.

Workflows

The following content management workflows are supported with the Gitea/Forgejo backend:

• Local Workflow
• Simple Workflow

Future Plans

Support for the Editorial Workflow may be added in the future.

Deployment

Both Gitea and Forgejo support CI/CD pipelines that can be used to automate the deployment of your site whenever content is updated through Sveltia CMS. You can set up workflows to build and deploy your static site generator (SSG) whenever changes are pushed to the repository.

• Gitea Actions
• Forgejo Actions