{"id":18763777,"url":"https://github.com/roverdotcom/checkbridge","last_synced_at":"2025-04-13T04:32:51.513Z","repository":{"id":52642750,"uuid":"239599010","full_name":"roverdotcom/checkbridge","owner":"roverdotcom","description":"Create GitHub Checks from arbitrary commands","archived":false,"fork":false,"pushed_at":"2021-04-22T15:33:33.000Z","size":180,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-03-26T21:46:12.588Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roverdotcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-10T19:49:03.000Z","updated_at":"2023-05-04T08:29:02.000Z","dependencies_parsed_at":"2022-08-21T10:40:19.104Z","dependency_job_id":null,"html_url":"https://github.com/roverdotcom/checkbridge","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roverdotcom%2Fcheckbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roverdotcom%2Fcheckbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roverdotcom%2Fcheckbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roverdotcom%2Fcheckbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roverdotcom","download_url":"https://codeload.github.com/roverdotcom/checkbridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248664212,"owners_count":21141915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T18:27:25.989Z","updated_at":"2025-04-13T04:32:51.254Z","avatar_url":"https://github.com/roverdotcom.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Checkbridge ![build status](https://github.com/roverdotcom/checkbridge/workflows/Test/badge.svg)\n\n**Project Status**: Alpha\n\nCommand-line utility to allow creating arbitrary [GitHub\nchecks](https://developer.github.com/v3/checks/) from other command-line\nutilities.\n\n![Screenshot](/.github/screenshots/go-lint-check-screenshot.png)\n\n## About\n\nIf you're using GitHub actions, have a look at [Lint Action] instead, which\nis both more full-featured and doesn't require you to create a GitHub app and\ninstall it.\n\nThe use case this was designed for is when you have an existing CI system that\nis **not** running via GitHub actions, and you'd like to use [GitHub checks].\n\nGitHub checks allow you to post line-level annotations to files in Pull Requests\nand commits, which is especially useful for linters and other code analysis\ntools that you may want to run before code is merged.\n\nIn order to use GitHub checks on commits and pull requests, you need to have\na GitHub app provisioned and installed in your organization with `write` scope\non the `checks` [permission].\n\n[github checks]: https://developer.github.com/v3/checks/\n[lint action]: https://github.com/samuelmeuli/lint-action\n[permission]: https://developer.github.com/v3/apps/permissions/#permission-on-checks\n\n## Installing\n\nPrecompiled binaries are available for all releases [on GitHub]. Because they are\nstatic binaries, you can simply download them and run them. For example, on Linux:\n\n```bash\ncurl -L https://github.com/roverdotcom/checkbridge/releases/download/v0.0.4/checkbridge-v0.0.4.linux-amd64.tar.gz \\\n    | tar zxf - -C /usr/local/bin\n```\n\nYou can also install from source if you have Go 1.11+ installed:\n\n```bash\ngo get github.com/roverdotcom/checkbridge\n```\n\nThis will install the tip of `master` (not recommended for production usage) into `$GOPATH/bin/`\n\n[on github]: https://github.com/roverdotcom/checkbridge/releases\n\n## Usage\n\n`checkbridge` requires GitHub credentials to report checks. Read through the\n[configuration] and [authentication] sections to get started. Once configured,\nyou can create checks by piping your desired tool into a `checkbridge`\nsubcommand. For example:\n\n```bash\ngolint ./... | checkbridge golint\n```\n\n[configuration]: #configuration\n[authentication]: #authentication\n\n## Configuration\n\nMost configuration options can be passed as either command-line arguments or\nenvironment variables. All flags have shorthand values, run `checkbridge --help`\nto see them:\n\n```\nFlags:\n  -o, --annotate-only         only leave annotations, never mark check as failed\n  -a, --application-id int    GitHub application ID (numeric)\n  -c, --commit-sha string     commit SHA to report status checks for\n  -d, --details-url string    details URL to send for check\n  -z, --exit-zero             exit zero even when tool reports issues\n  -f, --file string           read input from named file instead of stdin\n  -r, --github-repo string    GitHub repository (e.g. 'roverdotcom/checkbridge')\n  -h, --help                  help for checkbridge\n  -i, --installation-id int   GitHub installation ID (numeric)\n  -m, --mark-in-progress      mark check as in progress before parsing\n  -p, --private-key string    GitHub application private key path or value\n  -v, --verbose               verbose output\n```\n\n### Required flags\n\n| Flag               | Environment Variable         |\n| ------------------ | ---------------------------- |\n| `--application-id` | `CHECKBRIDGE_APPLICATION_ID` |\n| `--private-key`    | `CHECKBRIDGE_PRIVATE_KEY`    |\n\n#### Optional flags\n\nThe following flags can be configured, but are not required by default.\n\n| Flag                | Environment Variable          |\n| ------------------- | ----------------------------- |\n| `--installation-id` | `CHECKBRIDGE_INSTALLATION_ID` |\n| `--commit-sha`      | `CHECKBRIDGE_COMMIT_SHA`      |\n| `--github-repo`     | `CHECKBRIDGE_GITHUB_REPO`     |\n| `--github-token`    | `CHECKBRIDGE_GITHUB_TOKEN`    |\n\n### Defaults\n\n`--installation-id` will be looked up dynamically if not provided, by doing a `GET` to\n`/repos/:owner/:repo/installation` with the provided private key / application ID.\n\n`--commit-sha` will be read from `$GITHUB_SHA`, `$BUILDKITE_COMMIT`, or `$(git rev-parse HEAD)`\n\n`--github-repo` will be read from `$GITHUB_REPOSITORY` or `$BUILDKITE_REPO` if present\n\n`--github-token` will be read from `$GITHUB_TOKEN` if present (i.e. when run via GitHub actions)\n\n## Authentication\n\nUsing the GitHub checks API requires a GitHub app to be created and installed, with `checks`\npermission on the repo you're running against.\n\nGitHub application tokens, unlike GitHub user tokens, are short-lived (1 hour) and thus must\nusually be fetched for each run. When running via GitHub actions, you automatically have a\ntoken (available under `secrets.github_token`) available for the \"GitHub actions\" application\nfor your use. You can see an example of this in this repo's [lint.yml](./.github/workflows/lint.yml)\nworkflow.\n\nIf you're running via GitHub actions, simply provide the token (as `--github-token`,\n`$GITHUB_TOKEN`, or `$CHECKBRIDGE_GITHUB_TOKEN`) and you're good to go. If you're _not_ running via\nGitHub actions (for example, you're using [BuildKite](https://buildkite.com/)), read on.\n\n### Creating a GitHub app\n\nFirst, you'll need to [create a GitHub app].\n\nYou'll start with [registering your app]. Give it a descriptive name and a homepage (these are\nrequired fields). We won't be doing any OAuth (user authorization) so you can leave most of the\nrest blank. Under the \"Permissions\" section, you'll need to select \"Read \u0026 write\" access\nto the \"Checks\" permission.\n\nIf you're going to use your application on an organization (as opposed to just your own repos),\nselect \"Any account\" under \"Where can this GitHub App be installed?\"\n\nOnce created, you'll need to grab two pieces of information:\n\n1. The application ID, which will be at the very top of the page (\"App ID\")\n2. A private key, at the very bottom of the page. You can generate a new one when your\n   app is first created. This will prompt you to download a `.pem` file containing the private key.\n\n[create a github app]: https://developer.github.com/apps/building-github-apps/creating-a-github-app/\n[registering your app]: https://github.com/settings/apps/new\n\nAfter creating the app and saving the app's ID and private key, you'll need to install it. On the\nlefthand side of the app's detail page, click \"Install App\" and select the organization (or your\nown account) you'd like to use. This will prompt you to accept the new application. Verify that\nit looks correct, and click \"Install\".\n\nInstalling an application generates an installation ID, which will be the final part of the URL on\nthe page you're sent to (i.e. `https://github.com/settings/installations/1234` where `1234` is your)\ninstallation ID. Installation IDs represent an instance of an application being installed in an\norganization or user account.\n\nWhile saving and using the installation ID is optional, it saves an extra API call every time\n`checkbridge` is run.\n\nThe final step is to make the application ID, private key, and optionally the installation ID,\navailable to `checkbridge`. Do _not_ commit the private key to your repository.\n\nYou should verify your credentials are correct by running `checkbridge check-auth`:\nFor example:\n\n```bash\n# These could be configured in your CI environment\nexport CHECKBRIDGE_APPLICATION_ID=\"456\"\nexport CHECKBRIDGE_PRIVATE_KEY=\"/tmp/private_key.pm\"\nexport CHECKBRIDGE_INSTALLATION_ID=\"1234\"  # application 456 installed in \"myorg\"\n\ncheckbridge check-auth --github-repo=myorg/myrepo\n```\n\nOr specifying as command-line flags:\n\n```bash\n# --installation-id left off, will look it up dynamically\ncheckbridge check-auth \\\n  --github-repo=myorg/myrepo \\\n  --application-id=456 \\\n  --private-key=/tmp/private_key.pem\n```\n\nIf it returns an error, validate you've passed the correct configuration values. If it returns\nsuccess, you're ready to use `checkbridge`.\n\n## Available parsers\n\nCurrently, `checkbridge` has builtin support for [golint] and [mypy]. In addition, it has a generic\n`regex` command, which allows you to specify a regular expression. For example, running the\nfollowing would create an annotation on `example.go` line `1`, with the message `this is a message`.\n\n```bash\necho \"example.go:1: this is a message\" | checkbridge regex \\\n  --regex \"(.*):(.*): (.*)\" \\\n  --name \"my custom linter\" \\\n  --path-pos 1 \\\n  --line-pos 2 \\\n  --message-pos 3\n```\n\nNote that the positions start at 1, as per convention, where the 0th element is the whole string\nmatch.\n\nRun `checkbridge regex --help` to see all the available configuration options.\n\n[golint]: https://github.com/golang/lint\n[mypy]: https://mypy.readthedocs.io/\n\n## Development\n\nThis section is intended for developers of this tool.\n\nYou will need to have the [Go] toolchain installed. If it's correctly installed,\nyou'll have the `go` binary available on your path. If you don't have `go`\navailable, install it via your system's package manager. For example, on macOS:\n\n```\nbrew install go\n```\n\nThis project is currently developed and tested using Go version 1.13, which is\nthe latest public release. You'll need at least Go 1.11 to build as this project\nuses the [new module system].\n\n[go]: https://golang.org/\n[new module system]: https://blog.golang.org/using-go-modules\n\n### Running tests\n\n```sh\ngo test ./...\n```\n\n### Linting\n\nLinting is enforced in CI via GitHub actions on this repository. If you get a\nlint failure, you probably need to configure your editor for Go support.\n\nYour editor should already be running `gofmt` (or `goimports`) for you on save.\nIf not, you can run it manually:\n\n```sh\ngofmt -w .\n```\n\nWe also run `golint` to find common code issues. Run it with:\n\n```sh\ngolint ./...\n```\n\nIf you don't have `golint` available, install it with:\n\n```sh\ngo get -u golang.org/x/lint/golint\n```\n\n### Related\n\n- [Lint Action](https://github.com/samuelmeuli/lint-action)\n- [Probot](https://probot.github.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froverdotcom%2Fcheckbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froverdotcom%2Fcheckbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froverdotcom%2Fcheckbridge/lists"}