@open-sauced/release

semantic-release shareable config to publish to npm and/or ghcr. now with alpha and beta pre-releases

📦 Plugins

This shareable configuration use the following plugins:

🖥️ Requirements

Most important limitations are:

GITHUB_TOKEN for everything
NPM_TOKEN for public npm library
docker containers need to be built beforehand

You can skip here if you are using elevated Private Access Token, however we don't recommend going down that path.

No force push or admin cherries branch protections for the following branches:

main - required
alpha - optional, pre-release branch
beta - optional, pre-release branch
next - optional, next channel
next-major - optional, next major
vX[.X.X] - maintenance releases

If you use more than the main branch, optionally create an environment that is limiting where pushes can come from and enable the merge strategy.

We are using production in our examples, if you copy paste them you will find this new environment generated in your settings! 🍕

🧪 GitHub actions usage

Since version 3 it is possible to use semantic-release without any trace of it or the open-sauced configuration anywhere in the dependency tree.

Docker containers are pushed as part of the release so they mirror the availability of npm packages.

The simplest use case for a typical NPM package, almost zero install downtime from ghcr and no more local tooling:

name: "Release container"

on:
  push:
    branches:
      - main
      - next
      - next-major
      - alpha
      - beta

jobs:
  release:
    environment:
      name: production
      url: https://github.com/${{ github.repository }}/releases/tag/${{ env.RELEASE_TAG }}
    runs-on: ubuntu-latest
    steps:
      - name: "☁️ checkout repository"
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: "🚀 release"
        id: semantic-release
        uses: docker://ghcr.io/open-sauced/release:1.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: '♻️ cleanup'
        run: |
          echo ${{ env.RELEASE_TAG }}
          echo ${{ env.RELEASE_VERSION }}

Marketplace actions should default to the major tag and are essentially more stable as we have to curate every release.

A more traditional approach, only thing really different here is a minor pull overhead and using set outputs instead of environment variables:

name: "Release"

on:
  push:
    branches:
      - main
      - next
      - next-major
      - alpha
      - beta

jobs:
  release:
    environment:
      name: production
      url: https://github.com/${{ github.repository }}/releases/tag/${{ steps.semantic-release.outputs.release-tag }}
    runs-on: ubuntu-latest
    steps:
      - name: "☁️ checkout repository"
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: "🚀 release"
        id: semantic-release
        uses: open-sauced/release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: '♻️ cleanup'
        run: |
          echo ${{ steps.semantic-release.outputs.release-tag }}
          echo ${{ steps.semantic-release.outputs.release-version }}

📦 NPM usage

You can opt to use this package in your local tooling. Proceed as you would normally would, replacing npm with your package manager of choice and install the package:

npm install --save-dev @open-sauced/release

The shareable config can then be configured in the semantic-release configuration file:

{
  "extends": "@open-sauced/release"
}

Now all you need to do is create a release:

npx semantic-release

🏗️ GitHub general usage

If you do not plan to publish to npm or ghcr but still want to cut tags and GitHub releases with this system, you can specify SKIP_NPM_PUBLISH and SKIP_DOCKER_PUBLISH. This will still publish releases, generate semver tags, and generate GitHub release notes. But it will skip attempting to publish

Then, in a separate GitHub action, you can watch for the releases and upload assets manually. For example, when building a Go application:

name: Semantic release

on:
  push:
    branches:
      - main
      - beta
  workflow_dispatch:

jobs:
  release:
    name: Semantic release
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: "☁️  checkout repository"
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: "🚀 release"
        id: semantic-release
        env:
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
          SKIP_NPM_PUBLISH: true
          SKIP_DOCKER_PUBLISH: true
        uses: open-sauced/release@v2

    outputs:
        release-tag: ${{ steps.semantic-release.outputs.release-tag }}

  build:
    needs:
      - release
    runs-on: ubuntu-latest
    permissions:
      contents: write # release changes require contents write

    steps:
    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: 1.21

    - name: Check out code
      uses: actions/checkout@v3

    - name: Build and upload Go binaries
      env:
        GH_TOKEN: ${{ github.token }}
      run: |
        go build -o build/my-go-binary
        gh release upload ${{ needs.release.outputs.release-tag }} build/my-go-binary

🔧 Configuration

See each plugin documentation for required installation and configuration steps.

NPM

Set private to true in package.json if you want to disable npm, or, change the scope of package using publishConfig.

Keep one of files or main keys in your package.json accurate depending on whether you are building a library or an application.

If you publish, make sure to also provide a valid NPM_TOKEN as .npmrc authentication is ignored in our config!

To configure the directory for publishing, you have the option to set a path value to NPM_PACKAGE_ROOT. By default, it is set to ".".

GitHub Actions

Unless you have an action.yml present in your root folder, this module is not added to the release config.

If you have an action.yml present, our config will attempt to adjust the container version to the newly pushed npm and docker tags.

Manifest.json

Unless you have a manifest.json present in your root folder, this module is not added to the release config.

If you have a manifest.json present, our config will attempt to adjust the version value to the newly pushed npm and docker tags. This version bump is limited to releases made exclusively on the main branch.

Docker

Unless you have a Dockerfile present in your root folder, this module is not added to the release config.

If you have a Dockerfile present, our config will attempt to push to ghcr.io.

CHANGELOG

By default, a CHANGELOG.md file is generated and committed to document the changes introduced in releases.

This can be skipped by setting SKIP_CHANGELOG=true.

Environment variables

Using our configuration comes with some sensible defaults:

DOCKER_USERNAME=$GITHUB_REPOSITORY_OWNER
DOCKER_PASSWORD=$GITHUB_TOKEN
GIT_COMMITTER_NAME="open-sauced[bot]"
GIT_COMMITTER_EMAIL="63161813+open-sauced[bot]@users.noreply.github.com"
GIT_AUTHOR_NAME - parsed from commit $GITHUB_SHA
GIT_AUTHOR_EMAIL - parsed from commit $GITHUB_SHA

Feel free to change any of the above to whatever suits your purpose, our motivation is to keep GITHUB_TOKEN and/or NPM_TOKEN the only necessary requirements.

We are actively investigating ways to drop the 2 remaining variables as well!

🤝 Contributing

We encourage you to contribute to Open Sauced! Please check out the Contributing guide for guidelines about how to proceed.

If you decide to fix a bug, make sure to use the conventional commit available at:

npm run push

🍕 Community

Got Questions? Join the conversation in our Discord.
Find Open Sauced videos and release overviews on our YouTube Channel.

open-sauced/release