GitHub Action to implement build numbers in Workflows.

⭐ I appreciate your star, it helps me decide to which OSS projects I should allocate my spare time.

This Action can be used to generate increasing build numbers across a number of scopes that can be useful for tracking purposes and defining complete version strings for product releases.

This Action uses a Gist to store persistent state between invocations. The OAuth token that is normally made available to GitHub Workflows and its Actions (GITHUB_TOKEN) does not provide any access to Gists (read or write) therefore this Action requires a separate parameter (gist_token) for an OAuth or PAT token which will be used to read and write the state Gist.

NOTE: it is not necessary that the Gist token be associated with the repository in which the Workflow that consumes this Action is targeting. In this way, a separate GitHub account can actually be used to store the state.

NOTE: this action does include some debug messaging so if you need to troubleshoot its behavior, you can enable debug logging using the ACTIONS_STEP_DEBUG secrets variable. You can find more info here.

Here is a quick sample of how to use this action in your own Workflows:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: generate build number
      uses: zyborg/gh-action-buildnum@v1 
      with:
        gist_token: ${{ secrets.GIST_TOKEN }}
        set_env: true

    - name: print repo global build number
      run: echo Global Build Number is $BUILDNUM_FOR_GLOBAL

    - name: get existing build number
      uses: zyborg/gh-action-buildnum@v1
      id: lastBuildNum
      with:
        gist_token: ${{ secrets.GIST_TOKEN }}
        skip_bump: true

    - name: dump last build num
      run: |
        echo Global Build Number is ${{ steps.lastBuildNum.outputs.global_buildnum }}
        echo Workflow Build Number is ${{ steps.lastBuildNum.outputs.workflow_buildnum }}

When this action runs it generates several build numbers that are relative to a number of scopes.

This scope tracks build numbers across all Workflows of a given GitHub repository which make use of this Action. The state of this build number is stored as a top-level value in the state Gist.

The resolved value of the Global Scope is made available as an output named global_build_number and optionally as an environment variable named BUILDNUM_FOR_GLOBAL.

This scope tracks build numbers across every invocation of single Workflow. The state of this build number is stored in the state Gist indexed by the current Workflow name.

The resolved value of the Workflow Scope is made available as an output named workflow_build_number and optionally as an environment variable named BUILDNUM_FOR_WORKFLOW.

This scope tracks build numbers across every invocation of single Workflow for a given, unique version key. This scope is optional and will only be resolved if the input parameter of version_key is provided with a non-null/non-empty value. The state of this build number is stored in the state Gist indexed by the current Workflow name and the given version key.

The resolved value of the Version Scope is made available as an output named version_build_number and optionally as an environment variable named BUILDNUM_FOR_VERSION.

This Action defines the following formal inputs.

This Action defines the following formal outputs.

If the set_env input is true, then the following environment variables will be defined.

This Action uses a Gist file to store the state of build numbers across Workflow runs.

Here is a sample.

/* THIS FILE IS AUTO-GENERATED AND MANAGED BY GITHUB ACTIONS. MANUAL MODIFICATIONS
** CAN BREAK THINGS IF YOU DO NOT KNOW WHAT YOU ARE DOING! *YOU* HAVE BEEN WARNED!
*/
{
  "workflow_buildnums": {
    "test-action": {
      "version_buildnums": {
        "0.0.0": {
          "build_num": 5
        }
      },
      "build_num": 13
    }
  },
  "build_num": 13
}

This Action is implemented as a PowerShell GitHub Action.