npm package: @ribbon-studios/semantic-release-forgejo
Description: semantic-release plugin to publish a Forgejo release
Latest version: 0.1.3

# @ribbon-studios/semantic-release-forgejo

[![NPM Latest Version][npm-version-image]][npm-url]
[![Coverage][coverage-image]][coverage-url]

[![CI Build][build-image]][build-url]
[![Semantic Release][semantic-release-image]][semantic-release-url]
[![Code Style: Prettier][code-style-image]][code-style-url]

[**semantic-release**][semantic-release-url] plugin to publish a Forgejo release.

| Step               | Description                                                                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verifyConditions` | Verify the presence and the validity of the authentication (set via [environment variables](#environment-variables)) and the other [options](#options) configuration. |
| `publish`          | Publish a Forgejo Release, optionally uploading file assets.                                                                                                          |
| `addChannel`       | Update a Forgejo Release's `pre-release` field.                                                                                                                       |

## Install

```sh
$ bun add -D @ribbon-studios/semantic-release-forgejo
```

## Usage

The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@ribbon-studios/semantic-release-forgejo",
      {
        "assets": [
          { "path": "dist/asset.min.css", "name": "CSS distribution" },
          { "path": "dist/asset.min.js", "name": "JS distribution" }
        ]
      }
    ]
  ]
}
```

With this example Forgejo releases will be published with the file `dist/asset.min.css` and `dist/asset.min.js`.

## Configuration

### Forgejo authentication

The Forgejo authentication configuration is **required** and can be set via [environment variables](#environment-variables).

When creating the token, the **minimum required permissions** are:

- "Repository" > "Read and Write"
- Repository and Organization Access must be set to "All" for private repos.

When using the `${{ forgejo.token }}`, the **minimum required permissions** are:

- `contents: write` to be able to publish a Forgejo release

### Environment variables

| Variable        | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `FORGEJO_TOKEN` | **Required.** The token used to authenticate with Forgejo. |
| `FORGEJO_URL`   | The Forgejo server endpoint.                               |

### Options

| Option         | Description                                                                                                        | Default                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `forgejoUrl`   | The Forgejo server endpoint.                                                                                       | `FORGEJO_URL` environment variable. |
| `assets`       | An array of files to upload to the release.                                                                        | -                                   |
| `draftRelease` | A boolean indicating if a Forgejo Draft Release should be created instead of publishing an actual Forgejo Release. | `false`                             |

[npm-url]: https://www.npmjs.com/package/@ribbon-studios/semantic-release-forgejo
[npm-version-image]: https://img.shields.io/npm/v/@ribbon-studios/semantic-release-forgejo/latest.svg
[npm-version-next-image]: https://img.shields.io/npm/v/@ribbon-studios/semantic-release-forgejo/next.svg
[npm-version-beta-image]: https://img.shields.io/npm/v/@ribbon-studios/semantic-release-forgejo/beta.svg
[build-image]: https://codeberg.org/ribbon-studios/semantic-release-forgejo/badges/workflows/ci.yml/badge.svg?branch=main
[build-url]: https://codeberg.org/ribbon-studios/semantic-release-forgejo/actions?workflow=ci.yml&branch=main
[coverage-image]: https://ribbon-studios.codeberg.page/semantic-release-forgejo/badge.svg
[coverage-url]: https://ribbon-studios.codeberg.page/semantic-release-forgejo
[code-style-image]: https://img.shields.io/badge/code%20style-prettier-ff69b4.svg
[code-style-url]: https://prettier.io
[semantic-release-url]: https://github.com/semantic-release/semantic-release
[semantic-release-image]: https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079