Skip to content

Latest commit

 

History

History
195 lines (156 loc) · 9.55 KB

README.md

File metadata and controls

195 lines (156 loc) · 9.55 KB
Raw

SemVer Action

Check dist/ CodeQL Continuous Integration Continuous Delivery Linter Code Coverage

Important

As of version v2.0.0, this action has been converted to ESM.

Gets the Semantic Version of a repository based on the type of manifest file located. This action currently supports the following:

Language Manifest File
Dart pubspec.yaml
GitHub Actions (Container) action.yml
Java pom.xml
Node.js package.json
Python pyproject.toml
setup.cfg
setup.py
Other .version

Tip

If your project type/language is not available, please submit an issue! In the meantime, you can create a generic .version file in your repository and refer to that! The .version file should only contain the version information.

Once a version has been located, this action automatically creates or updates the following tags to point to the specified ref, depending on if this is a prerelease version or not.

Prerelease Tag
Yes v<major>.<minor>.<patch>-<prerelease>+<build>
v<major>.<minor>.<patch>-<prerelease>
No v<major>.<minor>.<patch>+<build>
v<major>.<minor>.<patch>
v<major>.<minor>
v<major>

Note

Build tags are only created if build metadata is provided/inferred from the version string.

Setup

Here is a simple example of how to use this action in your workflow. Make sure to replace vX.X.X with the latest version of this action.

name: Continuous Delivery

on:
  pull_request:
    types:
      - closed
    branches:
      - main

# This is required to be able to update tags
permissions:
  contents: write

jobs:
  release:
    name: Release Version
    runs-on: ubuntu-latest

    # Only run this job if the PR was merged
    if: ${{ github.event.pull_request.merged == true }}

    steps:
      # Checkout the repository with fetch-depth set to 0 and fetch-tags set to
      # true
      - name: Checkout
        id: checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          fetch-tags: true

      - name: Tag Commit
        id: tag-commit
        uses: issue-ops/[email protected]
        with:
          manifest-path: package.json
          workspace: ${{ github.workspace }}
          ref: main

      - name: Print version
        run: echo ${{ steps.tag-commit.outputs.version }}

Pull Requests

When run as part of a pull request, this action will automatically add a comment indicating if the version in the manifest file is valid or conflicts with an existing version. This can be used as an additional check to ensure that the version is updated when new features are released.

Inputs

Input Default Description
allow-prerelease 'true' If check-only is 'true', this controls if the check should pass if a matching prerelease version is detected (e.g. v1.0.0-SNAPSHOT).
check-only 'false' If set to 'true', only checks if the version exists. Fails the action if the version already exists.
comment 'true' If set to 'true', a comment will be added to the pull request indicating if the version is valid or conflicts with an existing version.
manifest-path The path to the manifest that contains the version (relative to the root of the repository).
If not set, use-version must be set.
overwrite 'false' Set to 'true' to overwrite existing tags.
push-tags 'true' Set to 'true' to push tags to the repository.
ref ${{ github.base_ref }} The Git ref to tag.
token ${{ github.token }} The GitHub token to use for authentication.
use-version The version you want to explicitly use. This must follow SemVer 2.0 standards.
If not set, manifest-path must be set.
workspace ${{ github.workspace }} The path where the repository has been cloned.

Outputs

The action outputs the following (assuming the version in the manifest file is 1.2.3-alpha.4+build.5):

Output Description Example
version Full Semantic Version 1.2.3-alpha.4+build.5
major-minor-patch <major>.<minor>.<patch> 1.2.3
major-minor <major>.<minor> 1.2
major <major> 1
minor <minor> 2
patch <patch> 3
prerelease <prerelease> alpha.4
build <build> build.5

If the prerelease and/or build versions are not provided, they will not be included in the full version output.

Errors

If the overwrite parameter is 'false' (the default value), this action will fail if there is an existing version tag in the repository that matches the inferred or provided version. This is to prevent releases from overwriting one another. However, this only applies to the full version output. Other tags, such as <major>.<minor> are ignored in this check.

Example

Assume a Node.js repository has the following tag and commit structure:

Commit Tags Notes
9807987 Latest commit, no tags
0123456 v2.1.0, v2.1, v2 Latest v2 (major) / v2.1 (minor)
1243415 v2.0.0, v2.0 Latest v2.0 (minor)
9517391 v1.2.3, v1.2, v1 Latest v1 (major) / v1.2 (minor)

Prerelease Update

If the action is run with version set to 2.3.1-alpha.1 in package.json, the repository tags will be updated to:

Commit Tags Notes
9807987 v2.3.1-alpha.1 Latest commit, with prerelease tag
0123456 v2.1.0, v2.1, v2 Latest v2 (major) / v2.1 (minor)
1243415 v2.0.0, v2.0 Latest v2.0 (minor)
9517391 v1.2.3, v1.2, v1 Latest v1 (major) / v1.2 (minor)

Warning

In prerelease updates, existing major/minor/patch tags are not modified.

Major/Minor/Patch Update

If the action is run with version set to 2.1.3 in package.json, the repository tags will be updated to:

Commit Tags Notes
9807987 v2.1.3, v2.1, v2 Latest commit, no tags
0123456 v2.1.0 Latest v2 (major) / v2.1 (minor)
1243415 v2.0.0, v2.0 Latest v2.0 (minor)
9517391 v1.2.3, v1.2, v1 Latest v1 (major) / v1.2 (minor)

Warning

In major/minor/patch updates, existing major/minor/patch tags are modified.