How to version build artifacts using GitHub Actions?

Question

My use case is I want to have a unique version number for artifacts per each build/run. With current tools like CircleCI, Travis, etc. there is a build number available which is basically a counter that always goes up. So, I can create version strings like 0.1.0-27. This counter is increased each time even for the same commit.

How can I do something similar with GitHub Actions? Github actions only offer GITHUB_SHA and GITHUB_REF.

Savick

Does the $GITHUB_EVENT_PATH JSON file contain some sort of unique ID that you can use? – Oehsen

Wouldn't GITHUB_SHA be the idiomatic way of doing this though? A counter can get confusing quickly, if you have several branches, etc. – Igorot

I've opened a GitHub discussion to have auto-incrementing counters added to GitHub Actions. Go up-vote it :) github.com/orgs/community/discussions/64533 – Brigid

Answer 1

GitHub Actions now has a unique number and ID for a run/build in the github context.

github.run_id : A unique number for each workflow run within a repository. This number does not change if you re-run the workflow run.

github.run_number : A unique number for each run of a particular workflow in a repository. This number begins at 1 for the workflow's first run, and increments with each new run. This number does not change if you re-run the workflow run.

github.run_attempt : A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run.

ref: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context

You can reference them in workflows like this:

- name: Output Run ID
  run: echo ${{ github.run_id }}
- name: Output Run Number
  run: echo ${{ github.run_number }}
- name: Output Run Attempt
  run: echo ${{ github.run_attempt }}

Relativity

Important note: these numbers do not change if you re-run the action. This makes for a pretty fragile build number. – Funke

@Funke I think this can be resolved using github.run_attempt – Electricity

The difference between run_id and run_number is still not at all clear to me ... ? – Third

@JoshM. AFAIK run_id is unique but not meaningful. The run_number is a simple counter on the runs for that job and this displays neatly in the UI as well as being easy for users to understand the sequence of builds. But it's a mistake to use the run_no as unique. Something as simple as renaming the workflow file will reset the counter. So you always want to include the run_id as well as the run_number. – Habited

These variables are useful for getting a random unique ID, but for versioning it's nice to have sequential values. I've opened this discussion to have auto-incrementing counters added to GitHub Actions. Go up-vote it :) github.com/orgs/community/discussions/64533 – Brigid

Answer 2

I had the same problem and have just created an action to generate sequential build numbers. Use it like

- uses: einaregilsson/build-number@v1
  with:
    token: ${{secrets.github_token}}

In steps after that you'll have a BUILD_NUMBER environment variable. See more info about using the same build number for different jobs and more at https://github.com/einaregilsson/build-number/

UPDATE: There is now a $GITHUB_RUN_NUMBER variable built into GitHub Actions, so this approach is not needed anymore.

Ramrod

Love the elegant hack here. Using tags as a state store is brilliant. – Fotina

Thanks :) I had a lot of fun building it, wrote about it a bit at einaregilsson.com/… – Ramrod

bravo. very clever approach – Offoffbroadway

what should be the value for gihub_token? Is this a token that needs permission to do what? I have been getting "Bad credentials". – Donnydonnybrook

Answer 3

If you want to extract the github version numbers and put them in a json file which can be imported into your app, this is what I did (before building my app):

- name: Add version info to json file
    env:
      Version: ${{ github.run_id }}.${{ github.run_number }}.${{ github.run_attempt }}
    run: |
      echo "{\"version\": \"$Version\"}" > /assets/version.json

Systematist

Answer 4

If you want a constant integer increment (1,2,3,4,5), I haven't found anything in the docs that you could use as such increment which is aware of how many times that particular action ran. There's two solutions I can think of:

1. Maintaining state on the repo: for example with a count.build file that uses the workflow ID and you increment it on build. This is my least favourite solution of the two because it adds other complexities, like it will itself trigger a push event. You could store this file somewhere else like S3 or in a Gist.

2. Using the Date: if you're not worried about sequence on the integer increment you could just use the current data and time, for example 0.1.0-201903031310 for Today at 13:10.

Regardless if you have Actions Beta Access, I would definitely feed this back to GitHub.

Hope it helps.

Sheffy

Answer 5

I use it in my docker pushing like this:

- name: Push Docker image with incremented version tag
  uses: docker/build-push-action@v2
  with:
   context: .
   push: true
   tags: ${{secrets.DOCKER_USERNAME}}/${{secrets.DOCKER_IMAGE_NAME}}:${{ github.run_number }}

Kex

Answer 6

You can use GitVersion to generate incrementing versions from tags in Git. The PR at https://github.com/GitTools/GitVersion/pull/1787 has some details, but basically you can define this job:

- uses: actions/checkout@v1
    - name: Get Git Version
      uses: docker://gittools/gitversion:5.0.2-beta1-34-linux-debian-9-netcoreapp2.1
      with:
        args: /github/workspace /nofetch /exec /bin/sh /execargs "-c \"echo $GitVersion_MajorMinorPatch > /github/workspace/version.txt\""

Swec

Answer 7

To store an increment (or any other data-strings) you can use Repository variables but it's not possible to set them directly like local ENV vars. Use GitHub Actions API to set a variable into the value you need to.

https://docs.github.com/en/rest/actions/variables?apiVersion=2022-11-28

e.g.

  curl --location --request PATCH 'https://api.github.com/repos/my_org/any_app/actions/variables/BUILD_INCREMENT' \
--header 'Accept: application/vnd.github+json' \
--header 'Authorization: Bearer ghp_Fd6N34L9sometoken' \
--header 'Content-Type: text/plain' \
--header 'X-GitHub-Api-Version: 2022-11-28' \
--data '{"name":"BUILD_INCREMENT","value":"1111"}'

This solution allows you to control the increment and edit it if necessary.

P.S. Thanks to Mickey Gousset from youtube. His advice helped me to find this information.

Dicast