Installing on CircleCI

Create CircleCI Resource Classes

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

Create two custom "Resource Classes" which assigns incoming requests to specific runner pools. One pool is the primary pool with a name such as my-org/default. The 2nd pool is for Warming and should be named the same as the primary pool with a -warming suffix. For example, my-org/default-warming.

CircleCI will provide 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.

We recommend 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, we need three credentials for each of the two runner pools created above.

1. resource_class is the Resource Class name we created earlier, like my-org/default or my-org/default-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 you created the Resource Class.

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/default","access_token":"******","auth_token":"******"}

and,

{"resource_class":"my-org/default-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__default-warming, and set the "plaintext" values to the JSON strings for the respective runner pools. They will also appear as separate Key/value pairs in the AWS user interface.

Alternatively, you can supply the values using Terraform. We expose 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 your main.tf contains

main.tf

  cci_runner_groups = {
    default = {
      max_runners = 10
      min_runners = 0
      ...
    }
    default-warming = {
      max_runners = 1
      min_runners = 0
      ...
    }
  }

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["default-warming"]
  secret_string = "my-secret-for-default-warming"
}

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

Configure the workflow

Now we can update the CircleCI config file checked into your repo. Install our orb into .circleci/config.yaml, following the instructions at https://circleci.com/developer/orbs/orb/aspect-build/workflows

By default, the "Branch Freshness" strategy is set to rebase, which 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 CircleCI tokens described above.

resource "aws_secretsmanager_secret_version" "gh_rebase_token" {
  secret_id     = module.aspect-workflows.github_rebase_token_secret_id
  secret_string = "my-rebase-token"
}