codfish/semantic-release-action

The Original GitHub Action for running semantic-release. Sets output and environment variables for you to use in subsequent actions.

semantic-release-action

GitHub Action for running semantic-release. Respects any semantic-release configuration file in your repo or the release prop in your package.json. Exports environment variables for you to use in subsequent actions containing version numbers.

Note: v3 of this action uses semantic-release v22 & node v20.9. v2 uses semantic-release v20 & node v18.7.

• Usage
  • Which Version to Use
• Why
• Configuration
  • Example with all inputs
  • Outputs
• Recipes
  • Including all commit types in a release
• Maintenance

Important

Check the release notes for help migrating to v3.

Usage

steps:
  - uses: actions/checkout@v3

  - uses: codfish/semantic-release-action@v3
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Using output variables set by semantic-release-action:

steps:
  - uses: actions/checkout@v3

  # you'll need to add an `id` in order to access output variables
  - uses: codfish/semantic-release-action@v3
    id: semantic
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - run: echo ${{ steps.semantic.outputs.release-version }}

  - run: echo "$OUTPUTS"
    env:
      OUTPUTS: ${{ toJson(steps.semantic.outputs) }}

  - uses: codfish/some-other-action@v1
    with:
      release-version: ${{ steps.semantic.outputs.release-version }}

Example: Only run an action if a new version was created.

steps:
  - uses: actions/checkout@v3

  # you'll need to add an `id` in order to access output variables
  - uses: codfish/semantic-release-action@v3
    id: semantic
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - name: docker push version
    if: steps.semantic.outputs.new-release-published == 'true'
    run: |
      docker tag some-image some-image:$TAG
      docker push some-image:$TAG
    env:
      TAG: v$RELEASE_VERSION

Using environment variables set by semantic-release-action:

steps:
  - uses: actions/checkout@v3

  - uses: codfish/semantic-release-action@v3
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - run: |
      echo $RELEASE_VERSION
      echo $RELEASE_MAJOR
      echo $RELEASE_MINOR
      echo $RELEASE_PATCH

If you're not publishing to npm and only want to use this action for GitHub releases, the easiest approach would simply be to add "private": true, to your package.json.

Which Version to Use

See action.yml.

steps:
  # Recommended: Docker image digest from GitHub Container Registry (best for speed & security)
  - uses: docker://ghcr.io/codfish/semantic-release-action@sha256:71048986f7e28f024cbad0ef106a7ef20b9b0d322f3a8aa51d89f1c424e75061

  # Major version of a release
  - uses: codfish/semantic-release-action@v3

  # Minor version of a release
  - uses: codfish/[email protected]

  # Specific commit
  - uses: codfish/semantic-release-action@ee5b4afec556c3bf8b9f0b9cd542aade9e486033

  # Git branch
  - uses: codfish/semantic-release-action@main

Note

Whenever you use a custom docker-based GitHub Action like this one, you may notice in your run logs, one of the first steps you'll see will be GA building the image for you. You can speed up runs by pulling pre-built docker images instead of making GitHub Actions build them on every run.

steps:
  # GitHub Container Registry
  - uses: docker://ghcr.io/codfish/semantic-release-action:v3

  # Dockerhub
  - uses: docker://codfish/semantic-release-action:v3

Tip

If you're security conscious, you can pin the docker image down to a specific digest instead of using an image tag, which is a mutable reference.

steps:
  # Docker image digest from GitHub Container Registry
  - uses: docker://ghcr.io/codfish/semantic-release-action@sha256:71048986f7e28f024cbad0ef106a7ef20b9b0d322f3a8aa51d89f1c424e75061

Where <digest> is any docker image digest you want here.

Why

It's fairly easy to run semantic-release as a "host action," aka something that runs directly on the VM.

steps:
  - run: npx semantic-release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

If you're just publishing a node package, then this could still work well for you. The problem I found with this is when I was in projects where I had subsequent steps/actions in which I wanted to know whether a new version was cut.

Use Case: For instance, in an application where I'm using semantic-release to manage GitHub releases, but also building and pushing docker images. Dockerhub has a nice GitHub integration to handle this for us, but some other registries do not. If I need to cut a new release, then update a docker registry by adding a new tagged build, I'll want to run semantic-release and then build a docker image, tag it with a version and push it up. In my case I like to push up tags for latest, the semver (i.e. v1.8.3), and just the major the version (i.e. v1).

I want to know 1) if semantic-release cut a new version and 2) what the version is.

There's a number of ways to handle this, but the most elegant way I found to do it was to abstract it into it's own custom action. It abstracts away whatever logic you need to figure out what that new release number is.

This also scales well, just in case I want to add some flexibility and functionality to this action, I can easily leverage it across any project.

Configuration

You can pass in semantic-release configuration options via GitHub Action inputs using with.

It's important to note, NONE of these inputs are required. Semantic release has a default configuration that it will use if you don't provide any.

Also of note, if you'd like to override the default configuration, and you'd rather not use the inputs here, the action will automatically use any semantic-release configuration defined in your repo (.releaserc, release.config.js, release prop in package.json)

Note

Each input will take precedence over options configured in the configuration file and shareable configurations.

Input Variable	Type	Description	Default
branches	Array, String, Object	The branches on which releases should happen. Our default mimic's semantic-release's, with one major inclusion: the main branch.	['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]
plugins	Array	Define the list of plugins to use. Plugins will run in series, in the order defined, for each steps if they implement it	Semantic default
extends	Array, String	List of modules or file paths containing a shareable configuration.	Semantic default
additional-packages	Array, String	Define a list of additional plugins/configurations (official or community) to install. Use this if you 1) use any plugins other than the defaults, which are already installed along with semantic-release or 2) want to extend from a shareable configuration.	[]
dry-run	Boolean	The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, success and fail.	Semantic default
repository-url	String	The git repository URL	Semantic default
tag-format	String	The Git tag format used by semantic-release to identify releases.	Semantic default

Note

Any package specified in extends or additional-packages will be installed automatically for you as a convenience, allowing you to use this action without adding new dependencies to your application or install deps in a separate action step.

Note

additional-packages won't get used automatically, setting this variable will just install them so you can use them. You'll need to actually list them in your plugins and/or extends configuration for semantic-release to use them.

Note

The branch input is DEPRECATED. Will continue to be supported for v1. Use branches instead. Previously used in semantic-release v15 to set a single branch on which releases should happen.

• GitHub Actions Inputs: https://help.github.com/en/articles/metadata-syntax-for-github-actions#inputs
• Semantic Release Configuration: https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md

Example with all inputs

steps:
  - run: codfish/semantic-release-action@v3
    with:
      dry-run: true
      branches: |
        [
          '+([0-9])?(.{+([0-9]),x}).x',
          'main',
          'next',
          'next-major',
          {
            name: 'beta',
            prerelease: true
          },
          {
            name: 'alpha',
            prerelease: true
          }
        ]
      repository-url: https://github.com/codfish/semantic-release-action.git
      tag-format: 'v${version}'
      extends: '@semantic-release/apm-config'
      additional-packages: |
        ['@semantic-release/[email protected]', '@semantic-release/git']
      plugins: |
        ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/github', '@semantic-release/apm', '@semantic-release/git']
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Outputs

semantic-release-action sets both output variables and environment variables because why not? Allows users the ability to use whichever they want. I don't know or understand every use case there might be so this is a way to cover more cases.

Docs: https://help.github.com/en/articles/metadata-syntax-for-github-actions#outputs

Output Variables

Output Variable	Description
new-release-published	Either 'true' when a new release was published or 'false' when no release was published. Allows other actions to run or not-run based on this
release-version	The new releases' semantic version, i.e. 1.8.3
release-major	The new releases' major version number, i.e. 1
release-minor	The new releases' minor version number, i.e. 8
release-patch	The new releases' patch version number, i.e. 3
release-notes	The release notes of the next release.
type	The semver export type of the release, e.g. major, prerelease, etc.
channel	The release channel of the release.
git-head	The git hash of the release.
git-tag	The version with v prefix.
name	The release name.

Environment Variables

Environment Variable	Description
NEW_RELEASE_PUBLISHED	Either 'true' when a new release was published or 'false' when no release was published. Allows other actions to run or not-run based on this
RELEASE_VERSION	The new releases' semantic version, i.e. 1.8.3
RELEASE_MAJOR	The new releases' major version number, i.e. 1
RELEASE_MINOR	The new releases' minor version number, i.e. 8
RELEASE_PATCH	The new releases' patch version number, i.e. 3
RELEASE_NOTES	The release notes of the next release in markdown.
RELEASE_TYPE	The semver export type of the release, e.g. major, prerelease, etc.
RELEASE_CHANNEL	The release channel of the release.
RELEASE_GIT_HEAD	The git hash of the release.
RELEASE_GIT_TAG	The version with v prefix.
RELEASE_NAME	The release name.

Recipes

Including all commit types in a release

By default, semantic-release only includes fix, feat, and perf commit types in the release. A lot of projects want to include all commit types in their release notes, while still using semantic-release's commit analyzer to only create releases for fix, feat, and perf commits.

- run: codfish/semantic-release-action@v3
  with:
    additional-packages: ['conventional-changelog-conventionalcommits@7']
    plugins: |
      [
        '@semantic-release/commit-analyzer',
        [
          "@semantic-release/release-notes-generator",
          {
            "preset": "conventionalcommits",
            "presetConfig": {
              "types": [
                { type: 'feat', section: 'Features', hidden: false },
                { type: 'fix', section: 'Bug Fixes', hidden: false },
                { type: 'perf', section: 'Performance Improvements', hidden: false },
                { type: 'revert', section: 'Reverts', hidden: false },
                { type: 'docs', section: 'Other Updates', hidden: false },
                { type: 'style', section: 'Other Updates', hidden: false },
                { type: 'chore', section: 'Other Updates', hidden: false },
                { type: 'refactor', section: 'Other Updates', hidden: false },
                { type: 'test', section: 'Other Updates', hidden: false },
                { type: 'build', section: 'Other Updates', hidden: false },
                { type: 'ci', section: 'Other Updates', hidden: false }
              ]
            }
          }
        ],
        '@semantic-release/npm',
        '@semantic-release/github'
      ]

This configuration uses the conventional-changelog-conventionalcommits package to generate release notes & configures @semantic-release/release-notes-generator to include all commit types. Tweaking the types array will allow you to include or exclude specific commit types & group them to your liking.

Important

This example uses the additional-packages input to install the conventional-changelog-conventionalcommits package. This is necessary because semantic-release doesn't install it by default & it's required for the customization of the presetConfig in the @semantic-release/release-notes-generator plugin.

Maintenance

Make the new release available to those binding to the major version tag: Move the major version tag (v2, v3, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.

git tag -fa v3 -m "Update v3 tag" && git push origin v3 --force

Reference: https://github.com/actions/toolkit/blob/main/docs/action-versioning.md#recommendations

semantic-release-action's Issues

Pre-built Docker image

Problem

Currently the Docker image for the action is built ad-hoc for each execution. Given that it installs npm modules, it takes around a 45-60 seconds on average.

Suggestion

I would suggest building this image and pushing it to DockerHub (and also Quay.io given the restrictions DockerHub is about to enable) so that the image is just pulled. AFAIK GitHub caches some of the Docker images in their infra which would make it even faster.

Error in semantic-release/github: Cookies must be enabled to use GitHub

Current behavior

Action always errors with:

Failed step "publish" of plugin "@semantic-release/github"
✖ An error occurred while running semantic-release: RequestError [HttpError]: Cookies must be enabled to use GitHub.

Expected behavior

GitHub publish should work

Notes

Seems to be related to: semantic-release/github#271

Environment

• semantic-release version: master (1.3.1)
• CI environment: GitHub actions
• Plugins used: /
• semantic-release configuration:

on:
  push:
    branches: [master]
jobs:
  version-bumb-and-tag:
    name: Version bumb and tag
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - uses: codfish/semantic-release-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}```

- CI logs:

```[10:49:42 AM] [semantic-release] › ✔  Completed step "publish" of plugin "@semantic-release/npm"
[10:49:42 AM] [semantic-release] › ℹ  Start step "publish" of plugin "@semantic-release/github"
[10:49:42 AM] [semantic-release] › ✖  Failed step "publish" of plugin "@semantic-release/github"
[10:49:42 AM] [semantic-release] › ✖  An error occurred while running semantic-release: RequestError [HttpError]: Cookies must be enabled to use GitHub.
    at /action/node_modules/@octokit/request/dist-node/index.js:66:23
    at processTicksAndRejections (internal/process/task_queues.js:97:5) {
  status: 403,```

Feature request: Change working directory

This is a feature request to customize what directory to run semantic release in. This is useful when compiling a dist folding and wanting to only publish that.

Semantic-release/npm has a pkgRoot option available https://github.com/semantic-release/npm#options

And there is also a cwd accepted https://github.com/semantic-release/semantic-release/blob/master/index.js#L250

I'm not exactly sure which is needed for this though.

Update documentation to improve examples

PENDING: Github actions update in second week of september actions/toolkit#96

steps:
  - uses: actions/checkout@master

  # you'll need to add an `id` in order to access output variables
  - uses: codfish/semantic-release-action@master
    id: semantic
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - name: docker push version
    if: steps.semantic.outputs.new-release-published == "true"
    run: |
      docker tag $DOCKER_REGISTRY/your-image $DOCKER_REGISTRY/your-image:$TAG
      docker push $DOCKER_REGISTRY/your-image:$TAG
    env:
      DOCKER_REGISTRY: ${{ secrets.DOCKER_REGISTRY }}
      TAG: v$RELEASE_VERSION

Upgrade to node LTS version (v16) base image in Dockerfile

As of today, v14 is in Maintenance mode and v16 is the active LTS version.

https://nodejs.org/en/about/releases/

Is there a reason you use v12 in the Docker image? Would you mind to bump to v16?

GitHub url defaults to interactive front-end

Hi, I am using the action in a couple of my repositories and the action started throwing the following error:

[10:08:30 AM] [semantic-release] › ✖  An error occurred while running semantic-release: RequestError [HttpError]: Cookies must be enabled to use GitHub.
    at /action/node_modules/@octokit/request/dist-node/index.js:66:23
    at processTicksAndRejections (internal/process/task_queues.js:97:5) {
  status: 403,
...

It looks like it's a bug in semantic-release/github. I have filed an issue in their repository. For others, just adding how to mitigate this:

      - name: "Determine release version"
        uses: codfish/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_URL: "https://api.github.com" # This overrides the default value

Container size

When built/pulled the container ends up being 1.16GB which slows down our CI. By switching it to use node-alpine it can be reduced to 297MB and possibly further if the Dockerfile is modified more (However I haven't tried to optimise it further as it stands).

notify

hello world

Error: Cannot find module '@semantic-release/changelog'

Does anyone knows the reason?

[3:10:00 PM] [semantic-release] › ℹ Running semantic-release version 17.0.7
[3:10:00 PM] [semantic-release] › ✖ An error occurred while running semantic-release: Error: Cannot find module '@semantic-release/changelog'

Installing extra plugin

If I were to use an extra plugin that this action doesn't use, by default, it does not install it. Is this expected? Feels like this action could install all plugins defined.

Deprecated set-output

I'm getting the following warning even after bumping up to v2:

Here's the link in the image, in case it's helpful: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/

Support NPM config environment variables

I have a workflow running on a GitHub Enterprise runner and need to override certain NPM directories/files like ~/.npm and ~/.npmrc.

The step below shows the environment variables I use in other actions. But for some reason the default ~/.npm location is being used instead of /home/github/npm_cache. If I exec into the container running this job, and set those environment variables manually, /home/github/npm_cache will be used correctly.

Does anyone know if these environment variables, NPM_CONFIG_PREFIX and NPM_CONFIG_GLOBALCONFIG, can be used with this action? Or another way to override them?

      - name: NPM configuration
        run: |
          echo '${{ secrets.NPMRC }}' | base64 -d > /home/github/.npmrc
          echo 'cache=/home/github/npm_cache' >> /home/github/.npmrc

      - name: Semantic Release
        id: semantic-release
        uses: codfish/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          GIT_CONFIG_GLOBAL: /home/github/.gitconfig
          NPM_CONFIG_PREFIX: /home/github/node_modules
          NPM_CONFIG_GLOBALCONFIG: /home/github/.npmrc
        with:
          branches: |
            [
              "main"
            ]
          additional_packages: |
            [
              "@google/semantic-release-replace-plugin",
              "@semantic-release/git"
            ]
          plugins: |
            [
              "@semantic-release/commit-analyzer",
              "@semantic-release/release-notes-generator",
              ["@semantic-release/github", {
                "githubUrl": "https://test.github.example.com",
                "githubApiPathPrefix": "/api/v3"
              }],
              ["@google/semantic-release-replace-plugin", {
                "replacements": [
                  {
                    "files": ["Chart.yaml"],
                    "from": "version: .*",
                    "to": "version: ${nextRelease.version}",
                    "results": [
                      {
                        "file": "Chart.yaml",
                        "hasChanged": true,
                        "numMatches": 1,
                        "numReplacements": 1
                      }
                    ],
                    "countMatches": true
                  }
                ]
              }],
              ["@semantic-release/git", {
                  "assets": ["Chart.yaml"]
              }]
            ]

release.config.js is not respected

I get the following message in the CI:

[7:55:03 PM] [semantic-release] › ℹ  Running semantic-release version 22.0.5
...
...
...
[7:55:05 PM] [semantic-release] › ℹ  This test run was triggered on the branch develop, while semantic-release is configured to only publish from main, therefore a new version won’t be published.

I want to release in the develop branch therefore my release.config.js is:

/**
 * @type {import('semantic-release').GlobalConfig}
 */
module.exports = {
  branches: ["develop"],
  // ...
};

Lifecycle scripts are not running

I'm trying to run a script in the NPM prepack lifecycle hook script, as recommended by the semantic release docs, to sign the artifacts right before they are packed for publishing.

It executes fine when running semantic-release locally, but not when running in this action. Here's an example of the error message being returned:
https://github.com/47ng/sceau/actions/runs/3685799334/jobs/6237204982#step:8:66

npm WARN lifecycle [email protected]~prepack: cannot run in wd [email protected] node ./dist/cli.js sign (wd=/github/workspace)

A possible lead could be user permissions when running in a Docker context:
https://stackoverflow.com/questions/57008653/why-does-npm-not-run-prepublishonly-in-docker

test

deprecation warning for set-env

Error: The `set-env` command is deprecated and will be disabled on November 16th. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/

Do the maintainers of this project have plans to fix this before the deadline?

Does branch input do anything?

I was looking through this action and found myself confused by the branch input that it accepts. I couldn't find any documentation for it from semantic-release, just branches.

I think part of my confusion stems from the fact that I am new to semantic-release. I checked their release notes and noticed that in version 16 they dropped branch in favor of branches.

If I'm understanding correctly how GitHub Actions works, this action will always use ^17.x.x, according to its package.json. I think this all points to the branch input not doing anything and should be removed?

---

Possibly moot, but what was the use case for this? It seems likes it's just overriding .releaserc, so I think I'm still missing something.

Add `branch` input

weird analysis behaviour

Hey,

I've been using this action for a while now but today I'm encountering something weird:

Even though I have a bunch of commits that should trigger a new release, this happens on the analyze step and then nothing.

I've tried v2.0.0 to v3 (the latter broke in a different way) but nothing worked. This exact actions file has worked before with 2.2.0 which this log is for.
Any ideas?

Outputs should get set even when no new release is created

I think it would be better if the release-version and other outputs would be set to the calculated version even if no new release is created.
Or at least it should be noted in the readme that this is not the case.

BreakingChange: not working

Helo Team,

Thanks for the useful action.

I'm trying to release major of my app. when I add "Breaking Change:" in my commit the major version is not getting updated. I tried all the below things.

BREAKING CHANGE:
BREAKING CHANES:
! BREAKING CHANGE:
Also tried adding commit analyzer plugin and rules

Nothing works. Please guide me on how to bump up major version using the codefish action

Alpine image DNS issues

https://www.google.com/search?q=Alpine+image+DNS+issues&oq=Alpine+image+DNS+issues&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIKCAEQABiABBiiBDIKCAIQABiABBiiBNIBBzE1OWowajeoAgCwAgA&sourceid=chrome&ie=UTF-8#ip=1

Follow up to #202.

Should migrate to slim image to achieve close to same results with less risk.

CC @rdash99

v2 causes permission issues on self hosted runners

When upgrading from v1 to v2, running this action on self-hosted runners causes the cloned repo on the runner to be owned by root, causing subsequent runs of the same workflow to fail, due to not having enough permissions to access the repo on the runner.

On initial runs of a workflow containing this action, the repo is checked out, owned by the user the runner is installed in. This action then modifies the repo to be owned by root. The next time the same workflow is ran, it is not able to checkout the repo, due to not having enough permission to modify the cloned repo on the runner.

This is confirmed by sshing into the runner itself, and checking the permissions of the cloned repo

Testing notifications

hello

Feature request: Add noci option

We have a use case where we need to evaluate the next version of a build for short-lived/feature branches and during PR.

It works for feature branches when setting dry_run: true but for PR, we also need to set noCI so semantic-release could evaluate the release and not throwing an error.

It would be nice if this action could support any core options.

Regards,