@ross/semantic-release-forgejo

semantic-release plugin to publish a Forgejo (or Gitea) release.

Step	Description
verifyConditions	Verify the presence and the validity of the authentication and the assets option configuration.
publish	Publish a Forgejo release, optionally uploading file assets.
addChannel	Update a Forgejo release's pre-release field.

Forked from saitho/semantic-release-gitea and modernized for TypeScript, ESM, and Forgejo.

Install

npm install @ross/semantic-release-forgejo --save-dev

Usage

The plugin can be configured in the semantic-release configuration file:

Basic Usage (Release Only)

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@ross/semantic-release-forgejo", {
      "forgejoUrl": "https://git.reslate.solutions"
    }]
  ]
}

With Assets

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@ross/semantic-release-forgejo", {
      "forgejoUrl": "https://git.reslate.solutions",
      "assets": [
        {"path": "dist/asset.min.css", "label": "CSS distribution"},
        {"path": "dist/asset.min.js", "label": "JS distribution"}
      ]
    }]
  ]
}

With Package Registry Publishing

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@ross/semantic-release-forgejo", {
      "forgejoUrl": "https://git.reslate.solutions",
      "assets": [
        {"path": "dist/*.tgz", "label": "Package"}
      ]
    }]
  ]
}

Forgejo Authentication

The Forgejo authentication configuration is required and can be set via environment variables.

Create an API key token via your Forgejo installation's web interface: Settings → Applications → Generate New Token.

The token has to be made available in your CI environment via the FORGEJO_TOKEN environment variable. The user associated with the token must have push permission to the repository.

Environment Variables

Variable	Description	Required
FORGEJO_TOKEN	The token used to authenticate with Forgejo.	Yes
FORGEJO_URL	The URL to your Forgejo instance.	Yes
FORGEJO_PREFIX	The Forgejo API prefix.	No (default: /api/v1)

Options

Option	Description	Default
forgejoUrl	The Forgejo endpoint.	FORGEJO_URL environment variable.
forgejoApiPathPrefix	The Forgejo API prefix.	FORGEJO_PREFIX environment variable.
assets	Files to upload to the release.	—

Assets

The assets option can be a glob or an array of globs and objects with the following properties:

Property	Description	Default
path	Required. A glob to identify the files to upload.	—
name	The name of the downloadable file on the Forgejo release.	File name from path.
label	Short description displayed on the Forgejo release.	—

Asset Examples

Single glob:

{
  "assets": "dist/*.js"
}

Include all .js files in the dist directory.

Multiple globs with negation:

{
  "assets": [["dist", "!**/*.css"]]
}

Include all files in dist and its subdirectories, excluding .css files.

Objects with labels:

{
  "assets": [
    {"path": "dist/MyLibrary.js", "label": "JS distribution"},
    {"path": "dist/MyLibrary.css", "label": "CSS distribution"}
  ]
}

Include specific files with custom labels.

Multiple file patterns:

{
  "assets": [
    "dist/**/*.js",
    "dist/**/*.css",
    {"path": "docs/README.md", "label": "Documentation"}
  ]
}

Note: File types may need to be allowed in your Forgejo instance's attachment settings (AttachmentAllowedTypes in the [attachment] scope).

CI / Forgejo Actions

Use this plugin in a Forgejo Actions workflow to auto-publish releases on every push to main.

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npm ci
      - run: npm run build
      - run: npx semantic-release
        env:
          FORGEJO_URL: "https://git.reslate.solutions"
          FORGEJO_TOKEN: ${{ secrets.FORGEJO_TOKEN }}

Note: Use runs-on: docker for Forgejo Actions (not ubuntu-latest).

Set FORGEJO_TOKEN (and optionally NPM_TOKEN if publishing to a package registry) in your repo's Settings → Secrets.

Package Registry Publishing

If you publish to a Forgejo npm registry, add an .npmrc:

@your-scope:registry=https://git.reslate.solutions/api/packages/ross/npm/
//git.reslate.solutions/api/packages/ross/npm/:_authToken=${NPM_TOKEN}

Then configure @semantic-release/npm in your .releaserc.json:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@ross/semantic-release-forgejo", {
      "forgejoUrl": "https://git.reslate.solutions"
    }]
  ]
}

Troubleshooting

Error: Cannot find module '@ross/semantic-release-forgejo'

Make sure the plugin is installed and your .releaserc.json uses the correct package name.

Error: ENOForgejoURL or Error: EForgejoTOKEN

Verify that FORGEJO_URL and FORGEJO_TOKEN environment variables are set in your CI environment.

Release not created

Check that the Forgejo token has push access to the repository. The token must be created under Settings → Applications → Generate New Token with appropriate permissions.

License

MIT