Awesome

ci-github-notifier

A lightweight container to post the status of a CI task to GitHub, allowing GitHub users to see the status of a PR or Branch. Designed for cloud native workflows (eg Argo Workflows, or Tekton), but will run wherever a container can be run. Compatible with regular Github and Github Enterprise URLs.

Environment Variables

We pass key information to the container using environment variables. First, we provide the necessary values for the GitHub status API:

Environment Variable	Type	Description
`state`	string	The state of the status. Can be one of `pending`, `success`, `error`, or `failure` (Github Docs).
`target_url`	string	The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the ‘source’ of the Status.
`description`	string	A short description of the status.
`context`	string	A string label to differentiate this status from the status of other systems.

Then we provide GitHub authentication information. We provide one of the following:

Environment Variable	Type	Description
`access_token`	string	(Optional if `tokenFile` is set): A GitHub Access Token for a user with push access
`tokenFile`	string	(Optional if `access_token` is set): Path to a file within the container that contains the GitHub access token. Useful for Vault secrets injection or similar. Takes precedence over `access_token`

Finally we provide Environment Variables that make up the values of the GitHub API url:

Environment Variable	Type	Description
`organisation`	string	The GitHub organisation/username for the notification. e.g. given https://github.com/crumbhole/ci-github-notifier, the organisation is "crumbhole"
`app_repo`	string	The GitHub repo for the notification. e.g. given https://github.com/crumbhole/ci-github-notifier, the app_repo is "ci-github-notifier"
`git_sha`	string	The SHA1 of the PR or branch you wish to notify
`gh_url`	string	(OPTIONAL) The URL of the GitHub API. If omitted, will default to `api.github.com`

Docker run examples

You are unlikely to want to run these in production using docker run, but the following examples give a clear indication of how to execute the container.

Running with environment variables

docker run \
    -e state=pending \
    -e target_url=https://sendible.com \
    -e description="This is an example description" \
    -e context="Example context" \
    -e access_token="123ABC123ABC" \
    -e organisation=crumbhole \
    -e app_repo="ci-github-notifier" \
    -e git_sha="123abc123abc" \
    -e gh_url="api.mydomain.biz" \
    ghcr.io/crumbhole/ci-github-notifier:stable

Mounting tokenFile

docker run \
    -e state=pending \
    -e target_url=https://sendible.com \
    -e description="This is an example description" \
    -e context="Example context" \
    -e tokenFile="/tmp/access_token" \
    -e organisation=crumbhole \
    -e app_repo="ci-github-notifier" \
    -e git_sha="123abc123abc" \
    -e gh_url="api.mydomain.biz" \
    -v /path/to/file:/tmp/access_token \
    ghcr.io/crumbhole/ci-github-notifier:stable

Argo Workflows example

A simple Argo Workflows template can be found in the examples directory.