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¶
Project Artifacts¶
Artifacts are files containing analysis results and annotations. There are currently
five types:
.db– the project database containing versioned Erosion Issues and Metrics.shadoworshadow.fossil– database containing generated files.rfg– Resource Flow Graph (e.g., used for Architecture, CycleDetection, and DeadcodeDetection).ir– Intermediate Representation (e.g., used for CloneDetection, Metrics, and Stylechecks).dbx– stores Issue Annotations like tags and comments
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 “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 inandUpdate Analysis Artifacts.Go to the user’s personal page (click the username in user management).
Create an authentication token of type
Continuous Integrationand 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_USERNAMEis set to the username andAXIVION_PASSWORDto the token whenaxivion_ciis 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 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:
Create a database directory and register it as an ‘unmanaged database directory’ in Settings → Projects
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.trashsuffixEnable the project via Settings → Projects
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:
Remove
sourceserver_gitdirfrom the Git configurationThe next analysis will create a shared clone in the new location
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_uploadandshared_database) projects whose associated Git branch no longer exists in the remote repositoryTrash Inactive Projects- trashes uninstalled (shared_databaseonly) projects whose branch no longer exists
Phase 2 - Permanently deleting trashed projects (irreversible):
Delete *.trash files in configured database directories-shared_databaseprojectsDelete *.trash files in the artifacts directory-managed_uploadprojects
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.