Home

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.

CI Code Quality Release

Environment Variables

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

Environment VariableTypeDescription
statestringThe state of the status. Can be one of pending, success, error, or failure (Github Docs).
target_urlstringThe 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.
descriptionstringA short description of the status.
contextstringA 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 VariableTypeDescription
access_tokenstring(Optional if tokenFile is set): A GitHub Access Token for a user with push access
tokenFilestring(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 VariableTypeDescription
organisationstringThe GitHub organisation/username for the notification. e.g. given https://github.com/crumbhole/ci-github-notifier, the organisation is "crumbhole"
app_repostringThe GitHub repo for the notification. e.g. given https://github.com/crumbhole/ci-github-notifier, the app_repo is "ci-github-notifier"
git_shastringThe SHA1 of the PR or branch you wish to notify
gh_urlstring(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.