Feeding Yontrack from GitLab CI/CD

Note

Make sure Yontrack is configured for GitLab. The gitlab SCM engine matches your pipeline against the GitLab configurations registered in Yontrack, so at least one of them must name your instance.

Yontrack token

First, your GitLab pipelines need to be able to connect to Yontrack.

In Yontrack, create a token.

In GitLab, at the project or group level, under Settings > CI/CD > Variables, create:

a variable named YONTRACK_URL containing the URL of your Yontrack instance
a masked variable named YONTRACK_TOKEN containing the token you created in the previous step

The CI configuration file

Create a .yontrack/ci.yaml file at the root of your repository:

version: v1
configuration: {}

Note

This uses a default configuration for the items created in Yontrack.

See CI Configuration for more information.

Calling Yontrack from a job

The Yontrack CLI is the way in. Install and authenticate it in your job — see the CLI's own documentation for the installation and for yontrack config — then call yontrack ci config once, early in the pipeline: it creates the project, the branch and the build, and every later call attaches itself to that build.

stages:
  - setup
  - build

yontrack-config:
  stage: setup
  script:
    # The Yontrack CLI is installed and pointed at $YONTRACK_URL with $YONTRACK_TOKEN beforehand
    - yontrack ci config
      --file .yontrack/ci.yaml
      --env GITLAB_CI="$GITLAB_CI"
      --env CI_PROJECT_URL="$CI_PROJECT_URL"
      --env CI_PROJECT_PATH="$CI_PROJECT_PATH"
      --env CI_PROJECT_NAME="$CI_PROJECT_NAME"
      --env CI_COMMIT_SHA="$CI_COMMIT_SHA"
      --env CI_COMMIT_REF_NAME="$CI_COMMIT_REF_NAME"
      --env CI_MERGE_REQUEST_IID="$CI_MERGE_REQUEST_IID"
      --env CI_PIPELINE_ID="$CI_PIPELINE_ID"
      --env CI_PIPELINE_IID="$CI_PIPELINE_IID"
      --env CI_PIPELINE_URL="$CI_PIPELINE_URL"

The gitlab-ci CI engine and the gitlab SCM engine are detected automatically from these variables — there is nothing to name explicitly.

Do not pass the whole CI_ namespace

It is tempting to write --env-all CI_, as the Bitbucket Pipelines page does for BITBUCKET_. Don't: CI_REPOSITORY_URL and CI_JOB_TOKEN both carry the job token, and neither is used by Yontrack. CI_PROJECT_URL names the same repository without any credential, and it is the variable the engine reads.

Validating and promoting

Once the build exists, the rest of the CLI works as it does anywhere else:

unit-tests:
  stage: build
  script:
    - ./run-tests.sh
    - yontrack validate --validation UNIT --status PASSED

A validation that reflects whether the step succeeded, and fails the job afterwards:

unit-tests:
  stage: build
  script:
    - STATUS=PASSED
    - ./run-tests.sh || STATUS=FAILED
    - yontrack validate --validation UNIT --status "$STATUS"
    - test "$STATUS" = PASSED

Merge request pipelines

Merge request pipelines are rejected, as they are on every other CI engine: Yontrack tracks branches, not merge requests. A pipeline where CI_MERGE_REQUEST_IID is set gets a branch name of PR-<iid>, which the CI configuration refuses.

Guard the Yontrack jobs so they do not run at all for a merge request:

yontrack-config:
  stage: setup
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - when: on_success
  script:
    - # ... as above

Tag pipelines

In a tag pipeline, CI_COMMIT_REF_NAME is the tag name, not a branch, and CI_COMMIT_BRANCH is not set at all. If you feed Yontrack from tag pipelines, give the branch explicitly:

  script:
    - yontrack ci config --file .yontrack/ci.yaml --env BRANCH_NAME=main --env GITLAB_CI="$GITLAB_CI" # ... and the rest