Releaser

A tool to create releases for your Node.js projects. It works like a charm with monorepos!

Inspired by release-please, Releaser is a CLI tool that automates the process of creating releases for your Node.js projects. It works with monorepos and follows the Conventional Commits specification.

Advantages of Releaser over other release automation tools:

• Speed: Releaser is optimized for speed, allowing you to create releases quickly and efficiently. It need just a few seconds locally to run the github action! By comparison, other release automation tools can take several minutes to complete the release process.
• Monorepo support: Releaser is designed to work with monorepos, allowing you to manage releases for multiple packages within a single repository.
• Conventional Commits support: Releaser adheres to the Conventional Commits specification, ensuring that your release notes are structured and easy to understand.

Features

• Create releases for your Node.js projects.
• Supports monorepos.
• Follows the Conventional Commits specification.
• Automatically creates Git tags for the new versions.
• Automatically updates the CHANGELOG.md file.
• Automatically updates the package.json file.
• Automatically updates the version in extra files.
• Optionally creates a pull request with the release notes.
• Optionally creates a tag for the new versions and deploys the new version to a specified environment.

Note: While Releaser currently supports Node.js projects, support for other languages could be added in the future through custom adapters. Stay tuned for updates!

Setup

$ npm install -g releaser-cli

Create a releaser-manifest.json file in the root of your project.

[
  {
    "path": "packages/api", // path to the package
    "extraFiles": ["packages/api/index.js"] // optional: extra files to be updated. You need to comment // x-releaser-version on the lines you want to update
    "dependencies": ["shared"] // optional: name of the packages that this package depends on
  },
  {
    "path": "packages/shared"
  }
]

See the example for a complete example.

Usage

$ releaser [environment]

Options: --tag: Create a tag for the new versions --dry-run: Dry run mode. No changes will be made.

Usage with Github Actions

1. Create a PAT token as described above.
2. Add the PAT token as a secret in your repository.
3. Create a new workflow file in your repository.

on:
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  issues: write

name: releaser-production
jobs:
  release:
    name: Create the release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Git config
        run: git config --global user.email "github-actions[bot]@users.noreply.github.com" && git config --global user.name "github-actions[bot]"

      - name: Create branch
        run: git checkout -b production-release

      - name: Releaser
        run: npx -y releaser-cli production

      - name: Push
        run: |
          git push -f origin production-release
          PR_EXISTS=$(gh pr list --head production-release --base main --json number --jq length)
          if [ "$PR_EXISTS" -eq "0" ]; then
            gh pr create --title "Production Release" --body-file ./pull_request_content.md --base main --head production-release
          else
            echo "PR already exists. Updating..."
            PR_NUMBER=$(gh pr list --head production-release --base main --json number --jq '.[0].number')
            gh pr edit $PR_NUMBER --body-file ./pull_request_content.md
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}

If you want to create a tag when you merge your pull request, you can create a new workflow file in your repository.

on:
  pull_request:
    types: [closed]
    branches:
      - main
  workflow_dispatch:
    inputs:
      environment:
        description: "Environment to create tag for (staging or production)"
        required: true
        default: "staging"
        type: choice
        options:
          - staging
          - production

permissions:
  contents: write

name: releaser-tag
jobs:
  create-tag:
    name: Create tag on main after merge or manual trigger
    runs-on: ubuntu-latest
    if: |
      (github.event_name == 'workflow_dispatch') ||
      (github.event_name == 'pull_request' &&
       github.event.pull_request.merged == true &&
       github.event.pull_request.base.ref == 'main' &&
       (github.event.pull_request.head.ref == 'staging-release' ||
        github.event.pull_request.head.ref == 'production-release'))
    outputs:
      tag_created: ${{ steps.push_tags.outputs.tag_created }}
      api_tag_created: ${{ steps.push_tags.outputs.api_tag_created }}
      environment: ${{ steps.determine_env.outputs.ENVIRONMENT }}
    steps:
      - name: Checkout main
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: main

      - name: Determine environment
        id: determine_env
        run: |
          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            echo "ENVIRONMENT=${{ github.event.inputs.environment }}" >> $GITHUB_ENV
          elif [[ "${{ github.event.pull_request.head.ref }}" == "staging-release" ]]; then
            echo "ENVIRONMENT=staging" >> $GITHUB_ENV
          else
            echo "ENVIRONMENT=production" >> $GITHUB_ENV
          fi

          echo "ENVIRONMENT=${{ env.ENVIRONMENT }}" >> $GITHUB_OUTPUT

      - name: Git config
        run: |
          git config user.name github-actions
          git config user.email [email protected]

      - name: Create tag with releaser
        run: npx -y releaser-cli ${{ env.ENVIRONMENT }} --tag

      - name: Push tags
        id: push_tags
        env:
          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}
        run: |
          if git push origin --tags; then
            echo "tag_created=true" >> $GITHUB_OUTPUT
            if grep -q "api" tags_to_create.txt; then
              echo "api_tag_created=true" >> $GITHUB_OUTPUT
            else
              echo "api_tag_created=false" >> $GITHUB_OUTPUT
            fi
          else
            echo "tag_created=false" >> $GITHUB_OUTPUT
          fi

  deploy-api-staging:
    needs: create-tag
    if: needs.create-tag.outputs.api_tag_created == 'true' && needs.create-tag.outputs.environment == 'staging'
    uses: ./.github/workflows/YOUR_STAGING_WORKFLOW.yml
    secrets: inherit

  deploy-api-production:
    needs: create-tag
    if: needs.create-tag.outputs.api_tag_created == 'true' && needs.create-tag.outputs.environment == 'production'
    uses: ./.github/workflows/YOUR_PRODUCTION_WORKFLOW.yml
    secrets: inherit

Building

Automatic build

The build.sh script will build the releaser binary for all platforms.

Manual build

For the platform you are working on:

$ cargo build --release

For linux: you need to install cross first:

$ cargo install cross

Then run:

$ cross build --release --target x86_64-unknown-linux-gnu

Create a Github PAT Token

When creating a Personal Access Token (PAT) for use in GitHub Actions, you should carefully consider the permissions needed for your specific workflow. Based on your current workflow requirements, here are the recommended permissions for your PAT:

1. repo (Full control of private repositories)

   • This includes access to code, commit statuses, pull requests, and repository hooks.

2. workflow (Update GitHub Action workflows)

   • This allows the token to modify and trigger workflows.

3. write:packages (Write packages to GitHub Package Registry)

   • If your workflow involves publishing packages.

4. read:org (Read org and team membership, read org projects)

   • This might be necessary if your repository is part of an organization.

5. gist (Create gists)

   • Only if your workflow creates gists.

Here's a step-by-step guide to create a PAT with these permissions:

1. Go to your GitHub account settings.
2. Click on "Developer settings" in the left sidebar.
3. Click on "Personal access tokens" and then "Tokens (classic)".
4. Click "Generate new token" and select "Generate new token (classic)".
5. Give your token a descriptive name, e.g., "GitHub Actions Staging Release".
6. Set an expiration date (consider security implications when setting this).
7. Select the following scopes:
   • repo
   • workflow
   • write:packages
   • read:org
   • gist (if needed)
8. Click "Generate token" at the bottom of the page.
9. Copy the token immediately (you won't be able to see it again).

After generating the token:

1. Go to your repository settings.
2. Click on "Secrets and variables" then "Actions".
3. Click "New repository secret".
4. Name it (e.g., PAT_TOKEN) and paste your token as the value.
5. Click "Add secret".

Remember, this token has significant permissions, so keep it secure and don't share it. Also, consider using the principle of least privilege and only grant the permissions that are absolutely necessary for your workflow.

License

Releaser is licensed under the MIT License.