Skip to content

Latest commit

 

History

History
99 lines (59 loc) · 6.48 KB

teamcity.md

File metadata and controls

99 lines (59 loc) · 6.48 KB
Raw

Integrating Sigrid CI with TeamCity

This guide explains how to integrate Sigrid into your TeamCity continuous integration pipeline. Make sure you have also read the general Sigrid CI documentation before starting this guide.

Prerequisites

  • You have a Sigrid user account. Sigrid CI requires Sigrid, it is currently not supported to only use the CI integration without using Sigrid itself.
  • You have on-boarded your system, i.e. your system is available in Sigrid. Request your system to be added if this is not yet the case.
  • Python 3 needs to be available in the CI environment. The client scripts for Sigrid CI are based on Python.

Request a Sigrid CI account

The account you use to submit code to Sigrid CI is different from your normal Sigrid user account. The account consists of an account name and a token, which you add to your CI environment's configuration in the next step.

You can obtain a Sigrid CI account by requesting one from support@softwareimprovementgroup.com. Support for creating Sigrid CI accounts yourself will be added in a future version.

Once the account has been created, you can use Sigrid's user management feature to control which systems it is allowed to access. Similar to normal Sigrid user accounts, Sigrid CI accounts can either serve a specific system, a group of systems, or all systems in your portfolio.

Configuration

This documentation assumes you have already created a project in TeamCity, and that your project is connected to a Git repository.

Step 1: Create build step

You can add Sigrid CI to your TeamCity project by creating a new build step:

  • Select your TeamCity project
  • Select build steps from the menu on the left
  • Click the "add build step" button
  • When asked for the runner type, select "command line"
  • For the run type, select "custom script"
  • You can now enter the following script:
git clone https://github.com/Software-Improvement-Group/sigridci.git sigridci
./sigridci/sigridci/sigridci.py --customer yourcustomername --system yoursystemname --source . --targetquality 3.5

This scripts supports a number of arguments that you can use to configure your Sigrid CI run. The scripts and its command line interface are explained in using the Sigrid CI client script.

Security note: This example downloads the Sigrid CI client scripts directly from GitHub. That might be acceptable for some projects, and is in fact increasingly common. However, some projects might not allow this as part of their security policy. In those cases, you can simply download the sigridci directory in this repository, and make it available to your runners.

  • For "artifact paths", enter the value **/sigrid-ci-output/**.
  • In "Docker settings", use python:3.9-buster as the container name and "Docker image platform" to "Linux". Note that using this Docker container is just an example, custom Docker containers or custom runners are also supported, as long as the runner meets the system requirements listed in the "Prerequisites" section at the top of this page.

After performing these steps you should end up with the following configuration:

Step 2: Configure account credentials

Now that we have created the new build step, we need to provide our Sigrid account name and authentication token:

  • Select "parameters" in the build menu on the left.
  • Click "add new parameter"
  • Add an environment variable with the kind "environment variable", the name env.SIGRID_CI_ACCOUNT, with value based on the account name you have received.

  • Save the environment variable
  • Repeat the process for another environment variable env.SIGRID_CI_TOKEN, with the value based on the Sigrid CI authentication token you have received
  • You should now see the following parameters as part of your build configuration:

Step 3: Run your pipeline

After completing the previous two steps, Sigrid CI will now run as part of your pipeline. To test the pipeline, you can either wait until it's triggered or trigger it manually using the "run" button in the TeamCity web interface.

After the pipeline has completed, Sigrid CI will be shown as part of the normal build output. The check will succeed if the code quality meets the specified target, and will fail otherwise.

Usage

In addition to the simple success/failure indicator, Sigrid CI provides multiple levels of feedback. To obtain feedback on your commit, click on the "Sigrid CI" step in the pipeline results screen:

The output consists of the following:

  • A list of refactoring candidates that were introduced in your merge request. This allows you to understand what quality issues you caused, which in turn allows you to fix them quickly. Note that quality is obviously important, but you are not expected to always fix every single issue. As long as you meet the target, it's fine.
  • An overview of all ratings, compared against the system as a whole. This allows you to check if your changes improved the system, or accidentally made things worse.
  • The final conclusion on whether your changes and merge request meet the quality target.

In addition to the textual output, Sigrid CI also generates a static HTML file that shows the results in a more graphical form. This is similar to test coverage tools, which also tend to produce a HTML report. You can access this report from the "artifacts" section in your build output:

The information in the HTML report is based on the aforementioned list, though it includes slightly more detail.

Finally, if you want to have more information on the system as a whole, you can also access Sigrid, which gives you more information on the overall quality of the system, its architecture, and more.

Contact and support

Feel free to contact SIG's support department for any questions or issues you may have after reading this document, or when using Sigrid or Sigrid CI. Users in Europe can also contact us by phone at +31 20 314 0953.