Skip to main content
Version: 5.9.x

Installing on GitHub Actions

Provide a token

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

In GitHub, choose which account will give credentials. This account must be an admin on the repositories that use Aspect Workflows.

The admin role is required to grant API access to register self-hosted runners, see https://docs.github.com/en/rest/actions/self-hosted-runners

We recommend you make a machine user account to prevent trouble when engineers leave the team, see https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts

Login as that user and make a Fine-grained personal access token:

  • Settings > Developer settings > Personal access tokens
  • Fine-grained tokens > Generate new token
  • Choose a name like 'Aspect Workflows'
  • Expiration: we recommend 1 year, which is the maximum allowed. It will need to be created again when it expires.
  • Repository access > Select the repositories that will use Aspect Workflows
  • Repository permissions:
    1. Read/write for Administration (required to add a runner)
    2. Read-only for Actions (required for us to query the API to determine the queue depth)
    3. Read-only for Metadata is mandatory and will already be selected

If the token appears as "Pending", then approval may be required at the organization level. 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.

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

Copy the token value into Secrets Manager:

  1. Navigate to AWS Console > AWS Secrets Manager > Secrets,
  2. Locate the key starting aw_gha_token
  3. Set the value to the fine-grained token GitHub provided.

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 gha_secret_ids["runner group name"] where the "runner group name" matches the gha_runner_groups input parameter.

For example, if main.tf contains

main.tf
  gha_runner_groups = {
default = {
...
}
}

Then the secret can be configured with:

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

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

A number of Workflows features require read-only access to the GitHub API. We highly recommend that this is a separate token to the one used above, and scoped to read-only only access on pull requests.

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"
}

Configure your workflow

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

You can follow the instructions on that site to set it up.

(Optional) Define workflow ID's

In order to determine what queued jobs need runners, Workflows runs a query against the GitHub API. This query will loop through all active GitHub workflows, including those not managed by Aspect Workflows. This will result 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"]
...
}
}

The workflow ID's can be determined with a call to the GitHub API at the following URL:

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

For more information on this API URL please see: https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#list-repository-workflows

(Optional) Setup webhook

To scale the worker pool, Workflows polls GitHub Actions to find new workflow runs every minute. This polling delay means that scale-out of new workers takes longer, but this may be avoided by setting up a webhook from GitHub.

In the GitHub settings for the repository, add a new webhook. Navigate to https://github.com/[org]/[repo]/settings/hooks/new, then fill in the form:

  1. Payload URL: you need to find the URL for our scaling lambda. This URL can be found by navigating in the AWS Console to Lambda > Functions, then select the lambda named aw_gha_scaling__{GH_RUNNER_NAME}__{REPO_KEY_IN_SNAKE_CASE}. Once the lambda is selected, the URL can be found under Function URL. It will look similar to https://hn12345678r2s7q5eb33nc5nca0rnhip.lambda-url.us-east-2.on.aws/
  2. Content Type: please select application/json.
  3. Secret: should be generated using your company secret policy
  4. Which events would you like to trigger this webhook?: choose Let me select individual events, then check: Workflow jobs and Workflow runs.

Copy the generated secret into Secrets Manager:

  1. Navigate to AWS Console > AWS Secrets Manager > Secrets,
  2. Locate the key starting aw_gha_lambda_webhook_secret
  3. Set the value to generated secret

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 gha_lambda_webhook_secret_ids["runner group name"] where the runner group name matches the gha_runner_groups input parameter.

For example, if main.tf contains

main.tf
  gha_runner_groups = {
default = {
...
}
}

Then the secret can be configured with:

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

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