@code-pushup/gitlab-ci v0.3.2

Code PushUp - GitLab pipelines template

🤖 Integrate Code PushUp into your GitLab CI/CD pipelines.

Features

• 📃 Collects a Code PushUp report on push to remote branch.
• 📉 Uploads reports to job artifacts and/or Code PushUp portal (optional).
• 💬 When a MR is opened/updated, compares reports for source and target branches, and creates/updates a MR comment which summarizes the impact of the changes.
• 🏢 Supports monorepo setups - runs per project and summarizes comparisons in a single MR comment.

Setup

Include the template in your .gitlab-ci.yml:

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

include:
  - https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml

This creates a code-pushup job, which runs the Code PushUp CLI using the config file from the repo. Reports are then available as job artifacts. If you integrate the Code PushUp portal, reports will be uploaded there as well.

GitLab token

Merge request pipelines will also trigger a comparison between reports from source and target branches, resulting in a Markdown comment being posted to the MR. This requires access to the GitLab REST API, so a token must be configured using either of these environment variables:

• CP_GITLAB_TOKEN - for personal access tokens, group access tokens or project access tokens
• CP_GITLAB_OAUTH_TOKEN - for OAuth 2.0 tokens

You can define a CI/CD variable in project or group settings for this purpose, so that the token can be masked and hidden. Alternatively, you can set the environment variable using an external secrets management provider supported by GitLab.

Configuring the job

By default, the code-pushup assumes a standalone npm project in root directory and runs using the Node LTS Docker image. It installs all npm dependencies, before executing the underlying @code-pushup/gitlab-ci package. (Refer to code-pushup.yml for the full job configuration.)

These defaults may not be the right fit for your repository. In which case you can override or add properties for the code-pushup job. For example:

• If you're using Yarn instead of npm:

  code-pushup:
    before_script:
      - yarn install --frozen-lockfile

• To set which stage the job runs in:

  code-pushup:
    stage: report

• To use a custom Docker image (must have Node.js installed):

  code-pushup:
    image: node:20

• If artifacts from a previous job are required:

  code-pushup:
    needs:
      - test

• To trigger job only on push to specific branches:

  code-pushup:
    rules:
      - if: $CI_COMMIT_BRANCH == "develop"
      - if: $CI_COMMIT_BRANCH == "master"
      - if: $CI_COMMIT_BRANCH =~ /^release/

Additionally, you can customize inputs when including the template. For example:

• To enable debug logs:

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        debug: true

• To run Code PushUp CLI via a package.json script (instead of the binary executable):

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        bin: npm run code-pushup --

• To run Code PushUp in a sub-folder:

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        directory: code-pushup

• To run Code PushUp in monorepo mode:

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        monorepo: true

  • To skip auto-detection by specifying which tool you're using (options are nx, turbo, yarn, pnpm, npm):

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: true
          monorepo_tool: pnpm

  • If your monorepo doesn't use any of the supported tools, you can specify a comma-separated list of folder paths instead (supports globs):

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: true
          monorepo_projects: frontend, backend/*

  • If your projects' script/task/target is called something other than code-pushup:

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: true
          monorepo_task: analyze

  • To run tasks in parallel for multiple projects at once:

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: true
          monorepo_parallel: true

  • To customize the maximum number of parallel tasks:

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: true
          monorepo_parallel: true
          monorepo_parallel_max: 3

  • To apply custom projects filter for nx show projects in Nx monorepo:

    include:
      - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
        inputs:
          monorepo: nx
          monorepo_nx_projects_filter: '--with-target=code-pushup --affected --projects=apps/* exclude=*-e2e'

• To disable MR comment:

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        skip_comment: true

• To compare reports for Git branches/tags other than MR source and target branches:

  include:
    - remote: https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/latest/code-pushup.yml
      inputs:
        custom_source_ref: release/1.3.0
        custom_target_ref: v1.2.3

Versioning

The template is versioned using Git semver tags:

• the latest tag
• major tags (e.g. v1)
• minor tags (e.g. v1.2)
• full version tags (e.g. v1.2.3)

You can include any of these in the template URL. For example, if you're concerned about breaking changes, you can refer to a major version instead of latest:

include:
  - https://gitlab.com/code-pushup/gitlab-pipelines-template/-/raw/v1/code-pushup.yml