Skip to main content

CI/CD deployments

Q247 collects deployment history from CI/CD pipelines. The same repository connectors that supply commits collect it. They use the token stored in the connector, so collection needs no separate form. On the Client side you need to check the token permissions and, for Private Plugin, also the plugin version and configuration file.

Based on this data, the next release will provide DORA metrics: Deployment Frequency, Lead Time for Changes, Change Failure Rate and Time to Restore Service.

Supported platforms​

PlatformDeployment sourceSupported installations
GitLabGitLab CI/CDgitlab.com and self-managed instances
GitHubGitHub Actions and other deployments recorded in the GitHub APIgithub.com and GitHub Enterprise Server
Azure DevOpsYAML Pipelines and EnvironmentsAzure DevOps Services and Azure DevOps Server 2020 or later
BitbucketBitbucket PipelinesBitbucket Cloud only

In Azure DevOps, a deployment is a run of a job that declares an environment (Environment, the environment: key in YAML). Jobs without a declared environment leave no deployment history in Azure DevOps, so the plugin does not collect them.

Classic Release Management pipelines in Azure DevOps are not supported, and neither are Bitbucket Data Center and Server. The Gitea, Gerrit and Generic GIT connectors do not provide deployment data.

Scope of deployment data​

For each deployment the plugin collects:

  • the environment name and the deployment status,
  • the deployed commit, branch or tag it comes from, and the version, if available,
  • the start and end time and a link to the deployment in the source system,
  • the pipeline name,
  • the e-mail or login of the account that started the deployment (often a CI account),
  • for a successful deployment, the list of identifiers of the commits included in the deployment.

A deployment event does not contain source code, diffs, commit messages, pipeline logs, variables or secrets. Q247 receives commit messages separately, in commit events. The full list of fields of both kinds of events is in Enterprise Plugin security.

Deployments are collected only from repositories assigned to a project in Sources, and the plugin skips repositories without a project. The plugin fetches the history of the last 365 days for each repository separately, when it first processes that repository, and afterwards fetches only new deployments. A repository assigned to a project later also gets 365 days back, counted from the first run after the assignment.

Deployments do not change Calories, and the CI account that started a deployment does not become an organization user or a project participant as a result.

Token permissions​

Deployment collection uses the token stored in the connector. In some systems the token needs scopes for this that the connector itself does not require.

PlatformRequired permissionsChange relative to the connector
GitLabread_user, read_api and read_repositoryno change
GitHub, classic tokenrepono change
GitHub, fine-grained tokenContents, Deployments, Actions and Metadata, each at Read-only levelDeployments, Actions and Metadata are added
Azure DevOpsCode (Read), Project and Team (Read), Build (Read) and Environment (Read & manage)Build (Read) and Environment (Read & manage) are added
Bitbucket CloudBitbucket API token with the permissions described on the BitBucket page, including Pipelines read access (scope read:pipeline:bitbucket)Pipelines read access is added

Without the Deployments permission the plugin cannot fetch deployments from GitHub, and without the Actions permission it fetches them without the pipeline name.

Environment scope in Azure DevOps only with the manage permission

Microsoft does not offer a read-only scope for environments, so the token must have the Environment (Read & manage) scope. The plugin uses it only to read environments and deployment history.

Plugin version and configuration​

Cloud Plugin is maintained by Q247, so on the Client side steps 1 and 2 below are enough. Private Plugin requires all six:

  1. Token in the existing connector. If the table in Token permissions lists new scopes for the platform, generate a token with those scopes, open the connector in Configuration, in the Plugins section, with the "Edit" button, enter the new token and save with the "Save changes" button.
  2. Repositories assigned to a project in Sources. Deployments are not collected from repositories without a project.
  3. Plugin version q247-enterprise-plugin-linux-v2.7.9 or later, downloaded with the "Plugin File" button in the header of the Plugins section (→ Downloading the files).
  4. An { "code": "CICD" } entry in the plugins.items array of the config.cfg file. Updating the plugin file alone does not enable collection. The location of the entry and an example are in Installation.
  5. Restarting the plugin, because config.cfg is read only at startup. The startup command is in Installation.
  6. Checking the log q247-plugin.log: after startup the line Started addon CI/CD Deployments should appear in it (→ Collection diagnostics).

The CICD module connects to the same version control hosts as the repository connector, only with different API paths, so the existing firewall rules for those systems are sufficient.

The configuration file downloaded from the panel already contains the CICD entry. It has default settings, however, so replacing your existing file with it removes the changes made there, including custom ports and the ssl section. Use this route only if the file has not been changed since it was downloaded.

Collection diagnostics​

Missing deployment permissions produce no message in the application and do not change the connector status. You check the configuration on the token and plugin side:

  1. Token scopes matching the table in Token permissions.
  2. Plugin version and CICD entry (Private Plugin): version q247-enterprise-plugin-linux-v2.7.9 or later, an entry in plugins.items and a restart after adding it.
  3. Plugin log q247-plugin.log (Private Plugin), in which the module leaves the lines described in the table below.
Log lineMeaning
Started addon CI/CD Deploymentsthe CICD module started together with the plugin; the absence of this line after startup means there is no CICD entry in plugins.items or the plugin is older than q247-enterprise-plugin-linux-v2.7.9
CICD ingest for <account>: ...summary of a run: number of new deployments, processed repositories, errors and repositories without a project
CICD <account>: error processing repo <address> (ERROR level)error fetching deployments from a repository, including access denied when a token scope is missing
CICD <account>: skipping N repo(s) without a project assignment.the plugin skipped repositories without an assigned project

In place of <account> the log gives the identifier of the Q247 account, that is, of the organization in Q247. The connector name does not appear in these lines, and the repository is identified by its address.

See also​