Installing on GitHub Actions

Provide a token

Aspect Workflows requires a token to make 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. 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

You can confirm the token is working correctly with 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, you can supply the value 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 your main.tf contains

main.tf

  gha_runner_groups = {
    default = {
      ...
    }
  }

Then you configure this secret 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.

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, we run a query against the Github API. If there are active Github workflows that are not managed by Aspect Workflows, then we will check those as well. This will result in more GitHub API calls than necessary. 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 our worker pool, we poll GitHub Actions to find new workflow runs every minute. To avoid that polling delay, you can set up a webhook from GitHub.

In the GitHub settings for your 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, you can supply the value 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 your main.tf contains

main.tf

  gha_runner_groups = {
    default = {
      ...
    }
  }

Then you configure this secret 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.

(Optional) Upload coverage to Codecov

Enable uploading a combined coverage report to codecov.io in your Workflows config file:

---
tasks:
    test:
        coverage:
            codecov_upload: true

If your repository is not public, then add a secret in GitHub named CODECOV_TOKEN containing your Codecov upload token.

Allow the resuable workflow to inherit the codecov token secret by setting secrets: inherit and declaring the secret name in inherited_secrets. For example:

jobs:
    aspect-workflows:
        name: Aspect Workflows
        uses: my-org/workflows-action/.github/workflows/.aspect-workflows-reusable.yaml@5.8.0
        secrets: inherit
        with:
            inherited_secrets: CODECOV_TOKEN