Installing on CircleCI

Create CircleCI resource classes

In your CircleCI account, navigate to Self-Hosted Runners.

At least two custom "Resource Classes" are required. These used to assign CircleCI jobs to specific runner groups:

1. The default runner group resource class is typically my-org/aspect-default.
2. The warming runner group resource class is typically my-org/aspect-warming.

If overriding the queue names in .aspect/workflows/config.yaml, the preceding resource class names need to be adjusted accordingly. Each additional runner group requires a unique "Resource Class" so that it can be targeted by jobs.

CircleCI provides unique tokens for these pools for Aspect-managed self-hosted runners to connect to CircleCI to accept work. Write these down as you'll need them below.

Generate a CircleCI personal access token

In CircleCI, navigate to https://app.circleci.com/settings/user/tokens and generate a New Token.

Aspect recommends creating this token using a bot account so that it is not tied to a human user account.

Provide CircleCI API tokens

For Aspect Workflows to connect to CircleCI, it needs three credentials for each of the two runner pools created above.

1. resource_class is the Resource Class name created earlier, either my-org/aspect-default or my-org/aspect-warming
2. access_token is the 40-character personal access token created earlier for making API calls to CircleCI.
3. auth_token is the 80-character "resource class token" that CircleCI produced when the Resource Class was created.

The resource_class and auth_token are unique per runner pool, but you can re-use the same access_token for each.

There are two secrets to populate with the credentials for the two runner pools. The secret values should be formatted as JSON object providing these three keys. For example,

{"resource_class":"my-org/aspect-default","access_token":"******","auth_token":"******"}

and,

{"resource_class":"my-org/aspect-warming","access_token":"******","auth_token":"******"}

You can set the values in the AWS console:

1. Navigate to AWS Console > AWS Secrets Manager > Secrets,
2. Locate the keys named aw_cci_<hash>__<runner pool name>, for example aw_cci_63eb73cb0f156210__default and aw_cci_0c03c0e5c34924f0__warming, and set the "Plaintext" values to the JSON strings for the respective runner pools. They also appear as separate Key/value pairs in the AWS user interface.

Alternatively, you can supply the values using Terraform. Workflows exposes the AWS Secrets Manager Secret Id via an output from the Workflows terraform module. This ID is named runner_secret_ids["runner pool name"] where the "runner pool name" matches the cci_runner_groups input parameter.

For example, if main.tf contains

main.tf

  cci_runner_groups = {
    default = {
      max_runners = 10
      ...
    }
    warming = {
      max_runners = 1
      ...
    }
  }

Then you configure these secrets with:

resource "aws_secretsmanager_secret_version" "runner" {
  secret_id     = module.aspect_workflows.runner_secret_ids["default"]
  secret_string = "my-secret-for-default"
}

resource "aws_secretsmanager_secret_version" "runner_warming" {
  secret_id     = module.aspect_workflows.runner_secret_ids["warming"]
  secret_string = "my-secret-for-warming"
}

The secret_string values should be supplied using whatever mechanism you already use for managing secrets.

Configure the workflow

Now the CircleCI configuration file may be updated.

Very simple repositories may be able to use Aspect's CircleCI orb. It is installed into .circleci/config.yaml, following the instructions at https://circleci.com/developer/orbs/orb/aspect-build/workflows.

However, CircleCI is very limited. The Orb must use the continuations feature, and only one continuation may be present in an entire workflow. As an alternative to using the Orb, a large amount of YAML may need to be vendored into the repository. See https://github.com/aspect-build/aspect-cli/blob/main/.circleci/BUILD.bazel for an example.

A number of Workflows features require read-only access to the GitHub API.

For example, if the "Branch Freshness" strategy is set to rebase, it requires a GitHub token to make a GET request to https://api.github.com/repos/{owner}/{repo}/pulls/{pull_number}. The token must therefore be granted read permission to Pull Requests, scoped to any repositories that are tested by Workflows.

This secret can be supplied in Terraform, similarly to the tokens described above.

resource "aws_secretsmanager_secret_version" "gh_api_token" {
  secret_id     = module.aspect-workflows.github_token_secret_id
  secret_string = "my-github-token"
}