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 automated cleanup of branch projects considers the project alive forever and never removes it.
Since there is no tracking branch to derive the remote from, /Project/VCSIntegration/Git/remote defaults to the first remote the workspace has, together with its URL. If the workspace has more than one remote, set the remote explicitly as well.
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:
for /F "tokens=* usebackq" %%F in (`git symbolic-ref --quiet --short HEAD`) do (
set "AXIVION_BRANCH_NAME=%%F"
)
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:
for /F "tokens=* usebackq" %%F in (`git rev-parse HEAD`) do (
set "AXIVION_VERSION_NAME=%%F"
)
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:
git fetch %REMOTE%
for /F "tokens=* usebackq" %%F in (`git merge-base %REMOTE%/%BRANCH% HEAD`) do (
set "AXIVION_VERSION_NAME_FILTER=* (%%F)"
)
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:
{
"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:
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.