Installing on Buildkite

Configure a Pipeline

Create a new Pipeline for your Workflows build or choose an existing one and configure it to your preference. If you use GitHub, follow these steps to integrate your repository with Buildkite.

Click on Edit Steps and paste the following:

steps:
    - key: aspect-workflows-setup
      label: ':aspect-build: Setup Aspect Workflows'
      commands:
          - 'rosetta steps | buildkite-agent pipeline upload'
      agents:
          queue: <QUEUE>

Replace <QUEUE> with the name of the runner group's queue in your terraform module declaration. We recommend using aspect-default which is the default queue Aspect Workflows queue name. If using a non-default queue name, you'll also need to specify the queue name in your .aspect/workflows/config.yaml file with queue: <QUEUE>.

tip

You can use the Buildkite provider for Terraform to set up your pipeline programmatically.

Populate secrets

The Workflows terraform module creates two secrets to populate per runner group.

1. Buildkite Agent token. The agent token allows our runners to connect to Buildkite. Under your organization, click on the Agents Tab then click Reveal Agent Token. Copy and paste this token into a secret named like aw_bk_agent_token__<RunnerGroup>_XXXXXXXXXXXXXXXX.

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

For example, if main.tf contains

main.tf

  bk_runner_groups = {
    default = {
      ...
    }
  }

Then the secret can be configured with:

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

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

2. Buildkite API access token. The API token allows us to monitor the agents that we have created for anomalies. Under Personal Settings go to the API Access Tokens tab and click the New API Access Token button. Give it a name such as "Aspect Workflows API Token" and select your organization from the dropdown. Under REST API Scopes we need the Read Agents permission. Once created, copy and paste this token into a secret named like aw_bk_api_token__<RunnerGroup>_XXXXXXXXXXXXXXXX.

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

For example, if main.tf contains

main.tf

  bk_runner_groups = {
    default = {
      ...
    }
  }

Then the secret can be configured with:

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

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

3. Git SSH key. If you use a private repository, set up an SSH key that Workflows runners can use to check out your repository. Under your pipeline's GitHub settings, select the SSH radio button. Then, upload the private key to a secret with a name like aw_bk_git_ssh_key__<RunnerGroup>-XXXXXXXX. If you use GitHub, we recommend using a Deploy Key with read-only access.

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

For example, if main.tf contains

main.tf

  bk_runner_groups = {
    default = {
      ...
    }
  }

Then the secret can be configured with:

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

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

tip

The Workflows module exposes the names of the secrets it creates as an outputs. If you use a tool like Vault, you can wire in secret values automatically via Terraform.

4. GitHub API Token.

A number of Workflows features require read-only access to the GitHub API.

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 workflows

Add a Workflows configuration file to your repository.

(Optional) Custom Buildkite Agent hooks

The Buildkite Agent allows you to declare Agent hooks which it runs at various points throughout the lifecycle of an agent and of jobs.

To supply your own Agent hook, add the hook to the S3 or GCS bucket named aw-buildkite-agent-hooks-XXXXXXXXX under the global/ folder. Runners will find the hooks during bootstrap and install them for the Buildkite Agent to use.

To supply an agent hook that applies only to a specific runner group, add the hook to the runner-group/<runner-group-name> folder instead. Runner group specific hooks will be appended to any global hooks in the global/ folder of the same kind.

info

Workflows will automatically generate pre-bootstrap, pre-checkout, post-checkout, and pre-exit hooks that will be run before any user supplied pre-bootstrap, pre-checkout, post-checkout, and pre-exit hooks.

The Workflows generated pre-bootstrap and pre-exit hooks are used to gather telemetry for the different stages of the build.

The Workflows generated pre-checkout hook configures the SSH key set in the aw_bk_git_ssh_key secret for the runner group, starts the ssh-agent process, and sets the BUILDKITE_BUILD_CHECKOUT_PATH environment variable. The Workflows generated post-checkout removes the SSH key set in the pre-checkout hook and shuts down the ssh-agent process. User supplied pre-checkout and post-checkout hooks must not to conflict with these settings.

tip

You may wish to alternatively try Aspect Workflow's native hooks solution, which allows you to execute code before and after tasks.

(Optional) Customizing the Buildkite Agent configuration

Workflows automatically generates a Buildkite Agent configuration file on runners with a minimal configuration.

To customize the Buildkite Agent configuration further, upload a user buildkite-agent.cfg file to the Workflows Buildkite Agent hooks bucket global/ folder. Runners will fetch the user buildkite-agent.cfg from the Buildkite Agent hooks bucket during bootstrap and use it when generating the Buildkite Agent configuration for the runner.

As with hooks, a custom Buildkite Agent configuration that applies only to a specific runner group can be uploaded to the runner-group/<runner-group-name>/ folder in the Buildkite Agent hooks bucket. If global and runner group user Buildkite Agent configurations are specified, settings in the runner group configuration will take precedence over conflicting settings in the global configuration.

info

The Workflows generated buildkite-agent.cfg file will configure the following settings in the Buildkite Agent configuration:

• token
• name
• build-path
• hooks-path
• spawn
• disconnect-after-job
• disconnect-after-idle-timeout

The above configuration settings will take precedence over conflicting values set in user supplied buildkite-agent.cfg files.

Customizing the git clone depth

To speed up the Preparing working directory step, a shallow clone can be configured in the Buildkite Agent configuration. For large repositories this can make a measurable impact on clone times on new runners.

For example, to specify a clone depth of 100, set the following in either the global or per-runner group Buildkite Agent configuration in the Workflows Buildkite Agent hooks bucket.

git-clone-flags="-v --no-checkout --depth=100"
git-fetch-flags="-v --prune --depth=100"