Skip to content

Commit 12eb2f5

Browse files
mchammer01mchammer01
authored
Merge branch 'main' into secret-scanning-ga
2 parents 39282ae + 7e7268e commit 12eb2f5

1 file changed

Lines changed: 111 additions & 60 deletions

File tree

‎content/admin/policies/creating-a-pre-receive-hook-script.md‎

Lines changed: 111 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Creating a pre-receive hook script
33
intro: Use pre-receive hook scripts to create requirements for accepting or rejecting a push based on the contents.
4+
miniTocMaxHeadingLevel: 4
45
redirect_from:
56
- /enterprise/admin/developer-workflow/creating-a-pre-receive-hook-script
67
- /enterprise/admin/policies/creating-a-pre-receive-hook-script
@@ -13,59 +14,109 @@ topics:
1314
You can see examples of pre-receive hooks for {% data variables.product.prodname_ghe_server %} in the [`github/platform-samples` repository](https://github.com/github/platform-samples/tree/master/pre-receive-hooks).
1415

1516
### Writing a pre-receive hook script
16-
A pre-receive hook script executes in a pre-receive hook environment on the {% data variables.product.prodname_ghe_server %} appliance. When you create a pre-receive hook script, consider the available input, output, exit-status and environment variables.
17+
A pre-receive hook script executes in a pre-receive hook environment on {% data variables.product.product_location %}. When you create a pre-receive hook script, consider the available input, output, exit status, and environment variables.
1718

18-
#### Input (stdin)
19-
After a push occurs and before any refs are updated on the remote repository, the `git-receive-pack` process invokes the pre-receive hook script with the standard input of one line per ref to be updated:
19+
#### Input (`stdin`)
20+
After a push occurs and before any refs are updated for the remote repository, the `git-receive-pack` process on {% data variables.product.product_location %} invokes the pre-receive hook script. Standard input for the script, `stdin`, is a string containing a line for each ref to update. Each line contains the old object name for the ref, the new object name for the ref, and the full name of the ref.
2021

21-
`<old-value> SP <new-value> SP <ref-name> LF`
22+
```
23+
<old-value> SP <new-value> SP <ref-name> LF
24+
```
2225

23-
This string represents these arguments:
26+
This string represents the following arguments.
2427

2528
| Argument | Description |
2629
| :------------- | :------------- |
27-
| `<old-value>` | Old object name stored in the `ref`.<br> When you *create* a new `ref`, this equals 40 zeroes. |
28-
| `<new-value>` | New object name to be stored in the `ref`.<br> When you *delete* a `ref`, this equals 40 zeroes. |
29-
| `<ref-name>` | The full name of the `ref`. |
30+
| `<old-value>` | Old object name stored in the ref.<br> When you create a new ref, the value is 40 zeroes. |
31+
| `<new-value>` | New object name to be stored in the ref.<br> When you delete a ref, the value is 40 zeroes. |
32+
| `<ref-name>` | The full name of the ref. |
3033

31-
For more information on `git-receive-pack` see "[git-receive-pack](https://git-scm.com/docs/git-receive-pack)" in the Git documentation.
32-
For more information about `refs` see "[Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References)" in *Pro Git*.
34+
For more information about `git-receive-pack`, see "[git-receive-pack](https://git-scm.com/docs/git-receive-pack)" in the Git documentation. For more information about refs, see "[Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References)" in *Pro Git*.
3335

34-
#### Output (stdout)
36+
#### Output (`stdout`)
3537

36-
The script output (`stdout`) is passed back to the client, so any `echo` statements are visible to the user on the command line or in the user interface.
38+
The standard output for the script, `stdout`, is passed back to the client. Any `echo` statements will be visible to the user on the command line or in the user interface.
3739

38-
#### Exit-status
40+
#### Exit status
3941

40-
The `exit-status` of a pre-receive script determines if the push will be accepted.
42+
The exit status of a pre-receive script determines if the push will be accepted.
4143

42-
| Exit-status Value | Action |
43-
| :-------------: | :-------------: |
44-
| 0 | The push will be accepted. |
44+
| Exit-status value | Action |
45+
| :- | :- |
46+
| 0 | The push will be accepted. |
4547
| non-zero | The push will be rejected. |
4648

4749
#### Environment variables
48-
Outside of the values that are provided to `stdin`, there are additional variables that are available to a pre-receive hook script running on {% data variables.product.prodname_ghe_server %}.
4950

50-
| Variable | Description |
51-
| :------------- | :------------- |
52-
| $GITHUB_USER_LOGIN | The user id who created the `ref`. |
53-
| $GIT_DIR | The path of the remote repository on the appliance. |
54-
| $GITHUB_USER_IP | The IP Address of the user performing the push. |
55-
| $GITHUB_REPO_NAME | The name in `owner`/`repo` format of the repository being updated. |
56-
| $GITHUB_PULL_REQUEST_AUTHOR_LOGIN | The user ID for the author of a pull request opened on your instance. |
57-
| $GITHUB_REPO_PUBLIC | A boolean value that when `true` represents a public repository, and when `false` represents a private repository. |
58-
| $GITHUB_PUBLIC_KEY_FINGERPRINT | The user's public key fingerprint. |
59-
| $GITHUB_PULL_REQUEST_HEAD | A string in the format: `user:branch` for the HEAD of the PR.<br> Example: `octocat:fix-bug` |
60-
| $GITHUB_PULL_REQUEST_BASE | A string in the format: `user:branch` for the BASE of the PR.<br> Example: `octocat:main` |
61-
| $GITHUB_VIA | Method used to create the ref.<br> **Possible values:**<br> - `auto-merge deployment api` <br> - `blob edit` <br> - `branch merge api` <br> - `branches page delete button` <br> - `git refs create api` <br> - `git refs delete api` <br> - `git refs update api` <br> - `merge api` <br> - `pull request branch delete button` <br> - `pull request branch undo button` <br> - `pull request merge api` <br> - `pull request merge button` <br> - `pull request revert button` <br> - `releases delete button` <br> - `stafftools branch restore` <br> - `slumlord (#{sha})` |
62-
| $GIT_PUSH_OPTION_COUNT | The number of push options that were sent by the client. For more information about push options, see "[git-push](https://git-scm.com/docs/git-push#git-push---push-optionltoptiongt)" in the Git documentation. |
63-
| $GIT_PUSH_OPTION_N | Where <em>N</em> is an integer starting at 0, this variable contains the push option string that was sent by the client. The first option that was sent is stored in GIT_PUSH_OPTION_0, the second option that was sent is stored in GIT_PUSH_OPTION_1, and so on. For more information about push options, see "[git-push](https://git-scm.com/docs/git-push#git-push---push-optionltoptiongt)" in the Git documentation. |{% if currentVersion ver_gt "enterprise-server@2.21" %}
64-
| $GIT_USER_AGENT | The user-agent string sent by the client that pushed the changes. |{% endif %}
51+
In addition to the standard input for your pre-receive hook script, `stdin`, {% data variables.product.prodname_ghe_server %} makes the following variables available in the Bash environment for your script's execution. For more information about `stdin` for your pre-receive hook script, see "[Input (`stdin`)](#input-stdin)."
52+
53+
Different environment variables are available to your pre-receive hook script depending on what triggers the script to run.
54+
55+
- [Always available](#always-available)
56+
- [Available for pushes from the web interface or API](#available-for-pushes-from-the-web-interface-or-api)
57+
- [Available for pull request merges](#available-for-pull-request-merges)
58+
- [Available for pushes using SSH authentication](#available-for-pushes-using-ssh-authentication)
59+
60+
##### Always available
61+
62+
The following variables are always available in the pre-receive hook environment.
63+
64+
| Variable | Description | Example value |
65+
| :- | :- | :- |
66+
| <pre>$GIT_DIR</pre> | Path to the remote repository on the instance | /data/user/repositories/a/ab/<br>a1/b2/34/100001234/1234.git |
67+
| <pre>$GIT_PUSH_OPTION_COUNT</pre> | The number of push options that were sent by the client with `--push-option`. For more information, see "[git-push](https://git-scm.com/docs/git-push#Documentation/git-push.txt---push-optionltoptiongt)" in the Git documentation. | 1 |
68+
| <pre>$GIT\_PUSH\_OPTION\_<em>N</em></pre> | Where _N_ is an integer starting at 0, this variable contains the push option string that was sent by the client. The first option that was sent is stored in `GIT_PUSH_OPTION_0`, the second option that was sent is stored in `GIT_PUSH_OPTION_1`, and so on. For more information about push options, see "[git-push](https://git-scm.com/docs/git-push#git-push---push-optionltoptiongt)" in the Git documentation. | abcd |{% if currentVersion ver_gt "enterprise-server@2.21" %}
69+
| <pre>$GIT_USER_AGENT</pre> | User-agent string sent by the Git client that pushed the changes | git/2.0.0{% endif %}
70+
| <pre>$GITHUB_REPO_NAME</pre> | Name of the repository being updated in _NAME_/_OWNER_ format | octo-org/hello-enterprise |
71+
| <pre>$GITHUB_REPO_PUBLIC</pre> | Boolean representing whether the repository being updated is public | <ul><li>true: Repository's visibility is public</li><li>false: Repository's visibility is private or internal</li></ul>
72+
| <pre>$GITHUB_USER_IP</pre> | IP address of client that initiated the push | 192.0.2.1 |
73+
| <pre>$GITHUB_USER_LOGIN</pre> | Username for account that initiated the push | octocat |
74+
75+
##### Available for pushes from the web interface or API
76+
77+
The `$GITHUB_VIA` variable is available in the pre-receive hook environment when the ref update that triggers the hook occurs via either the web interface or the API for {% data variables.product.prodname_ghe_server %}. The value describes the action that updated the ref.
78+
79+
| Value | Action | More information |
80+
| :- | :- | :- |
81+
| <pre>auto-merge deployment api</pre> | Automatic merge of the base branch via a deployment created with the API | "[Repositories](/rest/reference/repos#create-a-deployment)" in the REST API documentation |
82+
| <pre>blob edit</pre> | Change to a file's contents in the web interface | "[Editing files in your repository](/github/managing-files-in-a-repository/editing-files-in-your-repository)" |
83+
| <pre>branch merge api</pre> | Merge of a branch via the API | "[Repositories](/rest/reference/repos#merge-a-branch)" in the REST API documentation |
84+
| <pre>branches page delete button</pre> | Deletion of a branch in the web interface | "[Creating and deleting branches within your repository](/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch)" |
85+
| <pre>git refs create api</pre> | Creation of a ref via the API | "[Git database](/rest/reference/git#create-a-reference)" in the REST API documentation |
86+
| <pre>git refs delete api</pre> | Deletion of a ref via the API | "[Git database](/rest/reference/git#delete-a-reference)" in the REST API documentation |
87+
| <pre>git refs update api</pre> | Update of a ref via the API | "[Git database](/rest/reference/git#update-a-reference)" in the REST API documentation |
88+
| <pre>git repo contents api</pre> | Change to a file's contents via the API | "[Repositories](/rest/reference/repos#create-or-update-file-contents)" in the REST API documentation |
89+
| <pre>merge base into head</pre> | Update of the topic branch from the base branch when the base branch requires strict status checks (via **Update branch** in a pull request, for example) | "[About protected branches](/github/administering-a-repository/about-protected-branches#require-status-checks-before-merging)" |
90+
| <pre>pull request branch delete button</pre> | Deletion of a topic branch from a pull request in the web interface | "[Deleting and restoring branches in a pull request](/github/administering-a-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request)" |
91+
| <pre>pull request branch undo button</pre> | Restoration of a topic branch from a pull request in the web interface | "[Deleting and restoring branches in a pull request](/github/administering-a-repository/deleting-and-restoring-branches-in-a-pull-request#restoring-a-deleted-branch)" |
92+
| <pre>pull request merge api</pre> | Merge of a pull request via the API | "[Pulls](/rest/reference/pulls#merge-a-pull-request)" in the REST API documentation |
93+
| <pre>pull request merge button</pre> | Merge of a pull request in the web interface | "[Merging a pull request](/github/collaborating-with-issues-and-pull-requests/merging-a-pull-request#merging-a-pull-request-on-github)" |
94+
| <pre>pull request revert button</pre> | Revert of a pull request | "[Reverting a pull request](/github/collaborating-with-issues-and-pull-requests/reverting-a-pull-request)" |
95+
| <pre>releases delete button</pre> | Deletion of a release | "[Managing releases in a repository](/github/administering-a-repository/managing-releases-in-a-repository#deleting-a-release)" |
96+
| <pre>stafftools branch restore</pre> | Restoration of a branch from the site admin dashboard | "[Site admin dashboard](/admin/configuration/site-admin-dashboard#repositories)" |
97+
| <pre>tag create api</pre> | Creation of a tag via the API | "[Git database](/rest/reference/git#create-a-tag-object)" in the REST API documentation |
98+
| <pre>slumlord (#<em>SHA</em>)</pre> | Commit via Subversion | "[Support for Subversion clients](/github/importing-your-projects-to-github/support-for-subversion-clients#making-commits-to-subversion)" |
99+
| <pre>web branch create</pre> | Creation of a branch via the web interface | "[Creating and deleting branches within your repository](/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch)" |
100+
101+
##### Available for pull request merges
102+
103+
The following variables are available in the pre-receive hook environment when the push that triggers the hook is a push due to the merge of a pull request.
104+
105+
| Variable | Description | Example value |
106+
| :- | :- | :- |
107+
| <pre>$GITHUB_PULL_REQUEST_AUTHOR_LOGIN</pre> | Username of account that authored the pull request | octocat |
108+
| <pre>$GITHUB_PULL_REQUEST_HEAD</pre> | The name of the pull request's topic branch, in the format `USERNAME:BRANCH` | <nobr>octocat:fix-bug</nobr> |
109+
| <pre>$GITHUB_PULL_REQUEST_BASE</pre> | The name of the pull request's base branch, in the format `USERNAME:BRANCH` | octocat:main |
110+
111+
##### Available for pushes using SSH authentication
112+
113+
| Variable | Description | Example value |
114+
| :- | :- | :- |
115+
| <pre>$GITHUB_PUBLIC_KEY_FINGERPRINT</pre> | The public key fingerprint for the user who pushed the changes | a1:b2:c3:d4:e5:f6:g7:h8:i9:j0:k1:l2:m3:n4:o5:p6 |
65116

66117
### Setting permissions and pushing a pre-receive hook to {% data variables.product.prodname_ghe_server %}
67118

68-
A pre-receive hook script is contained in a repository on the {% data variables.product.prodname_ghe_server %} appliance. A site administrator must take into consideration the repository permissions and ensure that only the appropriate users have access.
119+
A pre-receive hook script is contained in a repository on {% data variables.product.product_location %}. A site administrator must take into consideration the repository permissions and ensure that only the appropriate users have access.
69120

70121
We recommend consolidating hooks to a single repository. If the consolidated hook repository is public, the `README.md` can be used to explain policy enforcements. Also, contributions can be accepted via pull requests. However, pre-receive hooks can only be added from the default branch. For a testing workflow, forks of the repository with configuration should be used.
71122

@@ -80,7 +131,7 @@ We recommend consolidating hooks to a single repository. If the consolidated hoo
80131
git update-index --chmod=+x <em>SCRIPT_FILE.sh</em>
81132
```
82133

83-
2. Commit and push to your designated pre-receive hooks repository on the {% data variables.product.prodname_ghe_server %} instance.
134+
2. Commit and push to the designated repository for pre-receive hooks on {% data variables.product.product_location %}.
84135

85136
```shell
86137
$ git commit -m "<em>YOUR COMMIT MESSAGE</em>"
@@ -90,36 +141,36 @@ We recommend consolidating hooks to a single repository. If the consolidated hoo
90141
3. [Create the pre-receive hook](/enterprise/{{ currentVersion }}/admin/guides/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance/#creating-pre-receive-hooks) on the {% data variables.product.prodname_ghe_server %} instance.
91142

92143
### Testing pre-receive scripts locally
93-
You can test a pre-receive hook script locally before you create or update it on your {% data variables.product.prodname_ghe_server %} appliance. One method is to create a local Docker environment to act as a remote repository that can execute the pre-receive hook.
144+
You can test a pre-receive hook script locally before you create or update it on {% data variables.product.product_location %}. One method is to create a local Docker environment to act as a remote repository that can execute the pre-receive hook.
94145

95146
{% data reusables.linux.ensure-docker %}
96147

97148
2. Create a file called `Dockerfile.dev` containing:
98149

99-
```dockerfile
100-
FROM gliderlabs/alpine:3.3
101-
RUN \
102-
apk add --no-cache git openssh bash && \
103-
ssh-keygen -A && \
104-
sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \
105-
adduser git -D -G root -h /home/git -s /bin/bash && \
106-
passwd -d git && \
107-
su git -c "mkdir /home/git/.ssh && \
108-
ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \
109-
mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \
110-
mkdir /home/git/test.git && \
111-
git --bare init /home/git/test.git"
112-
113-
VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"]
114-
WORKDIR /home/git
115-
116-
CMD ["/usr/sbin/sshd", "-D"]
117-
```
118-
119-
3. Create a test pre-receive script called `always_reject.sh`. This example script will reject all pushes, which is useful for locking a repository:
120-
121-
```shell
122-
#!/usr/bin/env bash
150+
```dockerfile
151+
FROM gliderlabs/alpine:3.3
152+
RUN \
153+
apk add --no-cache git openssh bash && \
154+
ssh-keygen -A && \
155+
sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \
156+
adduser git -D -G root -h /home/git -s /bin/bash && \
157+
passwd -d git && \
158+
su git -c "mkdir /home/git/.ssh && \
159+
ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \
160+
mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \
161+
mkdir /home/git/test.git && \
162+
git --bare init /home/git/test.git"
163+
164+
VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"]
165+
WORKDIR /home/git
166+
167+
CMD ["/usr/sbin/sshd", "-D"]
168+
```
169+
170+
3. Create a test pre-receive script called `always_reject.sh`. This example script will reject all pushes, which is useful for locking a repository:
171+
172+
```
173+
#!/usr/bin/env bash
123174
124175
echo "error: rejecting all pushes"
125176
exit 1

0 commit comments

Comments
 (0)