Sync changes from upstream repository · JavaLeaks/developer.github.com@6673927 · GitHub
Skip to content

Commit 6673927

Browse files
author
Hubot
committed
Sync changes from upstream repository
1 parent 0786f39 commit 6673927

3 files changed

Lines changed: 68 additions & 9 deletions

File tree

‎content/changes/2014-08-15-deployments-api-changes.md‎

Lines changed: 29 additions & 0 deletions

‎content/v3/repos/deployments.md‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -72,12 +72,12 @@ Below is a simple sequence diagram for how these interactions would work.
7272
</pre>
7373

7474
Keep in mind that GitHub is never actually accessing your servers. It's up to
75-
your 3rd party integration to interact with deployment events.
76-
This allows for [github-services](https://github.com/github/github-services)
77-
integrations as well as running your own systems depending on your use case.
78-
Multiple systems can listen for deployment events, and it's up to each of
79-
those systems to decide whether or not they're responsible for pushing the code
80-
out to your servers, building native code, etc.
75+
your 3rd party integration to interact with deployment events. This allows for
76+
[github-services](https://github.com/github/github-services) integrations as
77+
well as running your own systems depending on your use case. Multiple systems
78+
can listen for deployment events, and it's up to each of those systems to
79+
decide whether or not they're responsible for pushing the code out to your
80+
servers, building native code, etc.
8181

8282
Note that the `repo_deployment` [OAuth scope](/v3/oauth/#scopes) grants
8383
targeted access to Deployments and Deployment Statuses **without**
@@ -86,31 +86,58 @@ as well.
8686

8787
## List Deployments
8888

89-
Users with pull access can view deployments for a repository:
89+
Simple filtering of deployments is available via query parameters:
9090

9191
GET /repos/:owner/:repo/deployments
9292

93+
Name | Type | Description
94+
-----|------|--------------
95+
`sha`|`string` | The short or long sha that was recorded at creation time. Default: `none`
96+
`ref`|`string` | The name of the ref. This can be a branch, tag, or sha. Default: `none`
97+
`task`|`string` | The name of the task for the deployment. e.g. `deploy` or `deploy:migrations`. Default: `none`
98+
`environment`|`string` | The name of the environment that was deployed to. e.g. `staging` or `production`. Default: `none`
99+
93100
### Response
94101

95102
<%= headers 200, :pagination => default_pagination_rels %>
96103
<%= json(:deployment) { |h| [h] } %>
97104

98105
## Create a Deployment
99106

107+
Deployments offer a few configurable parameters with sane defaults.
108+
109+
The `ref` parameter can be any named branch, tag, or sha. At GitHub we often
110+
deploy branches and verify them before we merge a pull request.
111+
112+
The `environment` parameters allows deployments to be issued to different
113+
runtime environments. Teams often have multiple environments for verifying
114+
their applications, like 'production', 'staging', and 'qa'. This allows for
115+
easy tracking of which environments had deployments requested. The default
116+
environment is 'production'
100117

101118
The `auto_merge` parameter is used to ensure that the requested ref is not
102119
behind the repository's default branch. If the ref *is* behind the default
103120
branch for the repository, we will attempt to merge it for you. If the merge
104121
succeeds, the API will return a successful merge commit. If merge conflicts
105122
prevent the merge from succeeding, the API will return a failure response.
106123

107-
By default, [commit statuses](/v3/repos/statuses) for every submitted context must be in a 'success' state. The `required_contexts` parameter allows you to specify a subset of contexts that must be "success", or to specify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do not require any contexts or create any commit statuses, the deployment will always succeed.
124+
By default, [commit statuses](/v3/repos/statuses) for every submitted context
125+
must be in a 'success' state. The `required_contexts` parameter allows you to
126+
specify a subset of contexts that must be "success", or to specify contexts
127+
that have not yet been submitted. You are not required to use commit statuses
128+
to deploy. If you do not require any contexts or create any commit statuses,
129+
the deployment will always succeed.
108130

109131
The `payload` parameter is available for any extra information that a
110132
deployment system might need. It is a JSON text field that will be passed on
111133
when a deployment event is dispatched.
112134

113-
Users with push access can create a deployment for a given ref:
135+
The `task` parameter is used by the deployment system to allow different
136+
execution paths. In the web world this might be 'deploy:migrations' to run
137+
schema changes on the system. In the compiled world this could be a flag to
138+
compile an application with debugging enabled.
139+
140+
Users with `repo` or `repo_deployment` scopes can create a deployment for a given ref:
114141

115142
POST /repos/:owner/:repo/deployments
116143

@@ -119,6 +146,7 @@ Users with push access can create a deployment for a given ref:
119146
Name | Type | Description
120147
-----|------|--------------
121148
`ref`|`string`| **Required**. The ref to deploy. This can be a branch, tag, or sha.
149+
`task`|`string`| **Required**. The named task to execute. e.g. `deploy` or `deploy:migrations`. Default: `deploy`
122150
`auto_merge`|`boolean`| Optional parameter to merge the default branch into the requested ref if it is behind the default branch. Default: `true`
123151
`required_contexts`|`Array`| Optional array of status contexts verified against commit status checks. If this parameter is omitted from the parameters then all unique contexts will be verified before a deployment is created. To bypass checking entirely pass an empty array. Defaults to all unique contexts.
124152
`payload`|`string` | Optional JSON payload with extra information about the deployment. Default: `""`

‎lib/resources.rb‎

Lines changed: 2 additions & 0 deletions

0 commit comments

Comments
 (0)