5.1.2.2. Projects

This section describes the connection between axivion_ci and the Dashboard, specifically how analysis results are made available inside the Dashboard via artifacts. Please refer to Project Configuration for information on how to create these artifacts.

Dashboard project configuration is performed on the “Projects” page within the Dashboard; see The project list configuration view. You require the Administrate permission to see the navigation entry in the settings menu of the navigation bar.

The project list configuration view

The project list configuration view

Project Artifacts

Artifacts are files containing analysis results and annotations. There are currently five types:

The first four artifacts are created by axivion_ci, while the .dbx file is created by the Dashboard.

Note

Mirror repositories required by some version control systems for the Dashboard to display source code are not considered artifacts in this context, as they are often shared between several projects.

Project Types

There are two types of projects, which differ only in how their artifacts are managed or installed on the Dashboard. From a usage perspective, the two project types are identical. The Dashboard can handle a mixture of both project types simultaneously. The types are:

  • Manually managed (default) – Artifacts are managed in the filesystem by an administrator and typically reside on a network file share when axivion_ci and the Dashboard run on different hosts

  • Automatically managed – Introduced with 7.6.0, this type eliminates the need for manual artifact management and installation. See here and here for information on how to enable this feature and its current limitations

Projects with database mode “shared database”

Projects with database_mode configured to shared_database are located in server-side directories, which can be configured in the list of added directories below. Files with the .db suffix within these directories are shown in the same list. They can be activated using the Install button and will be assigned a name derived from the analysis project that created them.

To deactivate such projects, use the Remove button. For these projects, this action simply unregisters the artifacts from the dashboard configuration (manual deletion from the file system is still required); however, for managed_upload projects, it deletes them from the disk permanently. Whether the artifacts of a project are shared_database or managed_upload is indicated by the Managed Upload column of the upper projects list.

Projects in watched database directories are installed and uninstalled automatically. The directories are scanned for new or removed database files when the dashboard server starts and when the watch status is set. While the server is running, the watched directories are continuously monitored for new and removed projects. Manually uninstalling projects whose databases are in a watched directory is forbidden.

Directory monitoring is registered when the Dashboard starts or when a directory is configured as a watched directory. If the directory does not exist at that time, it will not be monitored, even if it is created later. After the registration of a directory, its path becomes irrelevant: the registration only uses the directory handle/inode. Therefore, if a watched directory is renamed or moved, it will still be monitored. The configured directory path only becomes relevant upon a Dashboard restart or when the directory is un-watched and re-watched.

Projects with database mode “managed upload”

Projects with database_mode configured to managed_upload were introduced with 7.6.0 and eliminate the need for the manual artifact management and installation required for shared_database projects. See here for information on how to enable this feature and its current limitations.

To delete such projects, use the Remove button. For automatically managed projects, this deletes the artifacts from the disk permanently; for shared_database projects, it simply unregisters them from the dashboard configuration. Whether the artifacts of a project are managed_upload or shared_database is indicated by the Managed Upload column of the upper projects list.

All artifacts of automatically managed projects reside in one, non-configurable, dedicated folder called artifacts inside the Dashboard configuration folder.

Caution

Do not manually modify the files inside the artifacts folder. If you need to modify files in this folder manually, you are likely encountering one of the use-cases not yet supported by this feature.

axivion_ci Authentication

To provide axivion_ci with the permission to download and upload project artifacts, we recommend the following steps:

Create an authentication token:

  • In the Dashboard Server: Create a dedicated user (e.g., builduser) for automation tasks, if you have not already done so.

  • Give that user the permissions Log in and Update Analysis Artifacts.

  • Go to the user’s personal page (click the username in user management).

  • Create an authentication token of type Continuous Integration and provide a useful description, such as: builduser token used by axivion_ci to access the Dashboard stored in our automation server.

Configure the Token in your Automation Server:

  • Automation systems typically provide methods for storing credentials; use these to store the username and token.

  • Configure your automation system such that the environment variable AXIVION_USERNAME is set to the username and AXIVION_PASSWORD to the token when axivion_ci is invoked.

  • Depending on your security requirements, there are simpler but less secure methods for passing the credentials to axivion_ci.

In the Jenkins Automation Server, it could look as follows:

Jenkins Credentials Configuration

Jenkins Credentials Storage Example

Applying the credentials in the Jenkins Automation Server within a Groovy pipeline script could look as follows:

withCredentials([usernamePassword(
        credentialsId: 'dashboard-api',
        usernameVariable: 'AXIVION_USERNAME',
        passwordVariable: 'AXIVION_PASSWORD',
)]) {
    bat """
        set "BAUHAUS_CONFIG=%CD%\\Axivion"
        axivion_ci
    """
}

Classic Jenkins jobs can achieve the same result via the UI configuration.

List of Active Projects

In the list above, you can configure your active projects or remove them. By selecting one or more projects and clicking the Edit button, a new window opens displaying all available configuration options for the selected set of projects.

Caution

If you change a project name, you must adjust the projectname input in your analysis configuration accordingly so that Continuous Integration can refer to the project correctly (e.g., when triggering Erosion Notification Emails).

Note

Many aspects of the dashboard can be configured on a project-group basis using *-patterns. Consider grouping your projects by using similar prefixes or suffixes for related projects.

The Erosion Mail column allows you to disable notifications from the dashboard-integrated Erosion Notification System on a per-project basis.

Issue Annotations is another configurable column where you can explicitly disable the Issue Annotations feature. Consider doing this to prevent users from spending time commenting on and annotating issues that you will later discard while experimenting with your setup.

The Managed Upload column indicates whether the artifacts of a project are shared_database or managed_upload.

The Version column indicates the internal schema version of a database. Analysis data schema version numbers differ from the Axivion Suite version numbers.

Caution

Although you can explicitly migrate databases to newer versions via cidbman database migrate, we recommend doing so only for historical databases that no longer have Continuous Integration running, because the Axivion Suite version used for analysis might be older than the Axivion Suite version used for running the dashboard. Analysis runs automatically upgrade the schema version; it is best to let them handle this task.

The project list provides additional options that are rarely needed, such as clearing cached project data to refresh the version list or updating the version control system cache. If the dashboard is running during analysis and is properly known to Continuous Integration, cache updates will occur automatically.

Project Hierarchies

You can define project hierarchies for the Dashboard Page by naming them accordingly. Project names must be prefixed with the groups they belong to, separated by one of the characters configured via the Project Name Separators option in General Settings (defaulting to underscore (_), hyphen (-), and dot (.)). For example, the projects TeamA-ProjectX-master and TeamA-ProjectX-feature will create a tree with the root TeamA, which contains the group ProjectX, which in turn contains the projects master and feature.

Note

A group cannot be a project; i.e., a project name must not be a prefix of another one. A group name must not be empty; i.e., separators must not be leading, trailing, or occur consecutively.

FAQ

Q: Why was my project automatically deleted?

A: Axivion projects are associated with specific Git branches. If a branch no longer exists in the remote repository, the project is marked for automatic cleanup (if enabled).

Solution: Verify that /Project/VCSIntegration/Git/branch contains the plain name of a branch that exists in the remote, e.g., feature/x. The literal string HEAD, a tag name, or a name with an origin/ or refs/heads/ prefix will never match a remote branch, causing the project to be marked as deleted. In CI, the branch must be set explicitly; see Git Branch and Commit Hash.

Recovery: If your project was deleted:

  1. Create a database directory and register it as an ‘unmanaged database directory’ in Settings → Projects

  2. Place the trashed database file there and restore its original name. Trashed files are named <projectname>_<filename>.<timestamp>.trash; since the <projectname>_ prefix is not always present, remove any such prefix, the timestamp, and the .trash suffix

  3. Enable the project via Settings → Projects

  4. Run a managed upload analysis to make it a managed project again

Q: Why are Git clones consuming disk space in my database directory?

A: The sourceserver_gitdir configuration creates one Git clone per Axivion project, which is inefficient.

Solution: In version 7.8+, remove the sourceserver_gitdir setting. Axivion will automatically detect the repository and create a single shared clone instead of one per project:

  1. Remove sourceserver_gitdir from the Git configuration

  2. The next analysis will create a shared clone in the new location

  3. Once all projects are updated, you can remove the old project-specific clones

Dashboard: When using database_mode=managed_upload (formerly upload=true), old databases are automatically cleaned up when Automatic Project Cleanup is enabled on the Projects > Cleanup page of the settings.

Q: Why aren’t outdated projects being cleaned up automatically?

A: Automatic Project Cleanup is configured on the Projects > Cleanup page of the settings and consists of two independent phases, each with its own opt-in checkboxes. Both phases run periodically every 24 hours.

Phase 1 - Trashing projects (files renamed with a .trash suffix, not yet permanently deleted):

  • Trash Active Projects - trashes installed (managed_upload and shared_database) projects whose associated Git branch no longer exists in the remote repository

  • Trash Inactive Projects - trashes uninstalled (shared_database only) projects whose branch no longer exists

Phase 2 - Permanently deleting trashed projects (irreversible):

  • Delete *.trash files in configured database directories - shared_database projects

  • Delete *.trash files in the artifacts directory - managed_upload projects

Phase 2 only deletes trashed files whose timestamp in the file name is more than five days old.

You can enable Phase 1 without Phase 2 (to review before permanent deletion), or enable both to fully automate cleanup.

If the checkboxes are enabled but nothing is cleaned up, the most common cause is that no branch was recorded for the projects, which typically happens with an unconfigured CI setup; a project without a branch is always considered alive. Use cidbman repository list to check what was recorded and refer to Diagnosing the automated cleanup for the relevant log messages.