https://github.com/purpleclay/nsv-action
:octocat: GitHub action for the NSV tool
https://github.com/purpleclay/nsv-action
conventional-commits git github github-actions go semver semver-release
Last synced: 5 months ago
JSON representation
:octocat: GitHub action for the NSV tool
- Host: GitHub
- URL: https://github.com/purpleclay/nsv-action
- Owner: purpleclay
- License: mit
- Created: 2023-04-07T05:52:00.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-04T22:34:57.000Z (over 1 year ago)
- Last Synced: 2025-10-31T04:44:28.788Z (8 months ago)
- Topics: conventional-commits, git, github, github-actions, go, semver, semver-release
- Language: TypeScript
- Homepage:
- Size: 145 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# NSV Action
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](https://docs.purpleclay.dev/nsv/).
## Inputs
| Name | Required | Type | Description |
| ----------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `token` | no | string | A token for performing authenticated requests to the GitHub API |
| `version` | no | string | The version of NSV to download (default: `latest`) |
| `next-only` | no | boolean | If the next semantic version should just be calculated. Repository will not be tagged (default: `false`) |
| `projects` | no | string | A comma-separated list of paths to monorepo projects |
## Outputs
| Name | Type | Description |
| ----- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `nsv` | string | The calculated next semantic version. Can be a comma-separated list if multiple monorepo projects were provided |
## Environment variables
You can also define CI/CD variables within your GitLab project to configure the behavior of both [nsv](https://docs.purpleclay.dev/nsv/reference/env-vars/) and [gpg-import](https://github.com/purpleclay/gpg-import/blob/main/README.md#features). 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
## Using the action
### Tag the repository
If you wish to tag the repository without triggering another workflow, you must set the permissions of the job to `contents: write`.
```yaml
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 }}'
```
#### User impersonation
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](https://docs.purpleclay.dev/nsv/tag-version/#committer-impersonation) for further details.
### Tag a monorepo project
If working with a monorepo project, the project to tag can be specified through the `projects` input:
```yaml
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.
### Trigger another workflow
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.
```yaml
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 }}'
```
### Capturing the next tag
You can capture the next tag without tagging the repository by setting the `next-only` input to `true`.
```yaml
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 }}"
```