8.2.8. Project Branching¶
A common use case is analyzing VCS branches in a separate Dashboard project.
Important
A Dashboard project stores a single, linear history of analyzed versions—one timeline. New analysis results are therefore added sequentially: only one analysis run can add a new version to a given project at a time. Running several CI pipelines against the same Dashboard project in parallel (a potential mistake when setting up pull/merge-request analysis) is not supported; the concurrent runs will collide, and only one of them will succeed.
Consequently, every line of development you want to analyze—whether a long-lived branch or a short-lived pull/merge request—needs its own timeline. The section below summarizes the available options.
In software development, a typical way of implementing modifications is creating an exact copy of a specific state of the source code and working on that, while other developers may be working on other copies of the source code. This ensures that developers do not interfere with each other’s copies and that every copy has a well-defined purpose. Eventually, the changes made to a copy are integrated back into a main or master copy.
Version Control Systems (VCS) like Git assist with maintaining and sharing these copies,
as well as the process of integrating the changes made to them. They use the term
Branch for such copies and the term
Merge for when the changes of such a copy are reintegrated into the main copy
or branch.
Based on these principles, several workflows have emerged, the most fundamental being
that of so-called feature branches, as illustrated
here. These feature branches may exist for some
time before they are merged back and eventually deleted.
In some cases, such branches are never merged and continue to evolve independently.
An Axivion Dashboard project
tracks only one VCS Branch. However, it may be desirable to set up an additional
axivion_ci/Dashboard project corresponding to a Branch that begins as a copy
of the original project, as the erosion findings are identical when the source code is
the same.
Over time, the Main and the Branch projects will evolve differently regarding
erosion findings.
For the Branch project, users are typically only interested in findings introduced by
code changes on the corresponding VCS branch. It is also useful to see
the relationship between the Main and the Branch projects and to be able
to copy annotations created on issues in the branch
project back to the corresponding issues in the main project after merging.
This is possible using the tools and APIs provided, but they must be integrated into your automation system. The basic steps and their timing are illustrated here.
Note
Before proceeding, note that calling Dashboard APIs from an automation server requires storing credentials on that server; please ensure you have read the section on axivion_ci authentication.
8.2.8.1. Choosing an Approach¶
Depending on whether you want the results to reside in the Axivion Dashboard Server and whether the line of development is long-lived or short-lived, choose one of the following:
Branch off an existing Dashboard project. Create a new project that starts from a copy of an existing project’s state, so that its findings are shown in relation to that origin. This approach is detailed in the remainder of this howto. It is well-suited for long-lived branches as well as pull/merge requests for which you want the delta to be visible in the Axivion Dashboard Server. The method used to branch depends on the project’s database_mode: for
managed_uploadprojects, use the Dashboard Python API (see the example below); forshared_databaseprojects, copy the artifacts to a new name and register them in the Axivion Dashboard Server (see the example below).Create a new, empty Dashboard project on the fly. Run the analysis under a new, unique Project.name; the first analysis of that project becomes the baseline. Use this option when you do not need any relationship to an existing project.
Do not use the Dashboard at all. For pull/merge requests, the most lightweight option is to bypass the Dashboard timeline entirely and publish the findings of the code change directly to the pull/merge request using annotate_pr.
Note
It is helpful to distinguish between two use cases:
Branch analysis is the long-lived counterpart to your main-branch analysis: a branch that exists for some time (e.g., analyzed nightly) and is eventually merged back. Use option 1 or 2, with one Dashboard project per branch.
Pull/merge-request analysis is short-lived. Either use option 1 with one Dashboard project per pull/merge request or use the Dashboard-less option 3.
In either case, ensure that two pipelines never analyze into the same project simultaneously.
8.2.8.2. Branch Creation¶
Ideally, the Dashboard branch project should be created immediately after the VCS branch is created, although it can be done later. If your analysis configuration is under version control, it may already be branched. However, the Project.name may be hard-coded. Since this value must match the Dashboard project name, hard-coding it is risky; a copied configuration should typically correspond to a different Dashboard project. Using the same project name for two different branches will result in both branches appending their analysis results to the same database.
Therefore, you may want to configure Project.name
dynamically (e.g., by setting it to MyProject-$(env:AXIVION_BRANCH_NAME)), allowing your
automation system to derive that value from the VCS branch and supply it when
invoking axivion_ci
(see Git Branch and Commit Hash).
This same value must also be configured as /Project/VCSIntegration/Git/branch; simply naming the project after the branch is not sufficient for the automated cleanup described below.
Note
See here for guidance on choosing a project naming scheme and here for examples of how to derive environment variable values from git.
Caution
When using /Results/Dashboard/database_mode=shared_database, you also must ensure that the path names of all enabled artifacts are unique. The relevant configuration options are:
The names of the IR file, the RFG file, and the Annotation Database (.dbx) (created by the Dashboard) are automatically aligned with the Database filename.
Once you have ensured that your analysis project name and artifacts are unique,
it is time to branch the Dashboard project.
The procedure for this is fundamentally different depending on whether
/Results/Dashboard/database_mode is set to
managed_upload or shared_database.
Branch Project Creation with database_mode=managed_upload¶
Caution
Requires your Dashboard Server to be on at least 7.8.0.
With database_mode set to
managed_upload, no manual artifact copying
is necessary; you only need to call the appropriate Dashboard API endpoint.
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io
import os
from axivion.dashboard import ApiToken, Dashboard, Project
prj_main = os.environ['MAIN_PROJECT_NAME']
prj_feature = os.environ['FEATURE_PROJECT_NAME']
with Dashboard('https://dashboard.example', auth=ApiToken(os.environ['TOKEN'])) as d:
Project(d, prj_main).create_branch(name=prj_feature, version='latest')
Note
As of version 7.8.3, the Dashboard Server API was extended to
automatically check whether a branch project with the given name (prj_feature
in this example) already exists and whether its origin and analysis version
match the values supplied in the API call (prj_main and 'latest',
respectively). If such a project is found, it is returned
instead of creating a new branch project—effectively making
create_branch a NOOP on the server side. Also in Dashboard Server
version 7.8.3, the version parameter became optional, with latest
being the default value. Moreover, omitting version in create_branch
disables the version check for existing branch projects. This is
particularly useful in scenarios where the branching API is called for
every analysis run, regardless of whether the branch project already exists.
8.2.8.3. Merging of Issue Annotations¶
When new changes from the main branch are integrated into your long-lived feature branch, you will likely want to include the new issue annotations from the main branch in the annotation database of your feature branch. Likewise, when your feature branch reaches its end of life and is integrated back into the main branch, you will also want to merge the annotations unique to your feature branch back to the main branch.
This can be achieved using the merge_issue_annotations tool; the process is the same regardless of the database_mode used.
merge_issue_annotations¶merge_issue_annotations --url https://your-dashboard/axivion \
--source_project prj_src --target_project prj_tgt
Note that prj_src and prj_tgt must be chosen in accordance with the
annotation copy direction: when integrating changes from the main branch into
the feature branch, source is the main project and target is the feature project;
when integrating a feature branch into the main branch, the reverse is true.
By default, the tool compares the latest analysis versions of both projects. The options
--source_version and --target_version select other analysis versions using a
version query string. The source version should be the final
analysis on the source branch before the merge, and the target version should be the first analysis
on the target branch after the merge commit.
For the script to work properly, set
the environment variable AXIVION_USERNAME to the login name of
a (technical) Dashboard User
with at least the following permissions:
Log inViewView AnnotationsLow-Level Issue Annotation Control
All permissions except for Log In are project-specific; for example, the technical user
can be limited to a specific project namespace, such as Team1-*.
The environment variable AXIVION_PASSWORD must be set to an ApiToken of type
General Purpose or Continuous Integration belonging to the user specified by
AXIVION_USERNAME. Providing the password in the environment variable is also
possible but not recommended. The options --user and --password take precedence
over these environment variables. If no username is provided, the tool uses the name of the
current OS user; if no password is provided, it will prompt for one.
Caution
The Continuous Integration token type can only be used if your
Dashboard Server is running version 7.8.0 or later. Otherwise, you must resort
to the General Purpose token.
8.2.8.4. Branch Deletion¶
Once your feature branch has been merged back into the main branch and is no longer needed, you likely want to delete the corresponding Dashboard project.
This may also be a good time to trigger the final invocation of merge_issue_annotations to synchronize your issue annotations. To do this, wait for one analysis run on the main branch (after the feature branch was integrated), perform the last issue annotation sync, and only then delete the branch project.
As with creating the branch project, the procedure for removing it differs fundamentally depending on the database_mode used.
Branch Project Deletion with database_mode=managed_upload¶
Caution
Requires your Dashboard Server to be running at least version 7.8.0.
With database_mode set to
managed_upload, deleting the branch project
consists simply of calling the delete API endpoint:
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io
import os
from axivion.dashboard import ApiToken, Dashboard, Project
prj_feature = os.environ['FEATURE_PROJECT_NAME']
with Dashboard('https://dashboard.example', auth=ApiToken(os.environ['TOKEN'])) as d:
Project(d, prj_feature).delete()
8.2.8.5. Automated Cleanup of Branch Projects¶
The purpose of automated project cleanup is to periodically (every 24 hours) delete Dashboard projects (including their artifacts!) that are associated with a non-existent VCS branch.
Warning
Automated cleanup requires the branch option of the VCSIntegration Git to
contain the branch name. A project with an empty branch is always considered
alive, so the cleanup silently removes nothing at all. In CI, the branch must be set
explicitly (see Git Branch and Commit Hash); verify the
recorded value with cidbman repository list.
Note
Automated cleanup is currently limited to projects using the Git Version Control System.
Note
This option may be dangerous if you intend to merge back issue annotations before branch project deletion, as it can be difficult to ensure that the four steps – VCS merge, axivion_ci (on main), merge_issue_annotations, and VCS branch deletion – occur in that exact order.
On the Projects > Cleanup page of the
Dashboard Server settings,
you can enable automated cleanup using the following options:
Trashing Projects
The Dashboard periodically (every 24 hours) scans for projects where at least one
VCS branch no longer exists and trashes them. This means that projects are
not permanently erased immediately, but are instead removed from the Dashboard and
marked for deletion.
This is achieved by renaming the files associated with that project with a timestamp and a
.trash suffix.
Trash Active Projects– Active projects are those that are installed. Both managed_upload and shared_database projects can be active.Trash Inactive Projects– Inactive projects are those that are not installed. Only shared_database projects can be inactive.
Deleting trashed Projects
The Dashboard periodically (every 24 hours) scans for projects marked for deletion
(i.e., those with the .trash suffix in their filename) and deletes them from
the disk. Only
files with a timestamp in the filename older than five days are deleted.
Delete *.trash files in configured database directories– This will only delete shared_database projects that are marked for deletion.Delete *.trash files in the artifacts directory– This will only delete managed_upload projects that are marked for deletion.
Caution
Files deleted this way cannot be restored.
Diagnosing the automated cleanup
Each of the three scans above runs as a separate background job, which starts shortly after the Dashboard is launched (or after the respective option was enabled) and repeats every 24 hours. Toggling an option off and on restarts the job, providing the quickest way to trigger a run without waiting.
Decisions are logged to the source-server log file
(axivion_sourceserver.log), not the Dashboard log file. The Dashboard log only
reports the start of each scan and the projects being cleaned up;
projects that are retained are logged only at log level DEBUG. Relevant messages
in the source-server log include:
branch "..." is no longer alive in remote "..."— the branch is gone, and the project will be trashed.Project "..." with empty branch treated as still alive— no branch was recorded for this project; see the warning at the beginning of this section.an error reported by
git ls-remote— the Dashboard could not reach the remote, for example because the recorded repository URL contains credentials that have since expired. Such a project is treated as alive.
Other reasons a project may be treated as alive without a message include having no repository registered in its database or using a Version Control System other than Git. Use cidbman repository list to inspect the contents of a project database.