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.

The life cycle of a branch, e.g. Feature_1

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.

Where our tools/APIs should be invoked

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:

  1. 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_upload projects, use the Dashboard Python API (see the example below); for shared_database projects, copy the artifacts to a new name and register them in the Axivion Dashboard Server (see the example below).

  2. 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.

  3. 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=shared_database

With database_mode set to shared_database, you are responsible for providing and configuring the storage locations of the analysis artifacts both in axivion_ci and the Dashboard. Consequently, you can create your branch project by copying the artifacts to a new name and registering the new database in the Dashboard.

Python (rfgscript) Snippet to create a branch project from an existing project with database_mode=shared_database
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025-2026 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io


import os
import shutil
import subprocess
from pathlib import Path

from axivion.dashboard import ApiToken, Dashboard

prj_main = os.environ['MAIN_PROJECT_NAME']
prj_feature = os.environ['FEATURE_PROJECT_NAME']
ci_side_databases_dir = Path(os.environ['DATABASES_DIR'])
dashboard_side_databases_dir = Path(os.environ['DASHBOARD_DATABASES_DIR'])


def artifact(
    project_name: str, suffix: str, db_root: Path = ci_side_databases_dir
) -> str:
    return os.fspath(db_root / Path(project_name).with_suffix(suffix))


# issue database + annotation database
shutil.copy2(artifact(prj_main, '.db'), artifact(prj_feature, '.db'))
shutil.copy2(artifact(prj_main, '.dbx'), artifact(prj_feature, '.dbx'))

# generated files folder (next 18 lines, remove if you do not use a ShadowVCS)
repo_lines = subprocess.check_output(
    ['cidbman', 'repository', 'list', artifact(prj_feature, '.db')]
).splitlines()
opts = (line.split(b';') for line in repo_lines)
shadow_dir_opt = next((opt for opt in opts if opt[1] == b'shadow_directory'), None)
if shadow_dir_opt is not None:
    shadow_dir = artifact(prj_feature, '.shadow')
    shutil.copytree(shadow_dir_opt[2].decode('utf-8'), shadow_dir)
    shadow_dir_def = subprocess.check_call(
        [
            'cidbman',
            'repository',
            'set',
            shadow_dir_opt[0],
            'shadow_directory=' + shadow_dir,
            artifact(prj_feature, '.db'),
        ]
    )

with Dashboard('https://dashboard.example', auth=ApiToken(os.environ['TOKEN'])) as d:
    d.install_project(
        artifact(prj_feature, '.db', dashboard_side_databases_dir),
        prj_feature,
    )

Copying the generated files folder can be omitted if that feature is not enabled. Additionally, you will likely not want to copy the IR and RFG, as those artifacts are not versioned and the first analysis of the branch project will overwrite them anyway.

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 and grant the Configure Dashboard permission.

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.

Python (rfgscript) Snippet to create a branch project from an existing project with database_mode=managed_upload
# 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.

Example usage of 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 in

  • View

  • View Annotations

  • Low-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=shared_database

With database_mode set to shared_database, you are responsible for providing and configuring the storage locations of the analysis artifacts both in axivion_ci and the Dashboard. In this case, deleting artifacts requires manually deleting those files and deregistering the project from the Dashboard Server, unless Automated Cleanup for unmanaged projects is configured.

Python (rfgscript) Snippet to delete a branch project with database_mode=shared_database
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025-2026 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io


import os
import shutil
from pathlib import Path

from axivion.dashboard import ApiToken, Dashboard

prj_feature = os.environ['FEATURE_PROJECT_NAME']
ci_side_databases_dir = Path(os.environ['DATABASES_DIR'])


def artifact(
    project_name: str, suffix: str, db_root: Path = ci_side_databases_dir
) -> Path:
    return db_root / Path(project_name).with_suffix(suffix)


with Dashboard('https://dashboard.example', auth=ApiToken(os.environ['TOKEN'])) as d:
    d.uninstall_project(prj_feature)

artifact(prj_feature, '.db').unlink()  # issue database
artifact(prj_feature, '.dbx').unlink(missing_ok=True)  # annotation database
artifact(prj_feature, '.ir').unlink(missing_ok=True)  # IR file
artifact(prj_feature, '.rfg').unlink(missing_ok=True)  # RFG file
shutil.rmtree(
    artifact(prj_feature, '.shadow'), ignore_errors=True
)  # generated files folder

Caution

The Continuous Integration token type is only usable for this if your Dashboard Server is running at least version 7.8.0. Otherwise, you will need to use a General Purpose token and grant the Configure Dashboard permission.

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:

Python (rfgscript) Snippet to delete a branch project with database_mode=managed_upload
# 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.

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.