Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
https://github.com/cycjimmy/semantic-release-action

GitHub Action for Semantic Release
https://github.com/cycjimmy/semantic-release-action
actions github-actions semantic-release
Last synced: about 1 month ago
JSON representation
GitHub Action for Semantic Release
Host: GitHub
URL: https://github.com/cycjimmy/semantic-release-action
Owner: cycjimmy
License: mit
Created: 2019-10-17T11:26:28.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2024-04-30T07:54:44.000Z (about 2 months ago)
Last Synced: 2024-05-05T15:01:13.329Z (about 2 months ago)
Topics: actions, github-actions, semantic-release
Language: JavaScript
Homepage: https://github.com/marketplace/actions/action-for-semantic-release
Size: 654 KB
Stars: 489
Watchers: 3
Forks: 97
Open Issues: 20
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Lists

awesome-workflows - Action For Semantic Release
awesome-actions - Action For Semantic Release
awesome-ccamel - cycjimmy/semantic-release-action - GitHub Action for Semantic Release (JavaScript)
awesome - cycjimmy/semantic-release-action - GitHub Action for Semantic Release (JavaScript)
awesome-actions - Action For Semantic Release
fucking-awesome-actions - Action For Semantic Release
awesome-actions-fork - Action For Semantic Release
awesome-actions - Action For Semantic Release
awesome-actions - Action For Semantic Release
README

        # Semantic Release Action

![][version-image]

![][workflows-badge-image]

[![Release date][release-date-image]][release-url]

[![semantic-release][semantic-image]][semantic-url]

[![npm license][license-image]][license-url]

GitHub Action for [Semantic Release][semantic-url].

## Usage

### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.

### Step2: [Add Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.

### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.

#### Basic Usage:

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

**IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.

If you are using this action for protected branches, replace `GITHUB_TOKEN` with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part of `actions/checkout@v4` by setting the parameter `persist-credentials: false`. This credential does not have the required permission to operate on protected branches.

#### Private Packages

If you are using this action to publish to the npm [GitHub Packages Registry][github-packages-registry],

then make sure that you configure this in your `package.json` file:

```json

{

  "publishConfig": {

    "registry": "https://npm.pkg.github.com"

  }

}

```

### Inputs

|  Input Parameter  | Required | Description                                                                                                              |

|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------|

| semantic_version  |  false   | Specify version range for semantic-release. [[Details](#semantic_version)]                                               |

|     branches      |  false   | The branches on which releases should happen.[[Details](#branches)]
Support for **semantic-release above v16**.       |

|      branch       |  false   | The branch on which releases should happen.[[Details](#branch)]
Only support for **semantic-release older than v16**. |

|   extra_plugins   |  false   | Extra plugins for pre-install. [[Details](#extra_plugins)]                                                               |

|      dry_run      |  false   | Whether to run semantic release in `dry-run` mode. [[Details](#dry_run)]                                                 |

|        ci         |  false   | Whether to run semantic release with CI support. [[Details](#ci)]
Support for **semantic-release above v16**.         |

|      extends      |  false   | Use a sharable configuration [[Details](#extends)]                                                                       |

| working_directory |  false   | Use another working directory for semantic release [[Details](#working_directory)]                                       |

|    tag_format     |  false   | Specify format of tag (useful for monorepos)                                                                             |

|  repository_url   |  false   | The Git repository url. If no repository url specified, current repository will be used by default.                      |

#### semantic_version

> {Optional Input Parameter} Specify version range for semantic-release.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      semantic_version: 19.0.5  # It is recommended to specify a version range

                                # for semantic-release when using

                                # semantic-release-action lower than @v4

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

If no version range is specified with `cycjimmy/semantic-release-action@v4` then [semantic-release](https://github.com/semantic-release/semantic-release/) version [21.1.1](https://github.com/semantic-release/semantic-release/releases/tag/v21.1.1) is used.

#### branches

> {Optional Input Parameter} The branches on which releases should happen.
`branches` supports for **semantic-release above v16**.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      semantic_version: 16

      # you can set branches for semantic-release above v16.

      branches: |

        [

          '+([0-9])?(.{+([0-9]),x}).x',

          'master',

          'next',

          'next-major',

          {

            name: 'beta',

            prerelease: true

          },

          {

            name: 'alpha',

            prerelease: true

          }

        ]

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

`branches` will override the `branches` attribute in your configuration file. If the attribute is not configured on both sides, the default is:

```

[

  '+([0-9])?(.{+([0-9]),x}).x',

  'master',

  'next',

  'next-major',

  {name: 'beta', prerelease: true},

  {name: 'alpha', prerelease: true}

]

```

See [configuration#branches](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches) for more information.

#### branch

> {Optional Input Parameter} Similar to parameter `branches`. The branch on which releases should happen.
`branch` only supports for **semantic-release older than v16**.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      semantic_version: 15.13.28

      # you can set branch for semantic-release older than v16.

      branch: your-branch

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

It will override the `branch` attribute in your configuration file. If the attribute is not configured on both sides, the default is `master`.

#### extra_plugins

> {Optional Input Parameter} Extra plugins for pre-install.

The action can be used with `extra_plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array.

For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra_plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow:

Github Action Workflow:

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      # You can specify specifying version range for the extra plugins if you prefer.

      extra_plugins: |

        @semantic-release/[email protected]

        @semantic-release/git

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

Similar to parameter `semantic_version`. *It is recommended to manually specify a version of semantic-release plugins to prevent errors caused.*

Release Config:

```diff

  plugins: [

    .

+   "@semantic-release/changelog"

+   "@semantic-release/git",

  ]

```

#### dry_run

> {Optional Input Parameter} Whether to run semantic release in `dry-run` mode.
It will override the dryRun attribute in your configuration file.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      dry_run: true

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

#### ci

> {Optional Input Parameter} Whether to run semantic release with CI support (default true).
`ci` supports for **semantic-release above v16**.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      ci: false

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

`ci` can be used, e.g in combination with `dry_run` when generating the next release version in pull requests, where `semantic_release` would normally block the execution.

#### extends

The action can be used with `extends` option to extend an existing [sharable configuration](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations) of semantic-release. Can be used in combination with `extra_plugins`.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      # You can extend an existing shareable configuration.

      # And you can specify version range for the shareable configuration if you prefer.

      extends: |

        @semantic-release/apm-config@^9.0.0

        @mycompany/override-config

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

#### working_directory

This action run semantic release in the github provided workspace by default. You can override it by setting another working directory.

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      # You can select another working directory like a subdirectory for example.

      working_directory: ./code

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

#### tag_format

The default tag format on semantic-release is `v{version}`. You can override that behavior using this option (helpful when you are using monorepos)

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    with:

      tag_format: custom-v${version}

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

```

### Outputs

|     Output Parameter      | Description                                                                                                                       |

|:-------------------------:|-----------------------------------------------------------------------------------------------------------------------------------|

|   new_release_published   | Whether a new release was published. The return value is in the form of a string. (`"true"` or `"false"`)                         |

|    new_release_version    | Version of the new release. (e.g. `"1.3.0"`)                                                                                      |

| new_release_major_version | Major version of the new release. (e.g. `"1"`)                                                                                    |

| new_release_minor_version | Minor version of the new release. (e.g. `"3"`)                                                                                    |

| new_release_patch_version | Patch version of the new release. (e.g. `"0"`)                                                                                    |

|    new_release_channel    | The distribution channel on which the last release was initially made available (undefined for the default distribution channel). |

|     new_release_notes     | The release notes for the new release.                                                                                            |

| new_release_git_head      | The sha of the last commit being part of the new release |

| new_release_git_tag       | The Git tag associated with the new release. |

| last_release_version      | Version of the previous release, if there was one. (e.g. `1.2.0`) |

| last_release_git_head     | The sha of the last commit being part of the last release, if there was one. |

| last_release_git_tag      | The Git tag associated with the last release, if there was one. |                                                         |

#### Using Output Variables:

```yaml

steps:

  - name: Checkout

    uses: actions/checkout@v4

  - name: Semantic Release

    uses: cycjimmy/semantic-release-action@v4

    id: semantic   # Need an `id` for output variables

    env:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - name: Do something when a new release published

    if: steps.semantic.outputs.new_release_published == 'true'

    run: |

      echo ${{ steps.semantic.outputs.new_release_version }}

      echo ${{ steps.semantic.outputs.new_release_major_version }}

      echo ${{ steps.semantic.outputs.new_release_minor_version }}

      echo ${{ steps.semantic.outputs.new_release_patch_version }}

```

## Changelog

See [CHANGELOG][changelog-url].

## License

This project is released under the [MIT License][license-url].

[version-image]: https://img.shields.io/github/package-json/v/cycjimmy/semantic-release-action

[workflows-badge-image]: https://github.com/cycjimmy/semantic-release-action/workflows/Test%20Release/badge.svg

[release-date-image]: https://img.shields.io/github/release-date/cycjimmy/semantic-release-action

[release-url]: https://github.com/cycjimmy/semantic-release-action/releases

[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg

[semantic-url]: https://github.com/semantic-release/semantic-release

[license-image]: https://img.shields.io/npm/l/@cycjimmy/semantic-release-action.svg

[license-url]: https://github.com/cycjimmy/semantic-release-action/blob/main/LICENSE

[changelog-url]: https://github.com/cycjimmy/semantic-release-action/blob/main/docs/CHANGELOG.md

[github-packages-registry]: https://github.com/features/packages