Project Status: Alpha
Command-line utility to allow creating arbitrary GitHub checks from other command-line utilities.
If you're using GitHub actions, have a look at Lint Action instead, which is both more full-featured and doesn't require you to create a GitHub app and install it.
The use case this was designed for is when you have an existing CI system that is not running via GitHub actions, and you'd like to use GitHub checks.
GitHub checks allow you to post line-level annotations to files in Pull Requests and commits, which is especially useful for linters and other code analysis tools that you may want to run before code is merged.
In order to use GitHub checks on commits and pull requests, you need to have
a GitHub app provisioned and installed in your organization with write scope
on the checks permission.
Precompiled binaries are available for all releases on GitHub. Because they are static binaries, you can simply download them and run them. For example, on Linux:
curl -L https://github.com/roverdotcom/checkbridge/releases/download/v0.0.4/checkbridge-v0.0.4.linux-amd64.tar.gz \
| tar zxf - -C /usr/local/binYou can also install from source if you have Go 1.11+ installed:
go get github.com/roverdotcom/checkbridgeThis will install the tip of master (not recommended for production usage) into $GOPATH/bin/
checkbridge requires GitHub credentials to report checks. Read through the
configuration and authentication sections to get started. Once configured,
you can create checks by piping your desired tool into a checkbridge
subcommand. For example:
golint ./... | checkbridge golintMost configuration options can be passed as either command-line arguments or
environment variables. All flags have shorthand values, run checkbridge --help
to see them:
Flags:
-o, --annotate-only only leave annotations, never mark check as failed
-a, --application-id int GitHub application ID (numeric)
-c, --commit-sha string commit SHA to report status checks for
-d, --details-url string details URL to send for check
-z, --exit-zero exit zero even when tool reports issues
-f, --file string read input from named file instead of stdin
-r, --github-repo string GitHub repository (e.g. 'roverdotcom/checkbridge')
-h, --help help for checkbridge
-i, --installation-id int GitHub installation ID (numeric)
-m, --mark-in-progress mark check as in progress before parsing
-p, --private-key string GitHub application private key path or value
-v, --verbose verbose output
| Flag | Environment Variable |
|---|---|
--application-id |
CHECKBRIDGE_APPLICATION_ID |
--private-key |
CHECKBRIDGE_PRIVATE_KEY |
The following flags can be configured, but are not required by default.
| Flag | Environment Variable |
|---|---|
--installation-id |
CHECKBRIDGE_INSTALLATION_ID |
--commit-sha |
CHECKBRIDGE_COMMIT_SHA |
--github-repo |
CHECKBRIDGE_GITHUB_REPO |
--github-token |
CHECKBRIDGE_GITHUB_TOKEN |
--installation-id will be looked up dynamically if not provided, by doing a GET to
/repos/:owner/:repo/installation with the provided private key / application ID.
--commit-sha will be read from $GITHUB_SHA, $BUILDKITE_COMMIT, or $(git rev-parse HEAD)
--github-repo will be read from $GITHUB_REPOSITORY or $BUILDKITE_REPO if present
--github-token will be read from $GITHUB_TOKEN if present (i.e. when run via GitHub actions)
Using the GitHub checks API requires a GitHub app to be created and installed, with checks
permission on the repo you're running against.
GitHub application tokens, unlike GitHub user tokens, are short-lived (1 hour) and thus must
usually be fetched for each run. When running via GitHub actions, you automatically have a
token (available under secrets.github_token) available for the "GitHub actions" application
for your use. You can see an example of this in this repo's lint.yml
workflow.
If you're running via GitHub actions, simply provide the token (as --github-token,
$GITHUB_TOKEN, or $CHECKBRIDGE_GITHUB_TOKEN) and you're good to go. If you're not running via
GitHub actions (for example, you're using BuildKite), read on.
First, you'll need to create a GitHub app.
You'll start with registering your app. Give it a descriptive name and a homepage (these are required fields). We won't be doing any OAuth (user authorization) so you can leave most of the rest blank. Under the "Permissions" section, you'll need to select "Read & write" access to the "Checks" permission.
If you're going to use your application on an organization (as opposed to just your own repos), select "Any account" under "Where can this GitHub App be installed?"
Once created, you'll need to grab two pieces of information:
- The application ID, which will be at the very top of the page ("App ID")
- A private key, at the very bottom of the page. You can generate a new one when your
app is first created. This will prompt you to download a
.pemfile containing the private key.
After creating the app and saving the app's ID and private key, you'll need to install it. On the lefthand side of the app's detail page, click "Install App" and select the organization (or your own account) you'd like to use. This will prompt you to accept the new application. Verify that it looks correct, and click "Install".
Installing an application generates an installation ID, which will be the final part of the URL on
the page you're sent to (i.e. https://github.com/settings/installations/1234 where 1234 is your)
installation ID. Installation IDs represent an instance of an application being installed in an
organization or user account.
While saving and using the installation ID is optional, it saves an extra API call every time
checkbridge is run.
The final step is to make the application ID, private key, and optionally the installation ID,
available to checkbridge. Do not commit the private key to your repository.
You should verify your credentials are correct by running checkbridge check-auth:
For example:
# These could be configured in your CI environment
export CHECKBRIDGE_APPLICATION_ID="456"
export CHECKBRIDGE_PRIVATE_KEY="/tmp/private_key.pm"
export CHECKBRIDGE_INSTALLATION_ID="1234" # application 456 installed in "myorg"
checkbridge check-auth --github-repo=myorg/myrepoOr specifying as command-line flags:
# --installation-id left off, will look it up dynamically
checkbridge check-auth \
--github-repo=myorg/myrepo \
--application-id=456 \
--private-key=/tmp/private_key.pemIf it returns an error, validate you've passed the correct configuration values. If it returns
success, you're ready to use checkbridge.
Currently, checkbridge has builtin support for golint and mypy. In addition, it has a generic
regex command, which allows you to specify a regular expression. For example, running the
following would create an annotation on example.go line 1, with the message this is a message.
echo "example.go:1: this is a message" | checkbridge regex \
--regex "(.*):(.*): (.*)" \
--name "my custom linter" \
--path-pos 1 \
--line-pos 2 \
--message-pos 3Note that the positions start at 1, as per convention, where the 0th element is the whole string match.
Run checkbridge regex --help to see all the available configuration options.
This section is intended for developers of this tool.
You will need to have the Go toolchain installed. If it's correctly installed,
you'll have the go binary available on your path. If you don't have go
available, install it via your system's package manager. For example, on macOS:
brew install go
This project is currently developed and tested using Go version 1.13, which is the latest public release. You'll need at least Go 1.11 to build as this project uses the new module system.
go test ./...Linting is enforced in CI via GitHub actions on this repository. If you get a lint failure, you probably need to configure your editor for Go support.
Your editor should already be running gofmt (or goimports) for you on save.
If not, you can run it manually:
gofmt -w .We also run golint to find common code issues. Run it with:
golint ./...If you don't have golint available, install it with:
go get -u golang.org/x/lint/golint