NSV (Next Semantic Version) is a convention-based semantic versioning tool that leans on the power of conventional commits to make versioning your software a breeze!

Check out the latest documentation.

You can also define CI/CD variables within your GitLab project to configure the behavior of both nsv and gpg-import. All are optional:

• NSV_FORMAT is a Go template for formatting the generated semantic version tag.
• NSV_TAG_MESSAGE is a custom message when creating an annotated tag.
• GPG_PRIVATE_KEY is the base64 encoded GPG private key in armor format.
• GPG_PASSPHRASE is an optional passphrase if the GPG key is password protected.
• GPG_TRUST_LEVEL is an owner trust level assigned to the imported GPG key.

Ensure all environment variables are wrapped within double quotes to prevent any unintentional side effects

If you wish to tag the repository without triggering another workflow, you must set the permissions of the job to contents: write.

name: ci
on:
  push:
    branches:
      - main
jobs:
  ci:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: NSV
        uses: purpleclay/nsv-action@v1
        env:
          GPG_PRIVATE_KEY: '${{ secrets.GPG_PRIVATE_KEY }}'

When tagging your repository, nsv will identify the person associated with the commit that triggered the release and pass this to git through the user.name and user.email config settings.

You can override this behavior by importing a GPG key, manually setting those git config settings, or using the reserved git environment variables GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL; see the documentation for further details.

If working with a monorepo project, the project to tag can be specified through the projects input:

name: ci
on:
  push:
    branches:
      - main
jobs:
  ci:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: NSV
        uses: purpleclay/nsv-action@v1
        with:
          projects: src/project
        env:
          GPG_PRIVATE_KEY: '${{ secrets.GPG_PRIVATE_KEY }}'

Multiple monorepo projects can be tagged by providing a comma-separated list to the projects input.

If you wish to trigger another workflow after nsv tags the repository, you must manually create a token (PAT) with the public_repo permission and use it during the checkout. For best security practice, use a short-lived token.

name: ci
on:
  push:
    branches:
      - main
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: '${{ secrets.TOKEN }}'

      - name: NSV
        uses: purpleclay/nsv-action@v1
        env:
          GPG_PRIVATE_KEY: '${{ secrets.GPG_PRIVATE_KEY }}'
          GPG_PASSPHRASE: '${{ secrets.GPG_PASSPHRASE }}'

You can capture the next tag without tagging the repository by setting the next-only input to true.

name: ci
on:
  push:
    branches:
      - main
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: NSV
        id: nsv
        uses: purpleclay/nsv-action@v1
        with:
          next-only: true

      - name: Print Tag
        run: |
          echo "Next calculated tag: ${{ steps.nsv.outputs.nsv }}"