Skip to content

Build Number Action (Abacus)

Actions

About

Generate monotonic build numbers (and manage counters) via Abacus
v1.0.0
Latest
By Appegy
Star (0)

Tags

 (2)
continuous-integrationutilities

Build Number (Abacus) — GitHub Action

Generate monotonic build numbers in GitHub Actions with separate counters per project (or any other key). This action is a thin wrapper around the Abacus counting API.

Abacus API docs: https://abacus.jasoncameron.dev/
Abacus server source: https://github.com/JasonLovesDoggo/abacus

What this solves

  • You need a build number that is always +1 versus the previous run.
  • One CI workflow builds multiple projects, so you need independent counters per project.
  • You want to start from an existing number (via create initializer, or later via admin ops).

Supported operations

  • hit — increment by 1 and return the new value (creates the counter if missing)
  • get — return the current value
  • info — return metadata (exists, TTL, etc.)
  • create — create a counter and return admin_key (only returned once)
  • set — set an exact value (admin)
  • update — add a delta (can be negative) (admin)
  • reset — set value to 0 (admin)
  • delete — delete the counter (admin)

Quick start

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Next build number
        id: buildno
        uses: appegy/build-number-action@v1
        with:
          operation: hit
          namespace: my-org
          key: build-api

      - name: Use the build number
        run: echo "build=${{ steps.buildno.outputs.value }}"

Inputs

Name Type Default Used by operations Description
operation string hit all One of: hit, create, get, info, set, update, reset, delete.
namespace string — all Counter namespace (use a stable, unique prefix for your org/team).
key string — all Counter key (e.g. build-api, build-web, build-worker).
initializer integer 0 create Starting value for the counter.
value integer — set, update set: sets counter to value. update: adds value (can be negative).
admin_key string — set, update, reset, delete Admin key for management operations. Treat as a secret.

Outputs

Output Set by operations Type Notes
value hit, create, get, set, reset, update integer (string in Actions) The counter value returned by Abacus.
namespace create string Echoed namespace.
key create string Echoed key.
admin_key create string Only returned once by Abacus on create. Store it immediately.
exists info string Boolean-ish (true/false).
expires_in info string Seconds-ish value from Abacus.
expires_str info string Human-readable TTL string.
full_key info string Fully-qualified key representation.
is_genuine info string Boolean-ish (true/false).
status delete string Usually ok on success.
message delete string Informational message from Abacus.

Usage

1) Bootstrap the admin_key (one-time)

admin_key is returned only once by create. Save it immediately.
If you lose it, admin operations (set, update, reset, delete) for that counter become permanently unavailable.

Example workflow that creates a counter and uploads the admin key as an artifact:

name: bootstrap-abacus-admin-key

on:
  workflow_dispatch:
    inputs:
      namespace:
        description: "Abacus namespace"
        required: true
        default: "my-org"
      key:
        description: "Counter key"
        required: true
        default: "build-api"
      initializer:
        description: "Starting value"
        required: false
        default: "0"

jobs:
  bootstrap:
    runs-on: ubuntu-latest
    steps:
      - name: Create counter (admin_key is returned once)
        id: create
        uses: appegy/build-number-action@v1
        with:
          operation: create
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}
          initializer: ${{ inputs.initializer }}

      - name: Write admin key to file
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p abacus
          cat > abacus/abacus-admin-key.txt << 'EOF'
          namespace=${{ inputs.namespace }}
          key=${{ inputs.key }}
          admin_key=${{ steps.create.outputs.admin_key }}
          EOF

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: abacus-admin-key-${{ inputs.namespace }}-${{ inputs.key }}
          path: abacus/abacus-admin-key.txt
          if-no-files-found: error
          retention-days: 1

After you retrieve the value, store it as a repository secret (for example ABACUS_ADMIN_KEY) and delete the artifact.

2) Use the operations (excluding create)

Prerequisite:

  • add a repository secret named ABACUS_ADMIN_KEY that matches this (namespace, key) counter.

This workflow demonstrates all operations except create:

name: abacus-operations-demo

on:
  workflow_dispatch:
    inputs:
      namespace:
        description: "Abacus namespace"
        required: true
        default: "my-org"
      key:
        description: "Counter key"
        required: true
        default: "build-api"
      do_delete:
        description: "Also delete the counter at the end"
        required: false
        default: "false"

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Increment (+1)
        id: hit
        uses: appegy/build-number-action@v1
        with:
          operation: hit
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}

      - name: Read current value
        id: get
        uses: appegy/build-number-action@v1
        with:
          operation: get
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}

      - name: Get metadata
        id: info
        uses: appegy/build-number-action@v1
        with:
          operation: info
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}

      - name: Set exact value (admin)
        id: set
        uses: appegy/build-number-action@v1
        with:
          operation: set
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}
          value: 1000
          admin_key: ${{ secrets.ABACUS_ADMIN_KEY }}

      - name: Update by delta (admin)
        id: update
        uses: appegy/build-number-action@v1
        with:
          operation: update
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}
          value: -10
          admin_key: ${{ secrets.ABACUS_ADMIN_KEY }}

      - name: Reset to 0 (admin)
        id: reset
        uses: appegy/build-number-action@v1
        with:
          operation: reset
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}
          admin_key: ${{ secrets.ABACUS_ADMIN_KEY }}

      - name: Delete counter (admin)
        if: ${{ inputs.do_delete == 'true' }}
        uses: appegy/build-number-action@v1
        with:
          operation: delete
          namespace: ${{ inputs.namespace }}
          key: ${{ inputs.key }}
          admin_key: ${{ secrets.ABACUS_ADMIN_KEY }}

Notes

  • hit consumes a number immediately. If your job fails later, that number is still consumed.
  • For multi-project CI, use different key values (e.g. build-api, build-web) to keep counters independent.
  • If you delete a counter, you must create it again, and the new counter will have a new admin_key.

Attribution

  • Publisher/maintainer: Appegy (Ivan Murashka).
  • Backend: Abacus counting API by Jason Cameron (see server source link above).

Contributors (1)

@imurashka

Resources

Build Number Action (Abacus) is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.

About

Generate monotonic build numbers (and manage counters) via Abacus
v1.0.0
Latest
By Appegy

Tags

 (2)
continuous-integrationutilities

Contributors (1)

@imurashka

Resources

Build Number Action (Abacus) is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.