Github Extension

The Github extension allows Gofer pipelines to be run on Github webhook events. This makes it possible to write event driven workloads that depend on an action happening on Github.

See the events section below for all supported events and the environment variables they pass to each pipeline.

Pipeline Configuration

Example

gofer pipeline subscribe simple github run-tests \
    -s "repository=clintjedwards/experimental" \
    -s "event_filter=pull_request_with_check/opened,synchronize,reopened"

Extension Configuration

The Github extension isn't installed by default. It requires a Github app of your own; the setup walkthrough below covers creating one and installing the extension.

Secret settings must be global secret references like global_secret{{github-app-key}}.

Example

[[extensions.install]]
id = "github"
manifest = "https://raw.githubusercontent.com/clintjedwards/gofer/v<gofer version>/containers/extensions/github/manifest.toml"
[extensions.install.settings]
app_id = "112348"
app_installation = "99560091"
app_key = "global_secret{{github-app-key}}"
app_webhook_secret = "global_secret{{github-app-webhook-secret}}"
gofer_url = "https://gofer.example.com"

Setting it up

Due to the nature of Github's API and webhooks, you'll need to first set up a new Github app to use with Gofer's Github extension. Once this app has been set up, you'll have everything you need to configure the extension.

Here is a quick and dirty walkthrough on the important parts of setting up the Github application.

1. Create a new Github application:

Github's documentation will be the most up to date and relevant so please see their walkthrough.

On the configuration page for the new Github application the following should be noted:

• APP ID: Take note of the id; it will be used later for extension configuration.

• Webhook URL: Should be the address of your Gofer's external extension instance and pointing to the events/github endpoint:

  ex: https://mygoferinstance.yourdomain.com/external/github

• Webhook Secret: Make this a secure, long, random string of characters and note it for future extension configuration.

• Private Keys: Generate a private key and keep the .pem file Github gives you; you'll store it in Gofer's secret store in step 3.

2. Find the installation ID

Once the Github application has been created, install it. This will give you an opportunity to configure the permissions and scope of the Github application. It is recommended that you give read-only permissions to any permissions that might include webhooks and read-write for code-suite and code-runs.

You might also utilize this Github App to perform other actions within Github with either other extensions or your own pipeline jobs. Remember to allow the correct permissions for all use cases.

The installation ID is unfortunately hidden in an event that gets sent once the Github app has been created and installed. You can find it by navigating to the settings page for the Github application and then viewing it in the "Recent Deliveries" page.

🪧 These recent deliveries only last a short amount of time, so if you take a while to check on them, they might not exist anymore. If that has happened you should be able to create another event and that will create another recent delivery.

3. Store the secrets

Put the private key and webhook secret in Gofer's global secret store. Leaving out the value prompts for it, which keeps it out of your shell history.

gofer secret global put github-app-key < ~/Downloads/myorg-gofer.2022-01-24.private-key.pem
gofer secret global put github-app-webhook-secret

4. Add the extension to Gofer's config

Add an [[extensions.install]] entry like the example above, with your app ID and installation ID and references to the two secrets. Point manifest at the github manifest for your version of Gofer.

gofer extension manifest <manifest url> --id github prints this block for you, with every setting documented.

5. Reload

gofer extension reload

Gofer shows the extension it's about to install and its settings; confirm, and it starts. If it doesn't, gofer extension list shows why and gofer extension logs github shows what the extension itself reported.

Events

Gofer's extensions have the ability to pass along event specific information in the form of environment variables that get injected into each container's run. Most of these variables are pulled from the webhook request that comes in.

Below is a breakdown of the environment variables that are passed to a run based on the event that was generated. You can find more information about the format the variables will be in by referencing the payloads for the event.

Events below are the only events that are supported.