8.2.1. Git Branch and Commit Hash

8.2.1.1. Background

You are using Git and want to automatically capture the current branch and current commit hash for use within the configuration.

Important

Practically all CI systems using Git check out the repository in a detached HEAD state. In this state, the current branch cannot be determined from the workspace, and /Project/VCSIntegration/Git/branch remains empty. Therefore, you must set the branch explicitly in CI; see Determining the branch in a CI system.

An empty branch does not trigger an error:

The value must be the plain branch name as it exists on the remote, e.g. feature/x — not HEAD, not a tag name, and without any origin/ or refs/heads/ prefix. Any non-empty value that does not correspond to an existing remote branch will cause the Axivion Dashboard Server to consider the project’s branch deleted, which results in the project being trashed once Automatic Project Cleanup is enabled.

8.2.1.2. What can be configured?

You can use Git commands and parse their one-line output into an environment variable, which can then be referenced within the Axivion configuration.

8.2.1.3. What needs to be done?

To reflect the current branch, you can use the following code in your analysis start batch file to set the environment variable AXIVION_BRANCH_NAME. This variable can then be used, for example, within the configured /Project/name and as /Project/VCSIntegration/Git/branch:

On Windows:
for /F "tokens=* usebackq" %%F in (`git symbolic-ref --quiet --short HEAD`) do (
    set "AXIVION_BRANCH_NAME=%%F"
)
On GNU/Linux or macOS:
export AXIVION_BRANCH_NAME="$(git symbolic-ref --quiet --short HEAD)"

These examples retrieve the branch from the workspace, which works on a developer’s machine and in a Local Build. In CI, the workspace has no branch; retrieve it from the CI system instead (see Determining the branch in a CI system).

Warning

Do not use git rev-parse --abbrev-ref HEAD for this purpose. In a detached HEAD state, it outputs the literal string HEAD, which does not correspond to a remote branch, whereas git symbolic-ref --quiet --short HEAD outputs nothing, allowing you to detect this situation.

To reflect the current commit hash, use the following code to set the environment variable AXIVION_VERSION_NAME (the default) in order to import the commit hash along with the timestamp into the project database:

On Windows:
for /F "tokens=* usebackq" %%F in (`git rev-parse HEAD`) do (
    set "AXIVION_VERSION_NAME=%%F"
)
On GNU/Linux or macOS:
export AXIVION_VERSION_NAME="$(git rev-parse HEAD)"

This also works in a detached HEAD state.

In a “Local Build” scenario, you can set the reference version as follows:

On Windows:
git fetch %REMOTE%
for /F "tokens=* usebackq" %%F in (`git merge-base %REMOTE%/%BRANCH% HEAD`) do (
    set "AXIVION_VERSION_NAME_FILTER=* (%%F)"
)
On GNU/Linux or macOS:
git fetch $REMOTE
export AXIVION_VERSION_NAME_FILTER="* ($(git merge-base $REMOTE/$BRANCH HEAD))"

Substitute %REMOTE% and %BRANCH% on Windows (or $REMOTE and $BRANCH on GNU/Linux or macOS) with the appropriate remote and branch names from which the current branch was created.

8.2.1.4. Determining the branch in a CI system

Since the checkout in CI does not have a branch, retrieve the branch name from the variables of your CI system and assign it to AXIVION_BRANCH_NAME as shown above. The subsections below list the variables to use for each CI system. Reference the variable in your configuration for both the branch itself and — if you use one project per branch — the project name:

axivion_config.json
{
    "Project": {
        "Git": {
            "_active": true,
            "branch": "$(env:AXIVION_BRANCH_NAME)"
        },
        "Project-GlobalOptions": {
            "name": "MyProject-$(env:AXIVION_BRANCH_NAME)"
        }
    }
}

The same start_analysis script typically runs in CI and – via IDE plugins – as a Local Build on a developer’s machine. To support both, first query the workspace and use the CI system variable as a fallback:

On GNU/Linux or macOS (GitLab CI as an example):
AXIVION_BRANCH_NAME="$(git symbolic-ref --quiet --short HEAD || true)"
: "${AXIVION_BRANCH_NAME:=$CI_COMMIT_BRANCH}"
export AXIVION_BRANCH_NAME

AXIVION_LOCAL_BUILD is set implicitly whenever axivion_ci runs in local_mode. Testing for this variable allows you to abort a CI job if the branch cannot be determined, while still permitting a Local Build from a detached workspace (where no project is written to the Axivion Dashboard Server).

Note

Pipelines triggered by a tag do not have a branch. Since only branches (refs/heads/*) are considered, either skip the analysis for tag pipelines or deliberately leave the branch empty.

GitLab CI

CI_MERGE_REQUEST_SOURCE_BRANCH_NAME for merge request pipelines, CI_COMMIT_BRANCH for branch pipelines:

export AXIVION_BRANCH_NAME="${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-$CI_COMMIT_BRANCH}"

GitHub Actions

GITHUB_HEAD_REF is set only for pull requests, where GITHUB_REF_NAME is <number>/merge — hence this order:

export AXIVION_BRANCH_NAME="${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}"

Gitea Actions

The same variables as GitHub Actions are used, with a GITEA_ prefix (Gitea also accepts the GITHUB_ prefix for compatibility):

export AXIVION_BRANCH_NAME="${GITEA_HEAD_REF:-$GITEA_REF_NAME}"

Azure DevOps

System.PullRequest.SourceBranch for pull request builds, Build.SourceBranch otherwise. Both are fully formed refs, so the leading refs/heads/ must be stripped:

env:
  AXIVION_BRANCH_NAME: $[ replace(coalesce(variables['System.PullRequest.SourceBranch'], variables['Build.SourceBranch']), 'refs/heads/', '') ]

Jenkins (multibranch)

CHANGE_BRANCH for pull requests, BRANCH_NAME otherwise:

export AXIVION_BRANCH_NAME="${CHANGE_BRANCH:-$BRANCH_NAME}"

8.2.1.5. Checking which branch was recorded

The branch is stored in the project database during analysis. To see what was actually recorded, list the VCS options of the database served by the Axivion Dashboard Server:

cidbman repository list <project>.db

Check the branch row of each repository. An empty value indicates the branch could not be determined — most likely due to a detached HEAD checkout without an explicit branch. You can repair an existing database with:

cidbman repository set <repository_id> branch=<branch name> <project>.db

Note that for managed_upload projects, the database is replaced by the next upload; therefore, the configuration in your CI must also be corrected.

To reproduce the Axivion Dashboard Server’s decision, run the following command on the machine hosting the Axivion Dashboard Server, using the recorded sourceserver_remote_url and branch:

git ls-remote -q --heads <sourceserver_remote_url> <branch>

A single line of output indicates the branch still exists; empty output indicates the project is no longer alive.