Set up your GitHub Actions workflow to run Bazel using Aspect.

Aspect Workflows is a self-hosted runner infrastructure for getting best-case performance of running Bazel on your CI/CD pipeline.

See https://docs.aspect.build/workflows for more documentation.

This action depends on infrastructure that's deployed by Aspect Workflows. First sign up for a trial: https://aspect.build/workflows

GitHub Actions has a critical restriction: you cannot re-use a workflow definition from another GitHub org and also target self-hosted runners.

From GitHub docs:

Called workflows that are owned by the same user or organization as the caller workflow can access self-hosted runners from the caller's context.

To work around this, either:

1. Vendor the file into the repository by copying .github/workflows/.aspect-workflows-reusable.yaml to the same location.
2. Fork this repository into your GitHub organization

Start from a standard GitHub Actions workflow file and reference Aspect Workflow's reusable workflow file.

This may be a new or existing file; for example many repositories have an existing .github/workflows/ci.yaml file.

The reusable workflow is configured via the .aspect/workflows/config.yaml file.

If you forked the repo to your org, then replace my-org with your org in this snippet:

jobs:
    aspect-workflows:
        name: Aspect Workflows
        uses: my-org/workflows-action/.github/workflows/[email protected]

If you vendored the file, then instead it will be:

jobs:
    aspect-workflows:
        name: Aspect Workflows
        uses: ./.github/workflows/.aspect-workflows-reusable.yaml

You may want to start out with Aspect Workflows only triggering on certain branches during the trial. You can use an if statement like the following to run on main and on pull requests coming from a branch named aspect-build/*.

jobs:
    aspect-workflows:
        if: github.ref == 'refs/heads/main' || startsWith(github.head_ref, 'aspect-build/')

See https://docs.aspect.build/workflows/configuration/delivery for a high-level overview of the CD process.

To install it, add another YAML file to create a new GitHub Actions Workflow, commonly .github/workflows/aspect-workflows-delivery.yaml.

First, allow manual delivery to be triggered in the GitHub Actions web UI, collecting two user inputs (the commit SHA and targets to deliver):

on:
    workflow_dispatch:
        inputs:
            delivery_commit:
                description: The commit to checkout and run the delivery from. Targets listed in the delivery manifest for this commit will be delivered unless specific targets are listed in `delivery_targets`.
                type: string
                required: true
            delivery_targets:
                description: List of Bazel targets to deliver, delimited by spaces. For example, \`//app/a:push_release //app/b:push_release\`. If empty, targets listed in the delivery manifest for the target commit will be delivered.
                type: string
                required: false

Now define the job. This has a few steps:

1. Configure the environment.
2. Checkout the repository at the commit to be delivered.
3. Check that the build agent is healthy.
4. Run Aspect Workflows 'composite action' with the delivery task, providing the user inputs via environment variables.

jobs:
    delivery:
        name: Aspect Workflows Delivery
        runs-on: [self-hosted, aspect-workflows, aspect-default]
        steps:
            - name: Configure environment
              run: /etc/aspect/workflows/bin/configure_workflows_env
            - uses: actions/checkout@v4
              with:
                  ref: ${{ inputs.delivery_commit }}
                  fetch-depth: 0
            - name: Agent health checks
              run: /etc/aspect/workflows/bin/agent_health_check
            - name: Run Delivery
              uses: aspect-build/[email protected]
              with:
                  task: delivery
              env:
                  DELIVERY_COMMIT: ${{ inputs.delivery_commit }}
                  DELIVERY_TARGETS: ${{ inputs.delivery_targets }}

A full, operational example of this file: https://github.com/aspect-build/rules_jasmine/blob/main/.github/workflows/aspect-workflows-delivery.yaml

You can get a notification when a build fails on a release branch. Then your oncall can acknowledge the problem and work with code owners to quickly revert.

Confusingly, we're going to use a Slack feature that's also called "workflows". You can read about it in the Slack docs.

1. In slack, click your workspace name in the upper-left.
2. Select Tools from the menu.
3. Select Workflow Builder
4. In the pop-up window, click Create in the top right.
5. Enter a name, for example Github Actions Buildcop.
6. In the next dialog, select Webhook to start this workflow.
7. Click Add Variable and use the key gha_url with a Data type of Text.
8. Click Next.
9. Click Add Step. You can choose what to do, for example, Send a message. You'll be able to add the gha_url variable in the message. This is will be filled in with a link back to the broken build on GitHub Actions.
10. Click Publish. Copy the resulting webhook URL.

1. Choose whether the secret will be in the Organization settings or the Repository settings.
2. In the GitHub UI, add a secret in the settings. See the GitHub docs.
3. We suggest naming the secret SLACK_WEBHOOK_URL. The value should be the webhook URL you copied earlier.

1. Add a secrets section to the aspect-workflows job in your ci.yaml file. It should look like this:

jobs:
  aspect-workflows:
    ...
    secrets:
      slack_webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}