Installing on GitHub Actions

Provide tokens

Aspect Workflows requires 2 different GitHub tokens to authenticate API calls to GitHub.

info

It is recommended to have 2 separate tokens as the second token is made available during builds, at which point it is preferable to have Read-Only permissions.

In GitHub, choose which account to use to provide credentials. This account must be an administrator on the repositories that use Aspect Workflows.

caution

An administrator role is required to grant API access to register self-hosted runners, see the self-hosted API documentation for more information.

We recommend you make a machine user account to prevent trouble when engineers leave the team, see types of GitHub accounts

Login as that user and make a fine-grained personal access token with the following steps:

1. Open Settings > Developer settings > Personal access tokens.
2. Select Fine-grained tokens > Generate new token.
3. Choose a name like "Aspect Workflows".
4. Set Expiration to the recommended value of "No expiration", which means the token will never expire.
5. Under Repository access, select the repositories that will use Aspect Workflows

If the token appears as "Pending", then you may need organizational level approval. Replace "my-org" with the GitHub org in the following URL to find the request: https://github.com/organizations/my-org/settings/personal-access-token-requests.

GitHub Actions Runner Token

This token is used to create GitHub Actions runners. For each repository that is tested using workflows, the permissions required are:

1. Read/write for administration (required to add a runner)
2. Read-only for Actions (required to query the API to determine the queue depth)
3. Read-only for Metadata (GitHub enables this automatically)

Check the token

To confirm the token is working correctly, try using this curl command, replacing your-org/your-repo with your repository and github_pat_XXX with the token:

curl -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" -H "Authorization: Bearer github_pat_XXX" https://api.github.com/repos/your-org/your-repo/actions/runners

Next, copy the token value into Secrets Manager. There is a secret for each runner group defined in terraform.

1. Navigate to Your Cloud Console > Secrets Manager > Secrets,
2. Locate the keys in the following format aw_gha_token__RUNNER_GROUP_NAME_XXXXXXXXXXXXXXXX.
3. Set the values to the fine-grained token GitHub provided.

Alternatively, Terraform can supply the value.

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

For example, if main.tf contains

main.tf

  gha_runner_groups = {
    default = {
      ...
    }
  }

Then you can configure the secret with:

resource "aws_secretsmanager_secret_version" "this" {
  secret_id     = module.aspect-workflows.gha_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

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. It is highly recommended that this is a separate token to the one used for scaling, and scoped to read-only only access.

For each repository that is tested using workflows, the permissions required are:

1. Read-only for Pull Requests.

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.

Alternatively, Terraform can supply the value.

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

Configure your workflow

The Workflows GitHub Action is published at https://github.com/marketplace/actions/aspect-workflows.

You can follow the instructions there to set it up.

Define workflow ID's (optional)

In order to determine what queued jobs need runners, Workflows runs a query against the GitHub API. This query loops through all active GitHub workflows, including those not managed by Aspect Workflows, which results in more GitHub API calls than necessary. As a performance optimization to avoid these extra API calls, users can specify what workflows require Aspect Workflows runners.

To do this, add a gha_workflow_ids parameter (which expects a list of string) to the relevant runner. For example:

gha_runner_groups = {
  default = {
    ...
    gha_workflow_ids = ["foo", "bar", "baz"]
    ...
  }
}

You can determine the workflow IDs by calling the GitHub API with the following URL pattern:

https://api.github.com/repos/OWNER/REPO/actions/workflows

info

For more information on this API URL, read the GitHub documentation

You may need to add different workflow IDs to different runner groups and a single workflow ID to multiple runner groups.

Common patterns:

• If warming is enabled, then you may have a runner group created specifically for warming. When looking at the API result, take the ID corresponding to the workflow with the path .github/workflows/aspect_workflows_warming.yml.
• If your setup has small and default queues (where small generates the pipeline config and default does the build), then you need to specify the ID of your workflow on BOTH runner groups.
• If you call .github/workflows/.aspect_workflows_reusable.yml from your main workflow and the workflow itself is not doing any work, then you do NOT need to add its ID to a runner group.
• If you have any internal workflows that use Aspect runners then make sure to also add their IDs to the runner groups.

danger

If you added workflow IDs to a runner group, that runner group only monitors jobs from those workflows. A missing ID can result in a runner not pickup up a job.

Alternatively, Terraform can supply the value.

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

For example, if main.tf contains:

main.tf

  gha_runner_groups = {
    default = {
      ...
    }
  }

Then you can configure the secret with:

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

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