Installing on GitLab

info

GitLab is currently only available when hosted on AWS.

Provide tokens

Aspect Workflows requires a token to authenticate API calls to GitLab.

Login to GitLab and navigate to Preferences > Access Tokens. Click Add new token, give it a name, select an expiration date, and provide it with the api scope. Then click Create personal access token.

Check the token

To confirm the token is working correctly, try using this curl command, replacing some-project-id with the GitLab repository ID and glpat-XXX with the GitLab token:

curl --header "PRIVATE-TOKEN: glpat-XXX" "https://gitlab.com/api/v4/projects/some-project-id/runners"

Copy the token value into Secrets Manager:

1. Navigate to AWS Console > AWS Secrets Manager > Secrets.
2. Locate the key starting with aw_gl_token followed by the name of the runner group.
3. Set the value to the token.

Alternatively, Terraform can supply the value.

An output from the Workflows Terraform module exposes the AWS Secrets Manager Secret ID. The ID is named gl_secret_ids["runner group name"] where "runner group name" matches the gl_runner_groups input parameter.

For example, if main.tf contains:

main.tf

  gl_runner_groups = {
    default = {
      ...
    }
  }

Then you can configure the secret with:

resource "aws_secretsmanager_secret_version" "this" {
  secret_id     = module.aspect-workflows.gl_secret_ids["default"]
  secret_string = "my-value"
}

You should supply the secret_string value using whatever mechanism you already use for managing secrets.

GitHub API token secret

A number of Workflows features require read-only access to the GitHub API. For example, the "Format" task uses a GitHub token to fetch the changed files in a PR.

Create a fine-grained Personal Access Token (PAT) and grant the read permission for Pull Requests, scoped to any repositories that are tested by Workflows.

You may need to enable the use of PATs in your organization's settings.

Next, copy the token value into Secrets Manager:

1. Navigate to Your Cloud Console > Secrets Manager > Secrets.
2. Locate the key in the following format aw_gh_api_token__XXXXXXXXXXXXXXXX.
3. Set the value to the fine-grained token GitHub provided.

Terraform can also supply this secret.

resource "aws_secretsmanager_secret_version" "gl_api_token" {
  secret_id     = module.aspect-workflows.gitlab_token_secret_id
  secret_string = "my-gitlab-token"
}

Configure a Pipeline

Edit the .gitlab-ci.yml file and add the following stages:

stages:
    - 'Setup Aspect Workflows'
    - 'Trigger Aspect Workflows'

aspect-workflows-setup:
    script: rosetta steps > .gitlab-aspect-workflows.yaml
    stage: 'Setup Aspect Workflows'
    tags:
        - aspect-workflows
        - RUNNER_GROUP_NAME
    artifacts:
        paths:
            - .gitlab-aspect-workflows.yaml

aspect-workflows-trigger:
    stage: 'Trigger Aspect Workflows'
    trigger:
        include:
            - artifact: .gitlab-aspect-workflows.yaml
              job: aspect-workflows-setup
        strategy: depend

You can find a working example in this repository https://gitlab.com/aspect-build/rules_deno/-/blob/main/.gitlab-ci.yml

Enabling warming

Warming periodically caches the results of repository rule executions to speed up the first build on a cold runner and reduce the chances of dependency fetching failures. Bazel does not natively cache the results of repository rules.

In the runner group in Terraform, set warming = true.

In GitLab, navigate to Build > Schedule Pipelines, create a New Schedule, and take the following steps:

1. Set the description to "Aspect Workflows Warming".
2. Select how often the warming job should run via the Interval Pattern section. As a starting point, try 0 08-22/1 * * *.
3. Set a target branch.
4. Create a variable named ASPECT_WORKFLOWS_ENABLE_WARMING and populate it with the value 1.
5. Ensure that the Activated box is checked'