|
| 1 | +--- |
| 2 | +kind: change |
| 3 | +title: Ensure your app is ready for Protected Branches |
| 4 | +created_at: 2015-09-03 |
| 5 | +author_name: aroben |
| 6 | +--- |
| 7 | + |
| 8 | +We’ve begun to [roll out Protected Branches][blog] across GitHub. When you |
| 9 | +protect a branch in one of your repositories, you will be prevented from |
| 10 | +force pushing to that branch or deleting it. You can also configure required |
| 11 | +status checks for your protected branch. When configured, changing a branch to |
| 12 | +point at a new commit will fail unless the that commit (or another commit with |
| 13 | +the same [Git tree][tree]) has a [Status][statuses] in the `success` state for |
| 14 | +each required status check. |
| 15 | + |
| 16 | +These restrictions apply to branch manipulations performed via the GitHub API |
| 17 | +as well. So when you protect a branch, you will no longer be able to [delete |
| 18 | +the branch][delete] via the API or [update it][update] to point at a |
| 19 | +non-ancestor commit, even with `"force": true`. And if your branch has required |
| 20 | +status checks, you won’t be able to [update it][update] or [merge pull |
| 21 | +requests][merge] into that branch until `success` Statuses have been posted to |
| 22 | +the target commit for all required status checks. |
| 23 | + |
| 24 | +These restrictions are all represented by 422 errors: |
| 25 | + |
| 26 | +<pre class="terminal"> |
| 27 | +$ curl -i -H 'Authorization: token TOKEN' \ |
| 28 | + -X DELETE https://api.github.com/repos/octocat/hubot/git/refs/heads/master |
| 29 | +HTTP/1.1 422 Unprocessable Entity |
| 30 | + |
| 31 | +{ |
| 32 | + "message": "Cannot delete a protected branch", |
| 33 | + "documentation_url": "https://help.github.com/articles/about-protected-branches" |
| 34 | +} |
| 35 | +</pre> |
| 36 | + |
| 37 | +Protected branches and required status checks are a great way to ensure your |
| 38 | +project’s conventions are followed. For example, you could write a Status |
| 39 | +integration that only posts a `success` Status when the pull request’s author |
| 40 | +has signed your project’s Contributor License Agreement. Or you could write one |
| 41 | +that only posts a `success` Status when three or more members of your |
| 42 | +`@initech/senior-engineers` team have left a comment saying they’ve reviewed |
| 43 | +the changes. If you configure these integrations as required status checks, you |
| 44 | +can be sure that these conditions have been satisfied before a pull request is |
| 45 | +merged. See our [Status API guide][guide] to learn how to create integrations |
| 46 | +like these. |
| 47 | + |
| 48 | +If you have any questions, please [let us know][contact]. |
| 49 | + |
| 50 | +[blog]: https://github.com/blog/2051-protected-branches-and-required-status-checks |
| 51 | +[statuses]: /v3/repos/statuses/ |
| 52 | +[tree]: http://git-scm.com/book/en/v2/Git-Internals-Git-Objects#Tree-Objects |
| 53 | +[delete]: /v3/git/refs/#delete-a-reference |
| 54 | +[update]: /v3/git/refs/#update-a-reference |
| 55 | +[merge]: /v3/pulls/#merge-a-pull-request-merge-button |
| 56 | +[contact]: https://github.com/contact?form[subject]=Protected+Branches+in+API+responses |
| 57 | +[guide]: /guides/building-a-ci-server/ |
0 commit comments