Skip to content

GitHub Integration

This guide will help you setup GitHub to integrated with your cluster's Build and Test UI.

Render EngFlow user instead of CI hostname in Engflow UI

When the EngFlow BES receives a BEP stream from Bazel it can only attribute builds to the OS username of the CI runner that is running the invocation and/or the principal stated in the certificate used to authenticate to the BES. In many cases this is not actually the user that is responsible for the build.

To fix this, you can send the GitHub username to the BEP using bazel keywords and your EngFlow cluster will use that username in the UI.

Pipe the github.actor GitHub variable into the command you use to run bazel. Exposing this as an environment variable allows you to use it in a script if you choose to do so.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
...
jobs:
  build:
    steps:
      ...
      - name: My Build
        ...
        env:
          ...
          GITHUB_ACTOR: ${{ github.actor }}
        run: |
          bazel build //:my_target
          ...
          --bes_keywords=engflow:Requester=$GITHUB_ACTOR
          ...

Post invocation results back to a GitHub PR

Your EngFlow cluster can post invocation results directly to a PR to reduce the number of clicks your developers have to make to get to their invocation results.

To do this you will need to create a private GitHub app in your organization's account and install it to your organization. Your EngFlow cluster will then use the private key associated with the app to authenticate and post results back to GitHub from your EngFlow cluster.

See this GitHub documentation for how cluster authenticates to GitHub using the secrets provided.

1. Create and install a private GitHub app

To integrate with GitHub you must create a GitHub app within your organization. The secrets used to authenticate as this app will then be added to your cluster so it may post results back to GitHub.

  1. Authenticate to GitHub as a user which has administrative access to the GitHub organization to which you would like EngFlow to post.

  2. Navigate to the "Getting Started" page in your cluster's UI.

  3. Fill out the form on the right side to create a GitHub app. Provide your GitHub organization name and cluster name. You will be redirected to GitHub to create your app.

  4. Review the app creation screen, it will be auto-populated with the settings necessary for your EngFlow cluster to authenticate and publish to your GitHub.

  5. Select Create GitHub App, this will take you to the app's settings page.

  6. Record the Client ID, this will be needed later.

  7. Under Private keys select Generate a private key. Save the downloaded file, this will be needed later.

  8. On the left sidebar navigate to Install App.

  9. Under the organization you wish to install the app select Install.

  10. Configure which repositories you want EngFlow to be able to interact with and select Install.

  11. Record the number at the end of the URL for the GitHub App installation, (should look something like "12345678") this is your installation ID.

2. Configure your EngFlow cluster to authenticate to GitHub

Contact your EngFlow support engineer and securely send the GitHub app's client ID, installation ID, and private key. They will add this to your cluster's secrets so the cluster can authenticate to GitHub using the private GitHub app you created.

Scheduler restart required

EngFlow will need to roll the schedulers for this to take affect which may temporarily impact build performance.

Please contact us for instructions on how to install and configure the secret into your cluster.

For all GitHub actions that you would like to post back to a PR add the following bazel keywords.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
...
jobs:
  build:
    steps:
      ...
      - name: My Build
        ...
        env:
          ...
          GITHUB_COMMIT: ${{ github.event.pull_request.head.sha }}
          GITHUB_PR_URL: ${{ github.event.pull_request.number != null && format('https://github.com/OWNER/REPO/pull/{0}', github.event.pull_request.number) || '' }}
        run: |
          bazel build //:my_target
          ...
          --bes_keywords="engflow:GitHubCommit=${GITHUB_COMMIT}" \
          --bes_keywords="engflow:GitHubPrUrl=${GITHUB_PR_URL}" \
          ...

Make sure to replace:

  • OWNER with your GitHub organization name
  • REPO with the repo that this PR belongs to