Skip to content
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

Commit 22879a2

Browse files
author
Hubot
committed
Sync changes from upstream repository
1 parent 95b05a9 commit 22879a2

File tree

6 files changed

+620
-0
lines changed

6 files changed

+620
-0
lines changed

‎content/v3/enterprise/pre_receive_environments.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Pre-receive Environments
3+
---
4+
5+
# Pre-receive Environments
6+
7+
{{#tip}}
8+
9+
<a name="preview-period"></a>
10+
11+
APIs for managing pre-receive hooks are currently available for developers to preview.
12+
During the preview period, the APIs may change without advance notice.
13+
14+
To access the API you must provide a custom [media type](/v3/media) in the `Accept` header:
15+
16+
application/vnd.github.eye-scream-preview
17+
18+
{{/tip}}
19+
20+
{:toc}
21+
22+
The Pre-receive Environments API allows you to create, list, update and delete environments for pre-receive hooks. *It is only available to [authenticated](/v3/#authentication) site administrators.* Normal users will receive a `404` response if they try to access it.
23+
24+
Prefix all the endpoints for this API with the following URL:
25+
26+
``` command-line
27+
http(s)://<em>hostname</em>/api/v3
28+
```
29+
30+
## Object attributes
31+
32+
### Pre-receive Environment
33+
34+
| Name | Type | Description |
35+
|-----------------------|-----------|----------------------------------------------------------------------------|
36+
| `name` | `string` | The name of the environment as displayed in the UI. |
37+
| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. |
38+
| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. |
39+
| `download` | `object` | This environment's download status. |
40+
| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. |
41+
42+
### Pre-receive Environment Download
43+
44+
| Name | Type | Description |
45+
|-----------------|----------|---------------------------------------------------------|
46+
| `state` | `string` | The state of the most recent download. |
47+
| `downloaded_at` | `string` | The time when the most recent download started. |
48+
| `message` | `string` | On failure, this will have any error messages produced. |
49+
50+
Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`.
51+
52+
53+
## Get a single pre-receive environment
54+
55+
GET /admin/pre-receive-environments/:id
56+
57+
<%= headers 200 %>
58+
<%= json :pre_receive_environment %>
59+
60+
## List pre-receive environments
61+
62+
GET /admin/pre_receive_environments
63+
64+
<%= headers 200, :pagination => default_pagination_rels %>
65+
<%= json :pre_receive_environments %>
66+
67+
## Create a pre-receive environment
68+
69+
POST /admin/pre_receive_environments
70+
71+
### Parameters
72+
73+
| Name | Type | Description |
74+
|-------------|----------|-------------------------------------------------------------------------|
75+
| `name` | `string` | **Required**. The new pre-receive environment's name. |
76+
| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. |
77+
78+
<%= json \
79+
:name => 'DevTools Hook Env',
80+
:image_url => 'https://my_file_server/path/to/devtools_env.tar.gz'
81+
%>
82+
83+
### Response
84+
85+
<%= headers 201 %>
86+
<%= json :pre_receive_environment_create %>
87+
88+
## Edit a pre-receive environment
89+
90+
PATCH /admin/pre_receive_environments/:id
91+
92+
### Parameters
93+
94+
| Name | Type | Description |
95+
|-------------|----------|-----------------------------------------------------------|
96+
| `name` | `string` | This pre-receive environment's new name. |
97+
| `image_url` | `string` | URL from which to download a tarball of this environment. |
98+
99+
### Response
100+
<%= headers 200 %>
101+
<%= json :pre_receive_environment %>
102+
103+
#### Client Errors
104+
105+
If you attempt to modify the default environment, you will get a response like this:
106+
107+
<%= headers 422 %>
108+
<%=
109+
json :message => "Validation Failed",
110+
:errors => [{
111+
:resource => :PreReceiveEnvironment,
112+
:code => :custom,
113+
:message => 'Cannot modify or delete the default environment'
114+
}]
115+
%>
116+
117+
## Delete a pre-receive environment
118+
119+
DELETE /admin/pre_receive_environments/:id
120+
121+
### Response
122+
123+
<%= headers 204 %>
124+
125+
#### Client Errors
126+
127+
If you attempt to delete an environment that cannot be deleted, you will get a response like this:
128+
129+
<%= headers 422 %>
130+
<%=
131+
json :message => "Validation Failed",
132+
:errors => [{
133+
:resource => :PreReceiveEnvironment,
134+
:code => :custom,
135+
:message => 'Cannot modify or delete the default environment'
136+
}]
137+
%>
138+
139+
The possible error messages are:
140+
141+
- _Cannot modify or delete the default environment_
142+
- _Cannot delete environment that has hooks_
143+
- _Cannot delete environment when download is in progress_
144+
145+
## Get a pre-receive environment's download status
146+
147+
In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status.
148+
149+
GET /admin/pre-receive-environments/:id/downloads/latest
150+
151+
<%= headers 200 %>
152+
<%= json :pre_receive_environment_download_2 %>
153+
154+
### Object attributes
155+
156+
| Name | Type | Description |
157+
|-----------------|----------|---------------------------------------------------------|
158+
| `state` | `string` | The state of the most recent download. |
159+
| `downloaded_at` | `string` | The time when the most recent download started. |
160+
| `message` | `string` | On failure, this will have any error messages produced. |
161+
162+
Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`.
163+
164+
## Trigger a pre-receive environment download
165+
166+
Triggers a new download of the environment tarball from the environment's `image_url`. When the download is finished, the newly downloaded tarball will overwrite the existing environment.
167+
168+
POST /admin/pre_receive_environments/:id/downloads
169+
170+
### Response
171+
172+
<%= headers 202 %>
173+
<%= json :pre_receive_environment_download %>
174+
175+
#### Client Errors
176+
177+
If a download cannot be triggered, you will get a reponse like this:
178+
179+
<%= headers 422 %>
180+
<%=
181+
json :message => "Validation Failed",
182+
:errors => [{
183+
:resource => :PreReceiveEnvironment,
184+
:code => :custom,
185+
:message => 'Can not start a new download when a download is in progress'
186+
}]
187+
%>
188+
189+
The possible error messages are:
190+
191+
- _Cannot modify or delete the default environment_
192+
- _Can not start a new download when a download is in progress_
193+

‎content/v3/enterprise/pre_receive_hooks.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Pre-receive Hooks
3+
---
4+
5+
# Pre-receive Hooks
6+
7+
{{#tip}}
8+
9+
<a name="preview-period"></a>
10+
11+
APIs for managing pre-receive hooks are currently available for developers to preview.
12+
During the preview period, the APIs may change without advance notice.
13+
14+
To access the API you must provide a custom [media type](/v3/media) in the `Accept` header:
15+
16+
application/vnd.github.eye-scream-preview
17+
18+
{{/tip}}
19+
20+
{:toc}
21+
22+
The Pre-receive Hooks API allows you to create, list, update and delete
23+
pre-receive hooks. *It is only available to
24+
[authenticated](/v3/#authentication) site administrators.* Normal users
25+
will receive a `404` response if they try to access it.
26+
27+
Prefix all the endpoints for this API with the following URL:
28+
29+
``` command-line
30+
http(s)://<em>hostname</em>/api/v3
31+
```
32+
33+
## Object attributes
34+
35+
### Pre-receive Hook
36+
37+
| Name | Type | Description |
38+
|----------------------------------|-----------|-----------------------------------------------------------------|
39+
| `name` | `string` | The name of the hook. |
40+
| `script` | `string` | The script that the hook runs. |
41+
| `script_repository` | `object` | The GitHub repository where the script is kept. |
42+
| `environment` | `object` | The pre-receive environment where the script is executed. |
43+
| `enforcement` | `string` | The state of enforcement for this hook. |
44+
| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. |
45+
46+
Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject
47+
any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected.
48+
49+
## Get a single pre-receive hook
50+
51+
GET /admin/pre-receive-hooks/:id
52+
53+
<%= headers 200 %> <%= json :pre_receive_hook %>
54+
55+
## List pre-receive hooks
56+
57+
GET /admin/pre-receive-hooks
58+
59+
<%= headers 200, :pagination => default_pagination_rels %>
60+
<%= json :pre_receive_hooks %>
61+
62+
## Create a pre-receive hook
63+
64+
POST /admin/pre-receive-hooks
65+
66+
### Parameters
67+
68+
| Name | Type | Description |
69+
|----------------------------------|-----------|----------------------------------------------------------------------------------|
70+
| `name` | `string` | **Required** The name of the hook. |
71+
| `script` | `string` | **Required** The script that the hook runs. |
72+
| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. |
73+
| `environment` | `object` | **Required** The pre-receive environment where the script is executed. |
74+
| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` |
75+
| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` |
76+
77+
<%= json \
78+
:name => "Check Commits",
79+
:script => "scripts/commit_check.sh",
80+
:enforcement => "disabled",
81+
:allow_downstream_configuration => false,
82+
:script_repository => { :full_name => "DevIT/hooks" },
83+
:environment => { :id => 2 }
84+
%>
85+
86+
### Response
87+
<%= headers 201 %>
88+
<%= json :pre_receive_hook %>
89+
90+
## Edit a pre-receive hook
91+
92+
PATCH /admin/pre_receive_hooks/:id
93+
94+
<%= json \
95+
:name => "Check Commits",
96+
:environment => { :id => 1 },
97+
:allow_downstream_configuration => true
98+
%>
99+
100+
### Response
101+
<%= headers 200 %>
102+
<%= json :pre_receive_hook_update %>
103+
104+
## Delete a pre-receive hook
105+
106+
DELETE /admin/pre_receive_hooks/:id
107+
108+
### Response
109+
110+
<%= headers 204 %>

‎content/v3/orgs/pre_receive_hooks.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Organization Pre-receive Hooks
3+
---
4+
5+
# Organization Pre-receive Hooks (Enterprise)
6+
7+
{{#tip}}
8+
9+
<a name="preview-period"></a>
10+
11+
APIs for managing pre-receive hooks are currently available for developers to preview.
12+
During the preview period, the APIs may change without advance notice.
13+
14+
To access the API you must provide a custom [media type](/v3/media) in the `Accept` header:
15+
16+
application/vnd.github.eye-scream-preview
17+
18+
{{/tip}}
19+
20+
{:toc}
21+
22+
The Organization Pre-receive Hooks API allows you to view and modify
23+
enforcement of the pre-receive hooks that are available to an organization.
24+
25+
Prefix all the endpoints for this API with the following URL:
26+
27+
``` command-line
28+
http(s)://<em>hostname</em>/api/v3
29+
```
30+
31+
## Object attributes
32+
33+
| Name | Type | Description |
34+
|----------------------------------|-----------|-----------------------------------------------------------|
35+
| `name` | `string` | The name of the hook. |
36+
| `enforcement` | `string` | The state of enforcement for the hook on this repository. |
37+
| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. |
38+
| `configuration_url` | `string` | URL for the endpoint where enforcement is set. |
39+
40+
Possible values for *enforcement* are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject
41+
any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected.
42+
43+
`configuration_url` may be a link to this endpoint or this hook's global
44+
configuration. Only site admins are able to access the global configuration.
45+
46+
## List pre-receive hooks
47+
48+
List all pre-receive hooks that are enabled or testing for this
49+
organization as well as any disabled hooks that can be configured at the
50+
organization level. Globally disabled pre-receive hooks that do not allow
51+
downstream configuration are not listed.
52+
53+
GET /orgs/:org/pre-receive-hooks
54+
55+
<%= headers 200, :pagination => default_pagination_rels %>
56+
<%= json :pre_receive_hooks_org %>
57+
58+
## Get a single pre-receive hook
59+
60+
GET /orgs/:org:pre-receive-hooks/:id
61+
62+
<%= headers 200 %> <%= json :pre_receive_hook_org %>
63+
64+
## Update pre-receive hook enforcement
65+
66+
For pre-receive hooks which are allowed to be configured at the org level, you can set
67+
`enforcement` and `allow_downstream_configuration`
68+
69+
PATCH /orgs/:org/pre-receive-hooks/:id
70+
71+
<%= json :enforcement => "enabled", :allow_downstream_configuration => false %>
72+
73+
### Response
74+
75+
<%= headers 200 %><%= json :pre_receive_hook_org_update %>
76+
77+
## Remove enforcment overrides for a pre-receive hook
78+
79+
Removes any overrides for this hook at the org level for this org.
80+
81+
DELETE /orgs/:org/pre-receive-hooks/:id
82+
83+
<%= headers 200 %> <%= json :pre_receive_hook_org %>

0 commit comments

Comments
 (0)