Installing on GitLab

info

GitLab is currently only available when hosted on AWS

Provide a token

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 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 in question
3. Set the value to the token

Alternatively, the value can be supplied using Terraform. We expose the AWS Secrets Manager Secret Id via an output from the Workflows terraform module. This ID is named gl_secret_ids["runner group name"] where the runner group name matches the gl_runner_groups input parameter.

For example, if main.tf contains

main.tf

  gl_runner_groups = {
    default = {
      ...
    }
  }

Then the secret can be configured with:

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

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

A working example can be found here: https://gitlab.com/aspect-build/rules_deno/-/blob/main/.gitlab-ci.yml

Enabling Warming

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

In GitLab, navigate to Build -> Schedule Pipelines and create a New Schedule.

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