{"id":19722879,"url":"https://github.com/cloudposse/github-status-updater","last_synced_at":"2025-04-05T07:07:33.168Z","repository":{"id":29078394,"uuid":"119480644","full_name":"cloudposse/github-status-updater","owner":"cloudposse","description":"Command line utility for updating GitHub commit statuses and enabling required status checks for pull requests","archived":false,"fork":false,"pushed_at":"2024-12-11T23:35:56.000Z","size":2081,"stargazers_count":108,"open_issues_count":6,"forks_count":27,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-03-29T06:08:59.169Z","etag":null,"topics":["branch-protection","ci","ci-environment","cicd","codefresh","docker-container","github","github-api","github-status","status-checks","travis"],"latest_commit_sha":null,"homepage":"https://cloudposse.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudposse.png","metadata":{"funding":{"github":"cloudposse"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-30T04:07:15.000Z","updated_at":"2025-02-01T18:55:30.000Z","dependencies_parsed_at":"2023-12-15T09:45:56.393Z","dependency_job_id":"d84b294b-6b62-40fd-b70b-cc0af58145ec","html_url":"https://github.com/cloudposse/github-status-updater","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudposse%2Fgithub-status-updater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudposse%2Fgithub-status-updater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudposse%2Fgithub-status-updater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudposse%2Fgithub-status-updater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudposse","download_url":"https://codeload.github.com/cloudposse/github-status-updater/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299832,"owners_count":20916190,"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":["branch-protection","ci","ci-environment","cicd","codefresh","docker-container","github","github-api","github-status","status-checks","travis"],"created_at":"2024-11-11T23:18:52.649Z","updated_at":"2025-04-05T07:07:33.149Z","avatar_url":"https://github.com/cloudposse.png","language":"Go","readme":"# github-status-updater ![docker](https://github.com/cloudposse/github-status-updater/workflows/docker/badge.svg?branch=master) ![go](https://github.com/cloudposse/github-status-updater/workflows/go/badge.svg?branch=master)\n\n\nCommand line utility for updating GitHub commit statuses and enabling required status checks for pull requests.\n\n* https://developer.github.com/v3/repos/statuses\n* https://help.github.com/articles/enabling-required-status-checks\n\nUseful for CI environments to set more specific commit and build statuses, including setting the target URL\n(the URL of the page representing the build status, or the URL of the deployed application).\n\n\n![GitHub Status Checks](images/codefresh-deployment-status-success.png)\n###\n\n\n__NOTE__: Create a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) with `repo:status` and `public_repo` scopes\n\n__NOTE__: The icons in the image above are the avatars of the users for which the GitHub access tokens are issued\n\n\n\n## Usage\n\n__NOTE__: The module accepts parameters as command-line arguments or as ENV variables\n(or any combination of command-line arguments and ENV vars).\nCommand-line arguments take precedence over ENV vars.\n\n\n| Command-line argument |  ENV var            |  Description                                                                   |\n|:----------------------|:--------------------|:-------------------------------------------------------------------------------|\n| action                | GITHUB_ACTION       | Action to perform: `update_state` or `update_branch_protection`                |\n| token                 | GITHUB_TOKEN        | Github access token                                                            |\n| owner                 | GITHUB_OWNER        | Github repository owner                                                        |\n| repo                  | GITHUB_REPO         | Github repository name                                                         |\n| ref                   | GITHUB_REF          | Commit SHA, branch name or tag                                                 |\n| state                 | GITHUB_STATE        | Commit state. Possible values are `pending`, `success`, `error` or `failure`   |\n| context               | GITHUB_CONTEXT      | Status label. Could be the name of a CI environment (_e.g._ `my-ci`)           |\n| description           | GITHUB_DESCRIPTION  | Short high level summary of the status                                         |\n| url                   | GITHUB_TARGET_URL   | URL of the page representing the status                                        |\n\n\n\n### build the Go program locally\n\n```sh\ngo get\n\nCGO_ENABLED=0 go build -v -o \"./dist/bin/github-status-updater\" *.go\n```\n\n\n### run locally with ENV vars\n[run_locally_with_env_vars.sh](examples/run_locally_with_env_vars.sh)\n\n```sh\nexport GITHUB_ACTION=update_state\nexport GITHUB_TOKEN=XXXXXXXXXXXXXXXX\nexport GITHUB_OWNER=cloudposse\nexport GITHUB_REPO=github-status-updater\nexport GITHUB_REF=XXXXXXXXXXXXXXXX\nexport GITHUB_STATE=success\nexport GITHUB_CONTEXT=\"my-ci\"\nexport GITHUB_DESCRIPTION=\"Commit status with target URL\"\nexport GITHUB_TARGET_URL=\"https://my-ci.com/build/1\"\n\n./dist/bin/github-status-updater\n```\n\n\nAfter 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)\n\n![GitHub Commit Status](images/github-commit-status.png)\n###\n\n\n### run locally with command-line arguments\n[run_locally_with_command_line_args.sh](examples/run_locally_with_command_line_args.sh)\n\n```sh\n./dist/bin/github-status-updater \\\n        -action update_state \\\n        -token XXXXXXXXXXXXXXXX \\\n        -owner cloudposse \\\n        -repo github-status-updater \\\n        -ref XXXXXXXXXXXXXXX \\\n        -state success \\\n        -context \"my-ci\" \\\n        -description \"Commit status with target URL\" \\\n        -url \"https://my-ci.com/build/1\"\n```\n\n\n\n### build the Docker image\n__NOTE__: it will download all `Go` dependencies and then build the program inside the container (see [`Dockerfile`](Dockerfile))\n\n\n```sh\ndocker build --tag github-status-updater  --no-cache=true .\n```\n\n\n\n### run in a Docker container with ENV vars\n[run_docker_with_env_vars.sh](examples/run_docker_with_env_vars.sh)\n\n```sh\ndocker run -i --rm \\\n        -e GITHUB_ACTION=update_state \\\n        -e GITHUB_TOKEN=XXXXXXXXXXXXXXXX \\\n        -e GITHUB_OWNER=cloudposse \\\n        -e GITHUB_REPO=github-status-updater \\\n        -e GITHUB_REF=XXXXXXXXXXXXXXXX \\\n        -e GITHUB_STATE=success \\\n        -e GITHUB_CONTEXT=\"my-ci\" \\\n        -e GITHUB_DESCRIPTION=\"Commit status with target URL\" \\\n        -e GITHUB_TARGET_URL=\"https://my-ci.com/build/1\" \\\n        github-status-updater\n```\n\n\n\n### run in a Docker container with local ENV vars propagated into the container's environment\n[run_docker_with_local_env_vars.sh](examples/run_docker_with_local_env_vars.sh)\n\n```sh\nexport GITHUB_ACTION=update_state\nexport GITHUB_TOKEN=XXXXXXXXXXXXXXXX\nexport GITHUB_OWNER=cloudposse\nexport GITHUB_REPO=github-status-updater\nexport GITHUB_REF=XXXXXXXXXXXXXXXX\nexport GITHUB_STATE=success\nexport GITHUB_CONTEXT=\"my-ci\"\nexport GITHUB_DESCRIPTION=\"Commit status with target URL\"\nexport GITHUB_TARGET_URL=\"https://my-ci.com/build/1\"\n\ndocker run -i --rm \\\n        -e GITHUB_ACTION \\\n        -e GITHUB_TOKEN \\\n        -e GITHUB_OWNER \\\n        -e GITHUB_REPO \\\n        -e GITHUB_REF \\\n        -e GITHUB_STATE \\\n        -e GITHUB_CONTEXT \\\n        -e GITHUB_DESCRIPTION \\\n        -e GITHUB_TARGET_URL \\\n        github-status-updater\n```\n\n\n\n### run in a Docker container with ENV vars declared in a file\n[run_docker_with_env_vars_file.sh](examples/run_docker_with_env_vars_file.sh)\n\n```sh\ndocker run -i --rm --env-file ./example.env github-status-updater\n```\n\n\n###\n###\n## GitHub Required Status Checks\n\n\nThe module can be used to update required status checks for Pull Requests.\n\nThis is useful for CI environments to set build statuses with URLs to the build pages.\n\nFirst, 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.\n\n* https://help.github.com/articles/enabling-required-status-checks\n\n\n![GitHub Branch Protection Settings](images/github-branch-protection-settings.png)\n\n\nThen, to add `my-ci` as a status check for branch `test` of the `github-status-updater` repo, execute the `update_branch_protection` action locally\n\n```ssh\n./dist/bin/github-status-updater \\\n        -action update_branch_protection \\\n        -token XXXXXXXXXXXXXXXXXXXXXX \\\n        -owner cloudposse \\\n        -repo github-status-updater \\\n        -ref test \\\n        -context my-ci\n```\n\n\nor in a Docker container\n\n```ssh\ndocker run -i --rm \\\n        -e GITHUB_ACTION=update_branch_protection \\\n        -e GITHUB_TOKEN=XXXXXXXXXXXXXXXX \\\n        -e GITHUB_OWNER=cloudposse \\\n        -e GITHUB_REPO=github-status-updater \\\n        -e GITHUB_REF=test \\\n        -e GITHUB_CONTEXT=\"my-ci\" \\\n        github-status-updater\n```\n\n\nAfter the command executes, status check `my-ci` will be enabled for the branch as shown in the image below\n\n###\n![GitHub Branch Protection Settings](images/github-branch-protection-update.png)\n###\n\n\nWhen 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`\nby executing the following command to update the status of the last commit (`ref XXXXXXXXXXXXXXX`)\n\n```sh\n./dist/bin/github-status-updater \\\n        -action update_state \\\n        -token XXXXXXXXXXXXXXXX \\\n        -owner cloudposse \\\n        -repo github-status-updater \\\n        -ref XXXXXXXXXXXXXXX \\\n        -state pending \\\n        -context \"my-ci\" \\\n        -description \"still building...\" \\\n        -url \"https://my-ci.com/build/1\"\n```\n\n###\n![GitHub Status Check Pending](images/github-status-check-pending.png)\n###\n\n\nIn case of any build errors, `my-ci` updates the build status to `error` with the error message in the `description` parameter\n\n```sh\n./dist/bin/github-status-updater \\\n        -action update_state \\\n        -token XXXXXXXXXXXXXXXX \\\n        -owner cloudposse \\\n        -repo github-status-updater \\\n        -ref XXXXXXXXXXXXXXX \\\n        -state error \\\n        -context \"my-ci\" \\\n        -description \"build error\" \\\n        -url \"https://my-ci.com/build/1\"\n```\n\n\n###\n![GitHub Status Check Error](images/github-status-check-error.png)\n###\n\n\nWhen the build succeeds, `my-ci` updates the build status to `success`\n\n```sh\n./dist/bin/github-status-updater \\\n        -action update_state \\\n        -token XXXXXXXXXXXXXXXX \\\n        -owner cloudposse \\\n        -repo github-status-updater \\\n        -ref XXXXXXXXXXXXXXX \\\n        -state success \\\n        -context \"my-ci\" \\\n        -description \"build completed\" \\\n        -url \"https://my-ci.com/build/1\"\n```\n\n###\n![GitHub Status Check Success](images/github-status-check-success.png)\n###\n\n\n###\n## Integrating with [CodeFresh](https://codefresh.io) CI/CD Pipelines\n\n`github-status-updater` can be easily integrated into CI/CD pipelines, especially those that use containers for build steps.\n\n[codefresh.yml](examples/codefresh.yml) shows a complete example of a [CodeFresh](https://docs.codefresh.io/docs/introduction-to-codefresh-pipelines) pipeline which performs the following steps:\n\n* Builds a Docker image for the application\n* Builds a [Helm](https://github.com/kubernetes/helm) [chart](https://github.com/kubernetes/charts)\n* Pushes the Docker images (for commits, branches and tags) to CodeFresh repository\n* Executes `update_branch_protection` action on `github-status-updater` [Docker container](https://hub.docker.com/r/cloudposse/github-status-updater) to add `Staging Environment` as a required status check\n* Executes `update_state` action on `github-status-updater` [Docker container](https://hub.docker.com/r/cloudposse/github-status-updater) to update `Staging Environment` deployment status to `pending`\n* Deploys the Helm chart to a [Kubernetes](https://kubernetes.io) cluster\n* Executes `update_state` action on `github-status-updater` [Docker container](https://hub.docker.com/r/cloudposse/github-status-updater) to update `Staging Environment` deployment status to `success`\n\n\n![GitHub Status Checks](images/codefresh-deployment-status-pending.png)\n###\n\n![GitHub Status Checks](images/codefresh-deployment-status-success.png)\n###\n\n\n\n## References\n* https://github.com/google/go-github\n* https://godoc.org/github.com/google/go-github/github\n* https://help.github.com/articles/enabling-required-status-checks\n* https://developer.github.com/v3/repos/statuses\n* https://developer.github.com/v3/guides/building-a-ci-server\n* https://docs.docker.com/develop/develop-images/dockerfile_best-practices\n* https://docs.docker.com/engine/reference/commandline/build\n* https://docs.docker.com/engine/reference/commandline/run\n* https://codefresh.io\n* https://docs.codefresh.io/docs/introduction-to-codefresh-pipelines\n* https://github.com/kubernetes/helm\n* https://github.com/kubernetes/charts\n\n\n\n## Help\n\n**Got a question?**\n\nFile a GitHub [issue](https://github.com/cloudposse/github-status-updater/issues), send us an [email](mailto:hello@cloudposse.com) or reach out to us on [Gitter](https://gitter.im/cloudposse/).\n\n\n## Contributing\n\n### Bug Reports \u0026 Feature Requests\n\nPlease use the [issue tracker](https://github.com/cloudposse/github-status-updater/issues) to report any bugs or file feature requests.\n\n### Developing\n\nIf 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](mailto:hello@cloudposse.com).\n\nIn general, PRs are welcome. We follow the typical \"fork-and-pull\" Git workflow.\n\n 1. **Fork** the repo on GitHub\n 2. **Clone** the project to your own machine\n 3. **Commit** changes to your own branch\n 4. **Push** your work back up to your fork\n 5. Submit a **Pull request** so that we can review your changes\n\n**NOTE:** Be sure to merge the latest from \"upstream\" before making a pull request!\n\n\n## License\n\n[APACHE 2.0](LICENSE) © 2018 [Cloud Posse, LLC](https://cloudposse.com)\n\nSee [LICENSE](LICENSE) for full details.\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n\n## About\n\n`github-status-updater` is maintained and funded by [Cloud Posse, LLC][website].\n\n![Cloud Posse](https://cloudposse.com/logo-300x69.png)\n\n\nLike it? Please let us know at \u003chello@cloudposse.com\u003e\n\nWe love [Open Source Software](https://github.com/cloudposse/)!\n\nSee [our other projects][community]\nor [hire us][hire] to help build your next cloud platform.\n\n  [website]: https://cloudposse.com/\n  [community]: https://github.com/cloudposse/\n  [hire]: https://cloudposse.com/contact/\n\n\n### Contributors\n\n| [![Erik Osterman][erik_img]][erik_web]\u003cbr/\u003e[Erik Osterman][erik_web] | [![Andriy Knysh][andriy_img]][andriy_web]\u003cbr/\u003e[Andriy Knysh][andriy_web] |\n|-------------------------------------------------------|------------------------------------------------------------------|\n\n  [erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144\n  [erik_web]: https://github.com/osterman/\n  [andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4\u0026u=ed9ce1c9151d552d985bdf5546772e14ef7ab617\u0026s=144\n  [andriy_web]: https://github.com/aknysh/\n","funding_links":["https://github.com/sponsors/cloudposse"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudposse%2Fgithub-status-updater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudposse%2Fgithub-status-updater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudposse%2Fgithub-status-updater/lists"}