github-status-updater

Command line utility for updating GitHub commit statuses and enabling required status checks for pull requests.

Useful for CI environments to set more specific commit and build statuses, including setting the target URL (the URL of the page representing the build status, or the URL of the deployed application).

NOTE: Create a GitHub token with repo:status and public_repo scopes

NOTE: The icons in the image above are the avatars of the users for which the GitHub access tokens are issued

Usage

NOTE: The module accepts parameters as command-line arguments or as ENV variables (or any combination of command-line arguments and ENV vars). Command-line arguments take precedence over ENV vars.

Command-line argument	ENV var	Description
action	GITHUB_ACTION	Action to perform: `update_state` or `update_branch_protection`
token	GITHUB_TOKEN	Github access token
owner	GITHUB_OWNER	Github repository owner
repo	GITHUB_REPO	Github repository name
ref	GITHUB_REF	Commit SHA, branch name or tag
state	GITHUB_STATE	Commit state. Possible values are `pending`, `success`, `error` or `failure`
context	GITHUB_CONTEXT	Status label. Could be the name of a CI environment (e.g. `my-ci`)
description	GITHUB_DESCRIPTION	Short high level summary of the status
url	GITHUB_TARGET_URL	URL of the page representing the status

build the Go program locally

go get

CGO_ENABLED=0 go build -v -o "./dist/bin/github-status-updater" *.go

run locally with ENV vars

run_locally_with_env_vars.sh

export GITHUB_ACTION=update_state
export GITHUB_TOKEN=XXXXXXXXXXXXXXXX
export GITHUB_OWNER=cloudposse
export GITHUB_REPO=github-status-updater
export GITHUB_REF=XXXXXXXXXXXXXXXX
export GITHUB_STATE=success
export GITHUB_CONTEXT="my-ci"
export GITHUB_DESCRIPTION="Commit status with target URL"
export GITHUB_TARGET_URL="https://my-ci.com/build/1"

./dist/bin/github-status-updater

After the above command is executed, the commit status will be updated to success with the target URL https://my-ci.com/build/1 (the green check mark in the image below)

run locally with command-line arguments

run_locally_with_command_line_args.sh

./dist/bin/github-status-updater \
        -action update_state \
        -token XXXXXXXXXXXXXXXX \
        -owner cloudposse \
        -repo github-status-updater \
        -ref XXXXXXXXXXXXXXX \
        -state success \
        -context "my-ci" \
        -description "Commit status with target URL" \
        -url "https://my-ci.com/build/1"

build the Docker image

NOTE: it will download all Go dependencies and then build the program inside the container (see Dockerfile)

docker build --tag github-status-updater  --no-cache=true .

run in a Docker container with ENV vars

run_docker_with_env_vars.sh

docker run -i --rm \
        -e GITHUB_ACTION=update_state \
        -e GITHUB_TOKEN=XXXXXXXXXXXXXXXX \
        -e GITHUB_OWNER=cloudposse \
        -e GITHUB_REPO=github-status-updater \
        -e GITHUB_REF=XXXXXXXXXXXXXXXX \
        -e GITHUB_STATE=success \
        -e GITHUB_CONTEXT="my-ci" \
        -e GITHUB_DESCRIPTION="Commit status with target URL" \
        -e GITHUB_TARGET_URL="https://my-ci.com/build/1" \
        github-status-updater

run in a Docker container with local ENV vars propagated into the container's environment

run_docker_with_local_env_vars.sh

export GITHUB_ACTION=update_state
export GITHUB_TOKEN=XXXXXXXXXXXXXXXX
export GITHUB_OWNER=cloudposse
export GITHUB_REPO=github-status-updater
export GITHUB_REF=XXXXXXXXXXXXXXXX
export GITHUB_STATE=success
export GITHUB_CONTEXT="my-ci"
export GITHUB_DESCRIPTION="Commit status with target URL"
export GITHUB_TARGET_URL="https://my-ci.com/build/1"

docker run -i --rm \
        -e GITHUB_ACTION \
        -e GITHUB_TOKEN \
        -e GITHUB_OWNER \
        -e GITHUB_REPO \
        -e GITHUB_REF \
        -e GITHUB_STATE \
        -e GITHUB_CONTEXT \
        -e GITHUB_DESCRIPTION \
        -e GITHUB_TARGET_URL \
        github-status-updater

run in a Docker container with ENV vars declared in a file

run_docker_with_env_vars_file.sh

docker run -i --rm --env-file ./example.env github-status-updater

GitHub Required Status Checks

The module can be used to update required status checks for Pull Requests.

This is useful for CI environments to set build statuses with URLs to the build pages.

First, repository administrators need to enforce the branch protection and required status checks before a branch is merged in a pull request or before commits on a local branch can be pushed to the protected remote branch.

https://help.github.com/articles/enabling-required-status-checks

Then, to add my-ci as a status check for branch test of the github-status-updater repo, execute the update_branch_protection action locally

./dist/bin/github-status-updater \
        -action update_branch_protection \
        -token XXXXXXXXXXXXXXXXXXXXXX \
        -owner cloudposse \
        -repo github-status-updater \
        -ref test \
        -context my-ci

or in a Docker container

docker run -i --rm \
        -e GITHUB_ACTION=update_branch_protection \
        -e GITHUB_TOKEN=XXXXXXXXXXXXXXXX \
        -e GITHUB_OWNER=cloudposse \
        -e GITHUB_REPO=github-status-updater \
        -e GITHUB_REF=test \
        -e GITHUB_CONTEXT="my-ci" \
        github-status-updater

After the command executes, status check my-ci will be enabled for the branch as shown in the image below

When you create a pull request for the branch, my-ci gets a notification from GitHub, starts the build, and updates the build status to pending by executing the following command to update the status of the last commit (ref XXXXXXXXXXXXXXX)

./dist/bin/github-status-updater \
        -action update_state \
        -token XXXXXXXXXXXXXXXX \
        -owner cloudposse \
        -repo github-status-updater \
        -ref XXXXXXXXXXXXXXX \
        -state pending \
        -context "my-ci" \
        -description "still building..." \
        -url "https://my-ci.com/build/1"

In case of any build errors, my-ci updates the build status to error with the error message in the description parameter

./dist/bin/github-status-updater \
        -action update_state \
        -token XXXXXXXXXXXXXXXX \
        -owner cloudposse \
        -repo github-status-updater \
        -ref XXXXXXXXXXXXXXX \
        -state error \
        -context "my-ci" \
        -description "build error" \
        -url "https://my-ci.com/build/1"

When the build succeeds, my-ci updates the build status to success

./dist/bin/github-status-updater \
        -action update_state \
        -token XXXXXXXXXXXXXXXX \
        -owner cloudposse \
        -repo github-status-updater \
        -ref XXXXXXXXXXXXXXX \
        -state success \
        -context "my-ci" \
        -description "build completed" \
        -url "https://my-ci.com/build/1"

Integrating with CodeFresh CI/CD Pipelines

github-status-updater can be easily integrated into CI/CD pipelines, especially those that use containers for build steps.

codefresh.yml shows a complete example of a CodeFresh pipeline which performs the following steps:

Builds a Docker image for the application
Builds a Helm chart
Pushes the Docker images (for commits, branches and tags) to CodeFresh repository
Executes update_branch_protection action on github-status-updater Docker container to add Staging Environment as a required status check
Executes update_state action on github-status-updater Docker container to update Staging Environment deployment status to pending
Deploys the Helm chart to a Kubernetes cluster
Executes update_state action on github-status-updater Docker container to update Staging Environment deployment status to success

References

Help

Got a question?

File a GitHub issue, send us an email or reach out to us on Gitter.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Developing

If you are interested in being a contributor and want to get involved in developing github-status-updater, we would love to hear from you! Shoot us an email.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

Fork the repo on GitHub
Clone the project to your own machine
Commit changes to your own branch
Push your work back up to your fork
Submit a Pull request so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

License

See LICENSE for full details.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

About

github-status-updater is maintained and funded by Cloud Posse, LLC.

Like it? Please let us know at hello@cloudposse.com

We love Open Source Software!

See our other projects or hire us to help build your next cloud platform.

Contributors

Erik Osterman	Andriy Knysh

cloudposse/github-status-updater