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:
- Read/write for Administration (required to add a runner)
- Read-only for Actions (required for us to query the API to determine the queue depth)
- 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.
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:
- Navigate to AWS Console > AWS Secrets Manager > Secrets,
- Locate the key starting
aw_gha_token
- 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
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:
- 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 underFunction URL
. It will look similar tohttps://hn12345678r2s7q5eb33nc5nca0rnhip.lambda-url.us-east-2.on.aws/
- Content Type: please select
application/json
. - Secret: should be generated using your company secret policy
- 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:
- Navigate to AWS Console > AWS Secrets Manager > Secrets,
- Locate the key starting
aw_gha_lambda_webhook_secret
- 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
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.