A bridge application for integrating CodeScene by Empear into CI/CD build pipelines
Table of Contents generated with DocToc
CodeScene identifies and prioritizes technical debt, while at the same time uncovering and measuring social factors of the organization behind the system. The earlier you can react to any potential finding, the better. That’s why CodeScene offers integration points that let you incorporate the analysis results into your build pipeline.
The codescene-ci-cd application is runnable from build scripts in a CI-CD system, and uses the CodeScene Delta analysis API to perform a delta analysis and display the results in the build output. In addition to this, the analysis results can be attached as review comments on Merge/Pull Requests:
This application lets you use CodeScene’s Delta Analysis to:
- Prioritize code reviews based on the risk of the commits.
- Specify quality gates for the goals specified on identified hotspots (see Managing Technical Debt).
- Specify quality gates that trigger in case the Code Health of a hotspot declines.
The application can be run on its own in a repo folder with:
$ java -jar codescene-ci-cd-1.0.0-standalone.jar [options]
With that said, the recommended usage in most build environments is to use the docker image available at Docker Hub by configuring a build job using the image in the build file for a project.
Being a command line utility, codescene-cd-cd takes numerous command line options specifying the delta analysis:
Usage: codescene-ci-cd [options]
Options:
-h, --help
--codescene-delta-analysis-url URL CodeScene Delta Analysis URL
-u, --codescene-user USER CodeScene User
-p, --codescene-password PWD CodeScene Password
-r, --codescene-repository REPO CodeScene Repository
--analyze-individual-commits Individual Commits
--analyze-branch-diff By Branch
--pass-on-failed-analysis Pass Build on Failed Analysis
--fail-on-high-risk Fail Build on High Risk
--fail-on-failed-goal Fail Build on Failed Goals
--fail-on-declining-code-health Fail Build on Code Health Decline
--create-gitlab-note Create Note For Gitlab Merge Request
--create-github-comment Create Comment For GitHub Pull Request
--create-bitbucket-comment Create Comment For Bitbucket Pull Request
--create-azure-comment Create Comment For Azure Pull Request
--[no-]log-result Log the result (by printing)
--coupling-threshold-percent THRESHOLD 75 Temporal Coupling Threshold (in percent)
--risk-threshold THRESHOLD 9 Risk Threshold
--previous-commit SHA Previous Commit Id
--current-commit SHA/refname Current Commit Id
--base-revision SHA/refname Base Revision Id
--external-review-id ID External Review Id
--gitlab-api-url URL GitLab API URL
--gitlab-api-token TOKEN GitLab API Token
--gitlab-project-id ID GitLab Project ID
--gitlab-merge-request-iid IID GitLab Merge Request IID
--github-api-url URL GitHub API URL
--github-api-token TOKEN GitHub API Token
--github-owner OWNER GitHub Repository Owner
--github-repo REPO GitHub Repository Name
--github-pull-request-id ID GitHub Pull Request ID
--bitbucket-api-url URL BitBucket API URL
--bitbucket-user USER BitBucket User
--bitbucket-password PASSWORD BitBucket Password
--bitbucket-repo REPO BitBucket Repository Name
--bitbucket-pull-request-id ID BitBucket Pull Request ID
--azure-api-url URL Azure API URL
--azure-api-token TOKEN Azure API Token
--azure-project PROJECT Azure Project Name
--azure-repo REPO Azure Repository Name
--azure-pull-request-id ID Azure Pull Request ID
--result-path FILENAME Path where JSON output is generated
--http-timeout TIMEOUT-MS Timeout for http API calls
In a typical build environment, most of these options are common to all projects, and are thus best defined as variables set in the CI/CD-system, see examples below.
The codescene-* options specify how to connect to CodeScene and must match the settings in codescene itself. The bitbucket-*, gitlab-*, github-* and azure-* options specify how to connect to the respective repo provider for creating comments on Merge/Pull Requests. See examples below for details.
Flag options are used to enable analysis and gates in codescene-ci-cd - by default nothing is enabled.
The result-path saves the analysis results as a json file.
The http-timeout options specifies the timeout in milliseconds for all http requests. In some situations it may benecessary to specify a value greater than the default 10,000 ms.
To enable the CodeScene integration in a GitLab build pipeline, jobs running codescene-ci-cd are added to the projects .gitlab-ci.yml file similar to the example provided here.
A good way to DRY up the .gitlab-ci.yml files is by using GitLabs include/extends functionality to specify template jobs similar to these. In that case, the .gitlab-ci.yml would only need a few lines for activating the delta analysis:
include: /templates/codescene-ci-cd.gitlab.yml
stages:
- codescene-ci-cd
run-codescene-ci-cd-on-push:
stage: codescene-ci-cd
extends: .template-codescene-ci-cd-on-push
run-codescene-ci-cd-on-merge-request:
stage: codescene-ci-cd
extends: .template-codescene-ci-cd-on-merge-request
The run-codescene-ci-cd-on-push job runs analysis on individual commits for pushes. The run-codescene-ci-cd-on-merge-request job runs analysis on an entire branch for merge requests, and submits the results as a merge request comment.
In these examples, the CI_* variables are all built-in variables in GitLab. The CODESCENE-* variables are delta analysis specific variables that should be configured in the GitLab UI:
| Variable | Description |
|---|---|
| CODESCENE_DELTA_ANALYSIS_URL | The full URL to the CodeScene Delta Analysis REST API. Retrievable from the CodeScene GUI. |
| CODESCENE_USER | A bot user created in codesene for accessing the API. |
| CODESCENE_PASSWORD | The password for the bot user. |
| CODESCENE_GITLAB_API_TOKEN | A personal access token created in GitLab. |
| CODESCENE_RISK_THRESHOLD | The risk threshold to use if fail-on-high-risk is specified. (Optional) |
| CODESCENE_COUPLING_THRESHOLD_PERCENT | The coupling threshold used in the delta analysis. (Optional) |
| CODESCENE_TIMEOUT | The timeout in ms for all http calls in codescene-ci-cd. (Optional) |
To sum this up, the steps to follow for GitLab integration are:
- Retrieve the delta analysis URL from the CodeScene UI.
- Create a CodeScene bot user in the CodeScene UI.
- Create a Personal Access Token in GitLab that can be used for accessing the API, preferrably as a dedicated CodeScene user. (That user will be visible as the comment author.)
- Add the
CODESCENE-*variables specified in the table above as custom variables through the GitLab UI. - Add delta analysis job(s) to .gitlab-ci.yml, preferrably using a template.
To enable the CodeScene integration in a Circle CI build workflow, jobs running codescene-ci-cd are added to the projects .circleci/config.yml file similar to the example provided here.
The codescene-ci-cd job runs differently depending on whether it is a merge request build or not. For merge requests, it runs analysis on an entire branch and submits the results as a merge request comment. For regular commits, the individual commit is analysed
In these examples, the CIRCLE_* variables are built-in variables in Circle CI. The CODESCENE-* variables are delta analysis specific variables that should be configured in the Circle CI UI. In the examples a Circle CI context is used for sharing these variables across projects.
| Variable | Description |
|---|---|
| CODESCENE_DELTA_ANALYSIS_URL | The full URL to the CodeScene Delta Analysis REST API. Retrievable from the CodeScene GUI. |
| CODESCENE_USER | A bot user created in codesene for accessing the API. |
| CODESCENE_PASSWORD | The password for the bot user. |
| CODESCENE_RISK_THRESHOLD | The risk threshold to use if fail-on-high-risk is specified. |
| CODESCENE_COUPLING_THRESHOLD_PERCENT | The coupling threshold used in the delta analysis. |
| CODESCENE_TIMEOUT | The timeout in ms for all http calls in codescene-ci-cd |
| CODESCENE_GITHUB_API_URL | The full URL to the GitHub API. |
| CODESCENE_GITHUB_API_TOKEN | A personal access token created in GitHub. |
The steps to follow for Circle CI/GitHub integration are:
- Retrieve the delta analysis URL from the CodeScene UI.
- Create a CodeScene bot user in the CodeScene UI.
- Create a Personal Access Token in GitHub that can be used for accessing the API, preferrably as a dedicated CodeScene user. (That user will be visible as the comment author.)
- Add the
CODESCENE-*variables specified in the table above as custom variables through the Circle CI UI, preferrably using a context. - Add delta analysis job(s) to config.yml.
Note that to DRY up the config.yml the codescene-jobs one could optionally create a Circle CI ORB containing the delta analysis jobs.
To enable the CodeScene integration in GitHub Actions, add a workflow with jobs running codescene-ci-cd to the projects .github folder similar to the example provided here.
The codescene-ci-cd job runs on pull requests and submits the results as a merge request comment.
In these examples, the CODESCENE-* variables are delta analysis specific variables that should be configured as GitHub secrets.
| Variable | Description |
|---|---|
| CODESCENE_DELTA_ANALYSIS_URL | The full URL to the CodeScene Delta Analysis REST API. Retrievable from the CodeScene GUI. |
| CODESCENE_USER | A bot user created in codesene for accessing the API. |
| CODESCENE_PASSWORD | The password for the bot user. |
The steps to follow for GitHub Actions integration are:
- Retrieve the delta analysis URL from the CodeScene UI.
- Create a CodeScene bot user in the CodeScene UI.
- Add the
CODESCENE-*variables specified in the table above as secrets through the GitHub UI, . - Add a delta analysis workflow to .github.
To enable the CodeScene integration in Jenkins Pipeline, add a multi-branch pipeline configuration, and set it up to to run codescene-ci-cd by adding a Jenkinsfile with a pipeline similar to the example provided here to your project repository. Setup the pipeline configuration to run on pull requests.
In these examples, the CODESCENE-* variables are delta analysis specific variables that should be configured as secret credentials in Jenkins.
| Variable | Description |
|---|---|
| CODESCENE_DELTA_ANALYSIS_URL | The full URL to the CodeScene Delta Analysis REST API. Retrievable from the CodeScene GUI. |
| CODESCENE_USER | A bot user created in codesene for accessing the API. |
| CODESCENE_PASSWORD | The password for the bot user. |
The steps to follow for Jenkins Pipeline integration are:
- Retrieve the delta analysis URL from the CodeScene UI.
- Create a CodeScene bot user in the CodeScene UI.
- Add the
CODESCENE-*variables specified in the table above as secrets through the GitHub UI, . - Add a Jenkinsfile containing the delta analysis pipeline to your repository.
- Create a Multibranch Pipeline in Jenkins, using Jenkinsfile in the repository.
You can build the latest version of codescene-ci-cd by running lein uberjar. The corresponding docker image is then built using docker build -t empear/codescene-ci-cd . .
Run codescene-ci-cd inside the docker image using docker run -it empear/codescene-ci-cd [options]
A release build is automatically triggered when pushing a release tag to a repository. The corresponding docker image is manually built and pushed to docker hub.
You're encouraged to submit pull requests, and to propose features and discuss issues.
Licensed under the MIT License.