@jscutlery/semver

To run @jscutlery/semver in a GitHub workflow, ensure you use fetch-depth: 0 in your checkout step to retrieve the full history required for version calculation. You must also configure a Git user and provide the GITHUB_TOKEN environment variable.

Example workflow configuration:

name: release

on:
  - workflow_dispatch

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Setup Git
        run: |
          git config user.name "GitHub Bot"
          git config user.email "gituser@example.com"
      - run: pnpm install --frozen-lockfile
      - name: Version
        shell: bash
        run: pnpm nx affected --base=last-release --target=version --parallel=1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Tag last-release
        shell: bash
        run: |
          git tag -f last-release
          git push origin last-release --force

The @jscutlery/semver:gitlab executor is used to create GitLab Releases. It requires the GitLab Release CLI to be installed on your machine.

Manual Execution

You can run the executor manually via Nx by providing a --tag:

nx run my-project:gitlab --tag v1.0.0

Automated Configuration with post-targets

The recommended way to use this executor is via post-targets. This allows the version target to automatically trigger the GitLab release after a version bump.

{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": ["my-project:gitlab"]
      }
    },
    "gitlab": {
      "executor": "@jscutlery/semver:gitlab",
      "options": {
        "tag": "${tag}",
        "description": "${notes}"
      }
    }
  }
}

To run @jscutlery/semver in GitLab CI, you may need to configure a deploy key to allow the runner to push changes back to the repository. Ensure you set the remote URL with the appropriate token and use the -o ci.skip flag when pushing to avoid triggering recursive pipelines.

Example GitLab CI configuration:

stages:
  - release

release:
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: manual
  stage: release
  image: node:20.19.3
  before_script:
    - git config --global user.name "GitLab Bot"
    - git config --global user.email "gituser@example.com"
    - git remote set-url origin http://gitlab-ci-token:${DEPLOY_KEY}@gitlab.com/org/project.git
  script:
    - pnpm install --frozen-lockfile
    - pnpm nx affected --target=version --base=last-release --parallel=1
    - git tag -f last-release
    - git push origin last-release --force -o ci.skip

The recommended way to use this executor is via post-targets. This allows the @jscutlery/semver:version executor to automatically trigger the GitHub release after a version bump.

Using a full Changelog file

To use an existing file (like CHANGELOG.md) as the release notes, use the notesFile option:

{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": ["my-project:github"]
      }
    },
    "github": {
      "executor": "@jscutlery/semver:github",
      "options": {
        "tag": "${tag}",
        "notesFile": "./libs/my-project/CHANGELOG.md"
      }
    }
  }
}

Using only new changes (Recommended)

To avoid including the entire changelog in every release, use the ${notes} context provided by @jscutlery/semver:version. This ensures only the new changes are included in the GitHub release notes:

{
  "targets": {
    "version": {
      "executor": "@jscutlery/semver:version",
      "options": {
        "postTargets": ["my-project:github"]
      }
    },
    "github": {
      "executor": "@jscutlery/semver:github",
      "options": {
        "tag": "${tag}",
        "notes": "${notes}"
      }
    }
  }
}