From 5963e53abbae890a6e7e8da8214c3bf711f539da Mon Sep 17 00:00:00 2001 From: Pierre DAL-PRA Date: Thu, 5 May 2016 23:46:04 +0200 Subject: [PATCH 01/81] No field is required when updating an issue label --- content/v3/issues/labels.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/issues/labels.md b/content/v3/issues/labels.md index 5830e0bbf1..718a0c6339 100644 --- a/content/v3/issues/labels.md +++ b/content/v3/issues/labels.md @@ -51,8 +51,8 @@ Name | Type | Description Name | Type | Description -----|------|-------------- -`name`|`string` | **Required**. The name of the label. -`color`|`string` |**Required**. A 6 character hex code, without the leading `#`, identifying the color. +`name`|`string` | The name of the label. +`color`|`string` | A 6 character hex code, without the leading `#`, identifying the color. <%= json :name => "bug", :color => "f29513" %> From 0e61e5f2f2da13f22a5ca111a73b894176f397d6 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 6 May 2016 15:32:22 -0700 Subject: [PATCH 02/81] Sync changes from upstream repository --- content/v3/activity/events/types.md | 38 +++++++++++++++++------------ content/webhooks/index.md | 10 ++++---- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/content/v3/activity/events/types.md b/content/v3/activity/events/types.md index 800987ad3b..9504e2de89 100644 --- a/content/v3/activity/events/types.md +++ b/content/v3/activity/events/types.md @@ -239,15 +239,19 @@ Key | Type | Description ## IssueCommentEvent +{% if page.version == 'dotcom' or page.version > 2.6 %} Triggered when an [issue comment](/v3/issues/comments/) is created, edited, or deleted. +{% else %} +Triggered when an [issue is commented on](/v3/issues/comments/). +{% endif %} ### Events API payload Key | Type | Description ----|------|------------- -`action`|`string` | The action that was performed on the comment. Can be one of "created", "edited", or "deleted". +`action`|`string` | The action that was performed on the comment. {% if page.version == 'dotcom' or page.version > 2.6 %}Can be one of "created", "edited", or "deleted". `changes`|`object` | The changes to the comment if the action was "edited". -`changes[body][from]` |`string` | The previous version of the body if the action was "edited". +`changes[body][from]` |`string` | The previous version of the body if the action was "edited".{% else %}Currently, can only be "created".{% endif %} `issue`|`object` | The [issue](/v3/issues/) the comment belongs to. `comment`|`object` | The [comment](/v3/issues/comments/) itself. @@ -261,17 +265,17 @@ Key | Type | Description ## IssuesEvent -Triggered when an [issue](/v3/issues) is assigned, unassigned, labeled, unlabeled, opened, edited, closed, or reopened. +Triggered when an [issue](/v3/issues) is assigned, unassigned, labeled, unlabeled, opened, {% if page.version == 'dotcom' or page.version > 2.6 %}edited, {% endif %}closed, or reopened. ### Events API payload Key | Type | Description ----|------|------------- -`action`|`string` | The action that was performed. Can be one of "assigned", "unassigned", "labeled", "unlabeled", "opened", "edited", "closed", or "reopened". -`issue`|`object` | The [issue](/v3/issues) itself. +`action`|`string` | The action that was performed. Can be one of "assigned", "unassigned", "labeled", "unlabeled", "opened", {% if page.version == 'dotcom' or page.version > 2.6 %}"edited", {% endif %}"closed", or "reopened". +`issue`|`object` | The [issue](/v3/issues) itself.{% if page.version == 'dotcom' or page.version > 2.6 %} `changes`|`object`| The changes to the issue if the action was "edited". `changes[title][from]`|`string` | The previous version of the title if the action was "edited". -`changes[body][from]`|`string` | The previous version of the body if the action was "edited". +`changes[body][from]`|`string` | The previous version of the body if the action was "edited".{% endif %} `assignee`|`object` | The optional user who was assigned or unassigned from the issue. `label`|`object` | The optional label that was added or removed from the issue. @@ -363,17 +367,17 @@ Triggered when a private repository is [open sourced](/v3/repos/#edit). Without ## PullRequestEvent -Triggered when a [pull request](/v3/pulls) is assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, or synchronized. +Triggered when a [pull request](/v3/pulls) is assigned, unassigned, labeled, unlabeled, opened, {% if page.version == 'dotcom' or page.version > 2.6 %}edited, {% endif %}closed, reopened, or synchronized. ### Events API payload Key | Type | Description ----|------|------------- -`action`|`string` | The action that was performed. Can be one of "assigned", "unassigned", "labeled", "unlabeled", "opened", "edited", "closed", or "reopened", or "synchronize". If the action is "closed" and the `merged` key is `false`, the pull request was closed with unmerged commits. If the action is "closed" and the `merged` key is `true`, the pull request was merged. -`number`|`integer` | The pull request number. +`action`|`string` | The action that was performed. Can be one of "assigned", "unassigned", "labeled", "unlabeled", "opened", {% if page.version == 'dotcom' or page.version > 2.6 %}"edited", {% endif %}"closed", or "reopened", or "synchronize". If the action is "closed" and the `merged` key is `false`, the pull request was closed with unmerged commits. If the action is "closed" and the `merged` key is `true`, the pull request was merged. +`number`|`integer` | The pull request number.{% if page.version == 'dotcom' or page.version > 2.6 %} `changes`|`object`| The changes to the comment if the action was "edited". `changes[title][from]`|`string` | The previous version of the title if the action was "edited". -`changes[body][from]`|`string` | The previous version of the body if the action was "edited". +`changes[body][from]`|`string` | The previous version of the body if the action was "edited".{% endif %} `pull_request`|`object` | The [pull request](/v3/pulls) itself. ### Webhook event name @@ -386,15 +390,19 @@ Key | Type | Description ## PullRequestReviewCommentEvent +{% if page.version == 'dotcom' or page.version > 2.6 %} Triggered when a [comment on a Pull Request's unified diff](/v3/pulls/comments) is created, edited, or deleted (in the Files Changed tab). +{% else %} +Triggered when a [Pull Request's unified diff is commented on](/v3/pulls/comments) (in the Files Changed tab). +{% endif %} ### Events API payload Key | Type | Description ----|------|------------- -`action`|`string` | The action that was performed on the comment. Can be one of `created`, `edited`, or `deleted`. +`action`|`string` | The action that was performed on the comment. {% if page.version == 'dotcom' or page.version > 2.6 %}Can be one of "created", "edited", or "deleted". `changes`|`object`| The changes to the comment if the action was "edited". -`changes[body][from]`|`string` | The previous version of the body if the action was "edited". +`changes[body][from]`|`string` | The previous version of the body if the action was "edited".{% else %}Currently, can only be "created".{% endif %} `pull_request`|`object` | The [pull request](/v3/pulls/) the comment belongs to. `comment`|`object` | The [comment](/v3/pulls/comments) itself. @@ -463,15 +471,15 @@ Key | Type | Description ## RepositoryEvent -Triggered when a repository is created, deleted, made public, or made private. +Triggered when a repository is created{% if page.version == 'dotcom' or page.version > 2.6 %}, deleted, made public, or made private{% endif %}. -Events of this type are not visible in timelines. These events are only used to trigger hooks. +Events of this type are not visible in timelines. These events are only used to trigger {% if page.version != 'dotcom' and page.version <= 2.6 %}organization {% endif %}hooks. ### Events API payload Key | Type | Description ----|------|------------- -`action` |`string` | The action that was performed. This can be one of `created`, `deleted`, `publicized`, or `privatized`. +`action` |`string` | The action that was performed. {% if page.version == 'dotcom' or page.version > 2.6 %}This can be one of "created", "deleted", "publicized", or "privatized".{% else %}Currently, can only be "created".{% endif %} `repository`|`object` | The [repository](/v3/repos/) itself. ### Webhook event name diff --git a/content/webhooks/index.md b/content/webhooks/index.md index bd109cf2d1..76fea2de20 100644 --- a/content/webhooks/index.md +++ b/content/webhooks/index.md @@ -48,16 +48,16 @@ Name | Description [`deployment_status`][event-types-deployment_status] | Any time a deployment for a Repository has a status update from the API. [`fork`][event-types-fork] | Any time a Repository is forked. [`gollum`][event-types-gollum] | Any time a Wiki page is updated. -[`issue_comment`][event-types-issue_comment] | Any time a [comment on an issue](/v3/issues/comments/) is created, edited, or deleted. -[`issues`][event-types-issues] | Any time an Issue is assigned, unassigned, labeled, unlabeled, opened, edited, closed, or reopened. +[`issue_comment`][event-types-issue_comment] | {% if page.version == 'dotcom' or page.version > 2.6 %}Any time a [comment on an issue](/v3/issues/comments/) is created, edited, or deleted.{% else %}Any time an [issue is commented on](/v3/issues/comments).{% endif %} +[`issues`][event-types-issues] | Any time an Issue is assigned, unassigned, labeled, unlabeled, opened, {% if page.version == 'dotcom' or page.version > 2.6 %}edited, {% endif %}closed, or reopened. [`member`][event-types-member] | Any time a User is added as a collaborator to a non-Organization Repository. [`membership`][event-types-membership] | Any time a User is added or removed from a team. **Organization hooks only**. [`page_build`][event-types-page_build] | Any time a Pages site is built or results in a failed build. [`public`][event-types-public] | Any time a Repository changes from private to public. -[`pull_request_review_comment`][event-types-pull_request_review_comment] | Any time a [comment on a pull request's unified diff](/v3/pulls/comments) is created, edited, or deleted (in the Files Changed tab). -[`pull_request`][event-types-pull_request] | Any time a Pull Request is assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, or synchronized (updated due to a new push in the branch that the pull request is tracking). +[`pull_request_review_comment`][event-types-pull_request_review_comment] | {% if page.version == 'dotcom' or page.version > 2.6 %}Any time a [comment on a Pull Request's unified diff](/v3/pulls/comments) is created, edited, or deleted{% else %}Any time a [Pull Request's unified diff is commented on](/v3/pulls/comments){% endif %} (in the Files Changed tab). +[`pull_request`][event-types-pull_request] | Any time a Pull Request is assigned, unassigned, labeled, unlabeled, opened, {% if page.version == 'dotcom' or page.version > 2.6 %}edited, {% endif %}closed, reopened, or synchronized (updated due to a new push in the branch that the pull request is tracking). [`push`][event-types-push] | Any Git push to a Repository, including editing tags or branches. Commits via API actions that update references are also counted. **This is the default event.** -[`repository`][event-types-repository] | Any time a Repository is created, deleted, made public, or made private. +[`repository`][event-types-repository] | Any time a Repository is created{% if page.version == 'dotcom' or page.version > 2.6 %}, deleted, made public, or made private{% else %}. **Organization hooks only**{% endif %}. [`release`][event-types-release] | Any time a Release is published in a Repository. [`status`][event-types-status] | Any time a Repository has a status update from the API [`team_add`][event-types-team_add] | Any time a team is added or modified on a Repository. From 23dd0abcc9e17e2251d7c5c956f6297360f5eecf Mon Sep 17 00:00:00 2001 From: Edward Jiang Date: Fri, 6 May 2016 17:29:45 -0700 Subject: [PATCH 03/81] changed comma to space in accordance with OAuth spec --- content/v3/oauth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/v3/oauth.md b/content/v3/oauth.md index 03182ab6fe..f1eef51017 100644 --- a/content/v3/oauth.md +++ b/content/v3/oauth.md @@ -35,7 +35,7 @@ Name | Type | Description -----|------|-------------- `client_id`|`string` | **Required**. The client ID you received from GitHub when you [registered](https://github.com/settings/applications/new). `redirect_uri`|`string` | The URL in your app where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). -`scope`|`string` | A comma separated list of [scopes](#scopes). If not provided, `scope` defaults to an empty list of scopes for users that don't have a valid token for the app. For users who do already have a valid token for the app, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow. +`scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list of scopes for users that don't have a valid token for the app. For users who do already have a valid token for the app, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow. `state`|`string` | An unguessable random string. It is used to protect against cross-site request forgery attacks. `allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. @@ -204,11 +204,11 @@ Name | Description {% if page.version == 'dotcom' %}`admin:gpg_key`| Fully manage GPG keys.{% endif %} NOTE: Your application can request the scopes in the initial redirection. You -can specify multiple scopes by separating them with a comma: +can specify multiple scopes by separating them with a space: https://github.com/login/oauth/authorize? client_id=...& - scope=user,public_repo + scope=user%20public_repo ## Common errors for the authorization request From 1d6a85f070fd62cc705843dcc88f4f3c4eaa7331 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 12 May 2016 12:47:07 -0700 Subject: [PATCH 04/81] Sync changes from upstream repository --- .../2016-05-12-reactions-api-preview.md | 33 +++ content/v3/issues.md | 62 ++++++ content/v3/issues/comments.md | 63 ++++++ content/v3/pulls/comments.md | 63 ++++++ content/v3/reactions.md | 208 ++++++++++++++++++ content/v3/repos/comments.md | 63 ++++++ layouts/sidebar.html | 9 + lib/responses/git.rb | 11 + lib/responses/issues_and_prs.rb | 9 + lib/responses/reactions.rb | 21 ++ 10 files changed, 542 insertions(+) create mode 100644 content/changes/2016-05-12-reactions-api-preview.md create mode 100644 content/v3/reactions.md create mode 100644 lib/responses/reactions.rb diff --git a/content/changes/2016-05-12-reactions-api-preview.md b/content/changes/2016-05-12-reactions-api-preview.md new file mode 100644 index 0000000000..fbf93d1aa7 --- /dev/null +++ b/content/changes/2016-05-12-reactions-api-preview.md @@ -0,0 +1,33 @@ +--- +title: Preview support for Reactions API +author_name: kneemer +--- + +GitHub recently added [Reactions to Pull Requests, Issues, and Comments][reactions-blog-post] to help people express their feelings more simply and effectively in conversations. We are adding endpoints for Reactions so that you can now react and unreact via the API. You can enable these changes during the preview period by providing a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + +For example: + +To view reactions on an issue: + +``` command-line +$ curl "https://api.github.com/repos/github/hubot/issues/1/reactions" \ + -H "Accept: application/vnd.github.squirrel-girl-preview" +``` + + +You can learn more about the new reaction response objects in the updated [Commit comment][commit-comment-doc], [Issue][issue-doc], [Issue comment][issue-comment-doc], and [Review Comment][review-comment-doc] documentation. There is also new [Reaction][reaction-doc] documentation. + +During the preview period, we may change aspects of these APIs based on developer feedback. We will announce the changes here on the developer blog, but we will not provide advance notice. + +If you have any questions or feedback, please [let us know][contact]. + +[media-type]: /v3/media +[reaction-doc]: /v3/reactions +[issue-doc]: /v3/issues#preview-period-org-issues +[issue-comment-doc]: /v3/issues/comments#preview-period-issue-comments +[review-comment-doc]: /v3/pulls/comments#preview-period-pull-comments +[commit-comment-doc]: /v3/repos/comments#preview-period-commits-comments +[contact]: https://github.com/contact?form%5Bsubject%5D=Reactions+API+Preview +[reactions-blog-post]: https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments diff --git a/content/v3/issues.md b/content/v3/issues.md index 046606cc3e..63f3f65a22 100644 --- a/content/v3/issues.md +++ b/content/v3/issues.md @@ -49,6 +49,26 @@ Name | Type | Description <%= headers 200, :pagination => default_pagination_rels %> <%= json(:issue) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_reaction_summary %> +{% endif %} + ## List issues for a repository <%= fetch_content(:prs_as_issues) %> @@ -74,6 +94,27 @@ Name | Type | Description <%= headers 200, :pagination => default_pagination_rels %> <%= json(:issue) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_reaction_summary %> +{% endif %} + ## Get a single issue <%= fetch_content(:prs_as_issues) %> @@ -85,6 +126,27 @@ Name | Type | Description <%= headers 200 %> <%= json :full_issue %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_reaction_summary %> +{% endif %} + ## Create an issue Any user with pull access to a repository can create an issue. diff --git a/content/v3/issues/comments.md b/content/v3/issues/comments.md index 23ab84be33..b9d077b4a0 100644 --- a/content/v3/issues/comments.md +++ b/content/v3/issues/comments.md @@ -30,6 +30,27 @@ Name | Type | Description <%= headers 200, :pagination => default_pagination_rels %> <%= json(:issue_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_comment_reaction_summary %> +{% endif %} + ## List comments in a repository GET /repos/:owner/:repo/issues/comments @@ -50,6 +71,27 @@ Name | Type | Description <%= headers 200 %> <%= json(:issue_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_comment_reaction_summary %> +{% endif %} + ## Get a single comment GET /repos/:owner/:repo/issues/comments/:id @@ -59,6 +101,27 @@ Name | Type | Description <%= headers 200, :pagination => default_pagination_rels %> <%= json :issue_comment %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the issue comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :issue_comment_reaction_summary %> +{% endif %} + ## Create a comment POST /repos/:owner/:repo/issues/:number/comments diff --git a/content/v3/pulls/comments.md b/content/v3/pulls/comments.md index bd22d27864..fa543427ab 100644 --- a/content/v3/pulls/comments.md +++ b/content/v3/pulls/comments.md @@ -24,6 +24,27 @@ types](#custom-media-types). You can read more about the use of media types in t <%= headers 200, :pagination => default_pagination_rels %> <%= json(:pull_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the review comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :pull_comment_reaction_summary %> +{% endif %} + ## List comments in a repository GET /repos/:owner/:repo/pulls/comments @@ -44,6 +65,27 @@ Name | Type | Description <%= headers 200, :pagination => default_pagination_rels %> <%= json(:pull_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the review comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :pull_comment_reaction_summary %> +{% endif %} + ## Get a single comment GET /repos/:owner/:repo/pulls/comments/:id @@ -53,6 +95,27 @@ Name | Type | Description <%= headers 200 %> <%= json :pull_comment %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the review comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :pull_comment_reaction_summary %> +{% endif %} + ## Create a comment POST /repos/:owner/:repo/pulls/:number/comments diff --git a/content/v3/reactions.md b/content/v3/reactions.md new file mode 100644 index 0000000000..a492093f4c --- /dev/null +++ b/content/v3/reactions.md @@ -0,0 +1,208 @@ +--- +title: Reactions +--- + +{% if page.version == 'dotcom' %} + +# Reactions + +{{#tip}} + + + + APIs for managing reactions are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + +{{/tip}} + +{:toc} + + +## Reaction types + + When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): + +content | emoji +-----|------ +`+1` | :+1: +`-1` | :-1: +`laugh` | :smile: +`confused` | :confused: +`heart` | :heart: +`hooray` | :tada: + + +## List reactions for a commit comment + + GET /repos/:owner/:repo/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | Indicates which type of reaction to return. + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:reaction) { |h| [h] } %> + + +## Create reaction for a commit comment + + POST /repos/:owner/:repo/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | **Required**. The reaction type + +<%= json :content => 'heart' %> + +### Response + +{{#tip}} + + If you have already created a reaction of type `content`, the previously created reaction will be returned with `Status: 200 OK`. + +{{/tip}} + +<%= headers 201 %> +<%= json :reaction %> + + +## List reactions for an issue + + GET /repos/:owner/:repo/issues/:number/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | Indicates which type of reaction to return. + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:reaction) { |h| [h] } %> + + +## Create reaction for an issue + + POST /repos/:owner/:repo/issues/:number/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | **Required**. The reaction type + +<%= json :content => 'heart' %> + +### Response + +{{#tip}} + + If you have already created a reaction of type `content`, the previously created reaction will be returned with `Status: 200 OK`. + +{{/tip}} + +<%= headers 201 %> +<%= json :reaction %> + + +## List reactions for an issue comment + + GET /repos/:owner/:repo/issues/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | Indicates which type of reaction to return. + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:reaction) { |h| [h] } %> + + +## Create reaction for an issue comment + + POST /repos/:owner/:repo/issues/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | **Required**. The reaction type + +<%= json :content => 'heart' %> + +### Response + +{{#tip}} + + If you have already created a reaction of type `content`, the previously created reaction will be returned with `Status: 200 OK`. + +{{/tip}} + +<%= headers 201 %> +<%= json :reaction %> + + +## List reactions for a pull request review comment + + GET /repos/:owner/:repo/pulls/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | Indicates which type of reaction to return. + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:reaction) { |h| [h] } %> + + +## Create reaction for a pull request review comment + + POST /repos/:owner/:repo/pulls/comments/:id/reactions + +### Parameters + +Name | Type | Description +-----|------|-------------- +`content`|`string` | **Required**. The reaction type + +<%= json :content => 'heart' %> + +### Response + +{{#tip}} + + If you have already created a reaction of type `content`, the previously created reaction will be returned with `Status: 200 OK`. + +{{/tip}} + +<%= headers 201 %> +<%= json :reaction %> + + +## Delete a reaction + + DELETE /reactions/:id + +### Response + +<%= headers 204 %> + +{% endif %} diff --git a/content/v3/repos/comments.md b/content/v3/repos/comments.md index 82959fa925..e6f9bb5050 100644 --- a/content/v3/repos/comments.md +++ b/content/v3/repos/comments.md @@ -20,6 +20,27 @@ Comments are ordered by ascending ID. <%= headers 200, :pagination => default_pagination_rels %> <%= json(:commit_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the commit comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :commit_comment_reaction_summary %> +{% endif %} + ## List comments for a single commit GET /repos/:owner/:repo/commits/:ref/comments @@ -29,6 +50,27 @@ Comments are ordered by ascending ID. <%= headers 200, :pagination => default_pagination_rels %> <%= json(:commit_comment) { |h| [h] } %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the commit comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :commit_comment_reaction_summary %> +{% endif %} + ## Create a commit comment POST /repos/:owner/:repo/commits/:sha/comments @@ -66,6 +108,27 @@ Name | Type | Description <%= headers 200 %> <%= json :commit_comment %> +{% if page.version == 'dotcom' %} +#### Reactions summary + +{{#tip}} + + + + An additional `reactions` object in the commit comment payload is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-12-reactions-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.squirrel-girl-preview + + The `reactions` key will have the following payload where `url` can be used to construct the API location for [listing and creating](/v3/reactions) reactions. + +{{/tip}} +<%= json :commit_comment_reaction_summary %> +{% endif %} + ## Update a commit comment PATCH /repos/:owner/:repo/comments/:id diff --git a/layouts/sidebar.html b/layouts/sidebar.html index d239c196c2..c179fd3fc7 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -83,6 +83,15 @@

Review Comments +
  • +

    Reactions

    + +

  • Repositories

      diff --git a/lib/responses/git.rb b/lib/responses/git.rb index 97ed4d345d..ab4e20f637 100644 --- a/lib/responses/git.rb +++ b/lib/responses/git.rb @@ -1,4 +1,5 @@ require_relative 'user' +require_relative 'reactions' module GitHub module Resources @@ -470,6 +471,16 @@ module Responses "message" => "Not Found", "documentation_url" => "https://developer.github.com/v3" } + + + PULL_COMMENT_REACTION_SUMMARY ||= REACTION_SUMMARY.merge({ + "url" => PULL_COMMENT["url"] + "/reactions" + }) + + COMMIT_COMMENT_REACTION_SUMMARY ||= REACTION_SUMMARY.merge({ + "url" => COMMIT_COMMENT["url"] + "/reactions" + }) + end end end diff --git a/lib/responses/issues_and_prs.rb b/lib/responses/issues_and_prs.rb index f254f45c18..897e4d8cb8 100644 --- a/lib/responses/issues_and_prs.rb +++ b/lib/responses/issues_and_prs.rb @@ -1,5 +1,6 @@ require_relative 'user' require_relative 'repos' +require_relative 'reactions' module GitHub module Resources @@ -153,6 +154,14 @@ module Responses } FULL_ISSUE_EVENT ||= ISSUE_EVENT.merge('issue' => ISSUE) + + ISSUE_REACTION_SUMMARY ||= REACTION_SUMMARY.merge({ + "url" => ISSUE["url"] + "/reactions" + }) + + ISSUE_COMMENT_REACTION_SUMMARY ||= REACTION_SUMMARY.merge({ + "url" => ISSUE_COMMENT["url"] + "/reactions" + }) end end end diff --git a/lib/responses/reactions.rb b/lib/responses/reactions.rb new file mode 100644 index 0000000000..cdef1d59fd --- /dev/null +++ b/lib/responses/reactions.rb @@ -0,0 +1,21 @@ +module GitHub + module Resources + module Responses + REACTION ||= { + "id": 1, + "user_id": 1, + "content": "heart" + } + + REACTION_SUMMARY ||= { + "total_count": 5, + "+1": 3, + "-1": 1, + "laugh": 0, + "confused": 0, + "heart": 1, + "hooray": 0 + } + end + end +end From 8b0528e0381cd00918e5c0c1a4c579a5795ca549 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 13 May 2016 16:51:09 -0700 Subject: [PATCH 05/81] Sync changes from upstream repository --- Rakefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Rakefile b/Rakefile index 98322c5037..066f1ab736 100644 --- a/Rakefile +++ b/Rakefile @@ -36,7 +36,7 @@ end desc "Run the HTML-Proofer" task :run_proofer do require 'html-proofer' - ignored_links = [%r{www.w3.org}, /api\.github\.com/] + ignored_links = [%r{www.w3.org}, /api\.github\.com/, /import\.github\.com/] # swap versionless Enterprise articles with versioned paths url_swap = { %r{help.github.com/enterprise/admin/} => "help.github.com/enterprise/#{config[:versions][0]}/admin/", From b0e9b964c2efddb8c10cf4b98bd1b3f8981ba84a Mon Sep 17 00:00:00 2001 From: Hubot Date: Sat, 14 May 2016 01:28:05 -0700 Subject: [PATCH 06/81] Sync changes from upstream repository --- content/v3/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/search.md b/content/v3/search.md index 561b6d444b..05ca2781c1 100644 --- a/content/v3/search.md +++ b/content/v3/search.md @@ -231,7 +231,7 @@ The `q` search term can also contain any combination of the supported issue sear With this qualifier you can restrict the search to issues (`issue`) or pull request (`pr`) only. * [`in`](https://help.github.com/articles/searching-issues#scope-the-search-fields) Qualifies which fields are searched. With this qualifier you can restrict the - search to just the title (`title`), body (`body`), comments (`comment`), or any combination of these. + search to just the title (`title`), body (`body`), comments (`comments`), or any combination of these. * [`author`](https://help.github.com/articles/searching-issues#search-by-the-author-of-an-issue-or-pull-request) Finds issues or pull requests created by a certain user. * [`assignee`](https://help.github.com/articles/searching-issues#search-by-the-assignee-of-an-issue-or-pull-request) From b1d69386fcb8a724dd40684a23563b0b1fdbc70f Mon Sep 17 00:00:00 2001 From: Trent Patterson Date: Mon, 16 May 2016 09:39:45 -0400 Subject: [PATCH 07/81] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 2c0b64ec11..d244718c35 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # developer.github.com +###### This is the source code for: [developer.github.com](https://developer.github.com) + This is a GitHub API resource built with [Nanoc][nanoc]. All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](http://help.github.com/send-pull-requests/). From 5d86e69da428da9bb1ac438ebe30eaff9fc7d030 Mon Sep 17 00:00:00 2001 From: Trent Patterson Date: Tue, 17 May 2016 19:04:19 -0400 Subject: [PATCH 08/81] Update README.md Added the ![](https://api.travis-ci.org/github/developer.github.com.svg) Tag! --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index d244718c35..a0e191b8a2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ -# developer.github.com +# developer.github.com ![](https://api.travis-ci.org/github/developer.github.com.svg) -###### This is the source code for: [developer.github.com](https://developer.github.com) This is a GitHub API resource built with [Nanoc][nanoc]. From 50549fbe709e842793ca53a6f9fcb56e1d7b968b Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 18 May 2016 01:45:21 -0700 Subject: [PATCH 09/81] Sync changes from upstream repository --- .../2013-02-05-changes-to-services.html | 4 +-- content/guides/building-a-ci-server.md | 2 +- content/guides/delivering-deployments.md | 2 +- content/v3/orgs/hooks.md | 1 - content/v3/repos/deployments.md | 2 +- content/v3/repos/hooks.md | 12 +++---- content/webhooks/index.md | 35 ------------------- content/webhooks/securing.md | 3 +- 8 files changed, 11 insertions(+), 50 deletions(-) diff --git a/content/changes/2013-02-05-changes-to-services.html b/content/changes/2013-02-05-changes-to-services.html index dfc4f8ff4c..4ff6d6e8cd 100644 --- a/content/changes/2013-02-05-changes-to-services.html +++ b/content/changes/2013-02-05-changes-to-services.html @@ -28,5 +28,5 @@ core Services backend for everyone. Maintaining custom logic and libraries for over 100 services is taking too much of this focus away. -[codeclimate]: https://github.com/github/github-services/blob/master/lib/services/codeclimate.rb -[cf]: https://github.com/github/github-services/blob/master/lib/services/campfire.rb +[codeclimate]: https://github.com/github/github-services/blob/fbc0db24b8b7685b2058462181d928a5f2a0a448/lib/services/codeclimate.rb +[cf]: https://github.com/github/github-services/blob/fbc0db24b8b7685b2058462181d928a5f2a0a448/lib/services/campfire.rb diff --git a/content/guides/building-a-ci-server.md b/content/guides/building-a-ci-server.md index 653c046991..be7373dc57 100644 --- a/content/guides/building-a-ci-server.md +++ b/content/guides/building-a-ci-server.md @@ -158,7 +158,7 @@ At GitHub, we: All of this communication is funneled back to our chat rooms. You don't need to build your own CI setup to use this example. -You can always rely on [third-party services][integrations]. +You can always rely on [GitHub integrations][integrations]. [deploy API]: /v3/repos/deployments/ [status API]: /v3/repos/statuses/ diff --git a/content/guides/delivering-deployments.md b/content/guides/delivering-deployments.md index 04566ab122..7ddb32df8a 100644 --- a/content/guides/delivering-deployments.md +++ b/content/guides/delivering-deployments.md @@ -175,7 +175,7 @@ server we've built above. At GitHub, we: * In the meantime, Heaven also notifies everyone about the build, via [Hubot][hubot] sitting in our chat rooms That's it! You don't need to build your own deployment setup to use this example. -You can always rely on [third-party services][integrations]. +You can always rely on [GitHub integrations][integrations]. [deploy API]: /v3/repos/deployments/ [status API]: /guides/building-a-ci-server diff --git a/content/v3/orgs/hooks.md b/content/v3/orgs/hooks.md index 4600626ac1..a00c5c4836 100644 --- a/content/v3/orgs/hooks.md +++ b/content/v3/orgs/hooks.md @@ -161,7 +161,6 @@ Name | Description [guid]: http://en.wikipedia.org/wiki/Globally_unique_identifier -[hub-signature]: https://github.com/github/github-services/blob/f3bb3dd780feb6318c42b2db064ed6d481b70a1f/lib/service/http_helper.rb#L77 [ping-event-url]: /webhooks/#ping-event [webhook-events]: /webhooks/#events [event-types]: /v3/activity/events/types/ diff --git a/content/v3/repos/deployments.md b/content/v3/repos/deployments.md index 0dfbfff431..34e2574621 100644 --- a/content/v3/repos/deployments.md +++ b/content/v3/repos/deployments.md @@ -59,7 +59,7 @@ Below is a simple sequence diagram for how these interactions would work. Keep in mind that GitHub is never actually accessing your servers. It's up to your 3rd party integration to interact with deployment events. This allows for -[github-services](https://github.com/github/github-services) integrations as +[GitHub integrations](https://github.com/integrations) as well as running your own systems depending on your use case. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether or not they're responsible for pushing the code out to your diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md index d82fa9d90c..5df7278423 100644 --- a/content/v3/repos/hooks.md +++ b/content/v3/repos/hooks.md @@ -43,17 +43,17 @@ Repositories can have multiple webhooks installed. Each webhook should have a un Name | Type | Description -----|------|-------------- `name`|`string` | **Required**. Use `web` for a webhook or use the name of a valid service. (See /hooks for the list of valid service names.) -`config`|`object` | **Required**. Key/value pairs to provide settings for this hook. These settings vary between the services and are defined in the [github-services](https://github.com/github/github-services) repository. Booleans are stored internally as "1" for true, and "0" for false. Any JSON `true`/`false` values will be converted automatically. +`config`|`object` | **Required**. Key/value pairs to provide settings for this hook. These settings vary between hooks and some are defined in the [github-services](https://github.com/github/github-services) repository. Booleans are stored internally as "1" for true, and "0" for false. Any JSON `true`/`false` values will be converted automatically. `events`|`array` | Determines what events the hook is triggered for. Default: `["push"]` `active`|`boolean` | Determines whether the hook is actually triggered on pushes. #### Example -To create [a webhook](/webhooks), [the following fields are required](https://github.com/github/github-services/blob/master/lib/services/web.rb#L4-11) by the `config`: +To create [a webhook](/webhooks), the following fields are required by the `config`: * `url`: A required string defining the URL to which the payloads will be delivered. * `content_type`: An optional string defining the media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`. -* `secret`: An optional string that's passed with the HTTP requests as an `X-Hub-Signature` header. The value of this header is computed as the [HMAC hex digest of the body, using the `secret` as the key][hub-signature]. +* `secret`: An optional string that's passed with the HTTP requests as an `X-Hub-Signature` header. The value of this header is computed as the HMAC hex digest of the body, using the `secret` as the key. * `insecure_ssl`: An optional string that determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `"0"` (verification is performed) and `"1"` (verification is not performed). The default is `"0"`. Here's how you can create a hook that posts payloads in JSON format: @@ -80,7 +80,7 @@ Here's how you can create a hook that posts payloads in JSON format: Name | Type | Description -----|------|-------------- -`config`|`object` | Key/value pairs to provide settings for this hook. Modifying this will replace the entire config object. These settings vary between the services and are defined in the [github-services](https://github.com/github/github-services) repository. Booleans are stored internally as "1" for true, and "0" for false. Any JSON `true`/`false` values will be converted automatically. +`config`|`object` | Key/value pairs to provide settings for this hook. Modifying this will replace the entire config object. These settings vary between hooks and some are defined in the [github-services](https://github.com/github/github-services) repository. Booleans are stored internally as "1" for true, and "0" for false. Any JSON `true`/`false` values will be converted automatically. `events`|`array` | Determines what events the hook is triggered for. This replaces the entire array of events. Default: `["push"]` `add_events`|`array` | Determines a list of events to be added to the list of events that the Hook triggers for. `remove_events`|`array` | Determines a list of events to be removed from the list of events that the Hook triggers for. @@ -205,14 +205,12 @@ Name | Type | Description ``hub.mode``|`string` | **Required**. Either `subscribe` or `unsubscribe`. ``hub.topic``|`string` |**Required**. The URI of the GitHub repository to subscribe to. The path must be in the format of `/:owner/:repo/events/:event`. ``hub.callback``|`string` | The URI to receive the updates to the topic. -``hub.secret``|`string` | A shared secret key that generates a SHA1 HMAC of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the `X-Hub-Signature` header. You can see [our Ruby implementation][ruby-secret], or [the PubSubHubbub documentation][pshb-secret] for more details. +``hub.secret``|`string` | A shared secret key that generates a SHA1 HMAC of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the `X-Hub-Signature` header. You can see [the PubSubHubbub documentation][pshb-secret] for more details. [guid]: http://en.wikipedia.org/wiki/Globally_unique_identifier [pubsub]: https://github.com/pubsubhubbub/PubSubHubbub [post-receive]: http://help.github.com/post-receive-hooks/ -[ruby-secret]: https://github.com/github/github-services/blob/14f4da01ce29bc6a02427a9fbf37b08b141e81d9/lib/services/web.rb#L47-L50 -[hub-signature]: https://github.com/github/github-services/blob/f3bb3dd780feb6318c42b2db064ed6d481b70a1f/lib/service/http_helper.rb#L77 [pshb-secret]: https://pubsubhubbub.github.io/PubSubHubbub/pubsubhubbub-core-0.4.html#authednotify [events-url]: /webhooks/#events [ping-event-url]: /webhooks/#ping-event diff --git a/content/webhooks/index.md b/content/webhooks/index.md index 76fea2de20..a033ff3662 100644 --- a/content/webhooks/index.md +++ b/content/webhooks/index.md @@ -154,42 +154,10 @@ zen | Random string of GitHub zen | hook_id | The ID of the webhook that triggered the ping | hook | The [webhook configuration][repo-hooks-show] | - -## Service Hooks - -In addition to webhooks, we also offer the ability to install pre-rolled -integrations for a variety of existing services. These services [are contributed -and maintained by the Open Source community][github-services]. - -Service hooks are installed and configured in a similar fashion as webhooks. -When [creating a hook][webhooks-guide-create], just set the `:name` parameter to -a service name instead of "web" (for webhook). The main differences to keep in -mind between webhooks and service hooks are: - -- Service hooks cannot be installed on organizations, only repositories. -- You can only install a one service per integrator for a repository, whereas - multiple webhooks can be installed on each organization/repository. -- Each service hook only supports a specific set of events, depending on the - services implementation. -- Each service has its own unique set of configuration options. - -To see a full list of available services, their supported events, and -configuration options, check out https://api.github.com/hooks. Documentation for all -service hooks can be found in the [docs directory][github-services-docs] of the -github-services repository. - -**Note:** If you are building a new integration, you should build it as webhook. -We suggest creating an [OAuth application][oauth-applications] to automatically -install and manage your users' webhooks. We will no longer be accepting new -services to the [github-services repository][github-services]. - - [service-hooks-section]: #service-hooks [events-section]: #events [wildcard-section]: #wildcard-event [payloads-section]: #payloads -[webhooks-guide-create]: /webhooks/creating/ [org-hooks]: /v3/orgs/hooks/ [repo-hooks]: /v3/repos/hooks/ [repo-hooks-show]: /v3/repos/hooks/#get-single-hook @@ -218,6 +186,3 @@ services to the [github-services repository][github-services]. [event-types-status]: /v3/activity/events/types/#statusevent [event-types-team_add]: /v3/activity/events/types/#teamaddevent [event-types-watch]: /v3/activity/events/types/#watchevent -[github-services]: https://github.com/github/github-services -[github-services-docs]: https://github.com/github/github-services/tree/master/docs -[oauth-applications]: /v3/oauth/ diff --git a/content/webhooks/securing.md b/content/webhooks/securing.md index 8f2706b83a..407ea1f26b 100644 --- a/content/webhooks/securing.md +++ b/content/webhooks/securing.md @@ -31,7 +31,7 @@ $ export SECRET_TOKEN=your_token ## Validating payloads from GitHub -When your secret token is set, GitHub uses it to create a hash signature with each payload. You can find details on the implementation [in our Ruby implementation][ruby-secret]. +When your secret token is set, GitHub uses it to create a hash signature with each payload. This hash signature is passed along with each request in the headers as `X-Hub-Signature`. Suppose you have a basic server listening to webhooks that looks like this: @@ -68,5 +68,4 @@ Obviously, your language and server implementations may differ than this code. T * Using a plain `==` operator is **not advised**. A method like [`secure_compare`][secure_compare] performs a "constant time" string comparison, which renders it safe from certain timing attacks against regular equality operators. -[ruby-secret]: https://github.com/github/github-services/blob/14f4da01ce29bc6a02427a9fbf37b08b141e81d9/lib/services/web.rb#L47-L50 [secure_compare]: http://rubydoc.info/github/rack/rack/master/Rack/Utils.secure_compare From 97c0b1583ec370c61d03af0075b42870e239d699 Mon Sep 17 00:00:00 2001 From: Trent Patterson Date: Wed, 18 May 2016 09:38:49 -0400 Subject: [PATCH 10/81] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a0e191b8a2..b0842a92cb 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# developer.github.com ![](https://api.travis-ci.org/github/developer.github.com.svg) +# developer.github.com [![Build Status](https://travis-ci.org/github/developer.github.com.svg?branch=master)](https://travis-ci.org/github/developer.github.com) This is a GitHub API resource built with [Nanoc][nanoc]. From 62ea15b138643a95e3d24b7b8e741e8df2d2a977 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 19 May 2016 11:13:10 -0700 Subject: [PATCH 11/81] Sync changes from upstream repository --- .../2016-02-19-source-import-preview-api.md | 2 +- content/v3/migration/source_imports.md | 46 ++++++++++++------- lib/responses/source_imports.rb | 25 +++++++++- 3 files changed, 54 insertions(+), 19 deletions(-) diff --git a/content/changes/2016-02-19-source-import-preview-api.md b/content/changes/2016-02-19-source-import-preview-api.md index 58e2a4eee8..1caf3c446e 100644 --- a/content/changes/2016-02-19-source-import-preview-api.md +++ b/content/changes/2016-02-19-source-import-preview-api.md @@ -3,7 +3,7 @@ title: Preview the Source Import API author_name: spraints --- -We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/). +We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/). To access [the Source Import API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header: diff --git a/content/v3/migration/source_imports.md b/content/v3/migration/source_imports.md index 80d1e6acdf..48b778ea0c 100644 --- a/content/v3/migration/source_imports.md +++ b/content/v3/migration/source_imports.md @@ -24,7 +24,7 @@ This API is not currently available on GitHub Enterprise. {{/tip}} -The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://import.github.com/). +The Source Import API lets you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as [the GitHub Importer](https://help.github.com/articles/importing-from-other-version-control-systems-to-github/). A typical source import would [start the import](#start-an-import) and then (optionally) [update the authors](#map-a-commit-author) and/or [set the preference](#set-git-lfs-preference) for using Git LFS if large files exist in the import. A more detailed example can be seen in this diagram: @@ -156,11 +156,17 @@ An import that does not have errors will progress through these steps: If there are problems, you will see one of these in the `status` field: -* `auth_failed` - the import requires authentication in order to connect to the original repository. Make an "Update Existing Import" request, and include `vcs_username` and `vcs_password`. +* `auth_failed` - the import requires authentication in order to connect to the original repository. To update authentication for the import, please see the [Update Existing Import](#update-existing-import) section. * `error` - the import encountered an error. The import progress response will include the `failed_step` and an error message. [Contact support](https://github.com/contact?form%5Bsubject%5D=Source+Import+API+error) for more information. -* `detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. Make an "Update Existing Import" request, and include `vcs_username` and `vcs_password`. -* `detection_found_nothing` - the importer didn't recognize any source control at the URL. -* `detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a `project_choices` field with the possible project choices as values. Make an "Update Existing Import" request, and include `vcs` and (if applicable) `tfvc_project`. +* `detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. To update authentication for the import, please see the [Update Existing Import](#update-existing-import) section. +* `detection_found_nothing` - the importer didn't recognize any source control at the URL. To resolve, [Cancel the import](#cancel-an-import) and [retry](#start-an-import) with the correct URL. +* `detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a `project_choices` field with the possible project choices as values. To update project choice, please see the [Update Existing Import](#update-existing-import) section. + +### The `project_choices` field + +When multiple projects are found at the provided URL, the response hash will include a `project_choices` field, the value of which is an array of hashes each representing a project choice. The exact key/value pairs of the project hashes will differ depending on the version control type. + +<%= json :source_import_project_choices %> ### Git LFS related fields @@ -173,15 +179,10 @@ This section includes details about Git LFS related fields that may be present i ## Update existing import -An import can be updated with credentials or a `project_choice` by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted. +An import can be updated with credentials or a project choice by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted. PATCH /repos/:owner/:repo/import -### Response - -<%= headers 200, :Location => "https://api.github.com/repos/spraints/socm/import" %> -<%= json :source_import %> - ### Parameters for updating authentication Name | Type | Description @@ -203,16 +204,18 @@ Name | Type | Description ### Parameters for updating project choice -Name | Type | Description ------|------|-------------- -`vcs`|`string`|The chosen project's VCS type. -`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported. +Some servers (e.g. TFS servers) can have several projects at a single URL. In those cases the import progress will have the status `detection_found_multiple` and the Import Progress response will include a `project_choices` array. You can select the project to import by providing one of the objects in the `project_choices` array in the update request. + +The following example demonstrates the workflow for updating an import with "project1" as the project choice. Given a `project_choices` array like such: + +<%= json :source_import_project_choices %> ### Example <%= json\ - :vcs => "tfvc", - :tfvc_project => "project" + "vcs": "tfvc", + "tfvc_project": "project1", + "human_name": "project1 (tfs)" %> ### Response @@ -220,6 +223,15 @@ Name | Type | Description <%= headers 200 %> <%= json :source_import_update_project_choice %> +### Parameters for restarting import + +To restart an import, no parameters are provided in the update request. + +### Response + +<%= headers 200, :Location => "https://api.github.com/repos/spraints/socm/import" %> +<%= json :source_import %> + ## Get commit authors Each type of source control system represents authors in a different way. For example, a Git commit author has a display name and an email address, but a Subversion commit author just has a username. The GitHub Importer will make the author information valid, but the author might not be correct. For example, it will change the bare Subversion username `hubot` into something like `hubot `. diff --git a/lib/responses/source_imports.rb b/lib/responses/source_imports.rb index 4aab1913a3..f8388c979a 100644 --- a/lib/responses/source_imports.rb +++ b/lib/responses/source_imports.rb @@ -51,7 +51,7 @@ module Responses "vcs" => "tfvc", "use_lfs": "undecided", "vcs_url" => "http://tfs.mycompany.com/tfs/myproject", - "tfvc_project": "project", + "tfvc_project": "project1", "status" => "importing", "status_text" => "Importing...", "has_large_files" => false, @@ -66,6 +66,29 @@ module Responses "repository_url" => "https://api.github.com/repos/octocat/socm" } + SOURCE_IMPORT_PROJECT_CHOICES ||= [ + { + "vcs": "tfvc", + "tfvc_project": "project0", + "human_name": "project0 (tfs)" + }, + { + "vcs": "tfvc", + "tfvc_project": "project1", + "human_name": "project1 (tfs)" + }, + { + "vcs": "tfvc", + "tfvc_project": "project2", + "human_name": "project2 (tfs)" + }, + { + "vcs": "tfvc", + "tfvc_project": "project3", + "human_name": "project3 (tfs)" + } + ] + SOURCE_IMPORT_AUTHOR ||= { "id" => 2268557, "remote_id" => "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef", From ed233e91e27853b003bdc73b4d7dc6c0d72f699e Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 23 May 2016 14:13:50 -0700 Subject: [PATCH 12/81] Sync changes from upstream repository --- .../2016-05-23-timeline-preview-api.md | 19 +++ content/v3/issues/events.md | 16 +- content/v3/issues/timeline.md | 138 ++++++++++++++++++ layouts/sidebar.html | 3 + 4 files changed, 168 insertions(+), 8 deletions(-) create mode 100644 content/changes/2016-05-23-timeline-preview-api.md create mode 100644 content/v3/issues/timeline.md diff --git a/content/changes/2016-05-23-timeline-preview-api.md b/content/changes/2016-05-23-timeline-preview-api.md new file mode 100644 index 0000000000..2400991a20 --- /dev/null +++ b/content/changes/2016-05-23-timeline-preview-api.md @@ -0,0 +1,19 @@ +--- +title: Preview the Timeline API +author_name: nickh +--- + +We've added an API for issue timelines, which will let you fetch a list +of events from an issue or pull request timeline. + +To access [the Timeline API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.mockingbird-preview + +During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice. + +If you have any questions or feedback, please [let us know][contact]! + +[media-type]: /v3/media +[docs]: /v3/issues/timeline/ +[contact]: https://github.com/contact?form%5Bsubject%5D=Timeline+API diff --git a/content/v3/issues/events.md b/content/v3/issues/events.md index e285264f3a..2b40755155 100644 --- a/content/v3/issues/events.md +++ b/content/v3/issues/events.md @@ -6,7 +6,7 @@ title: Issue Events {:toc} -Records various events that occur around an Issue or Pull Request. This is +Records various events that occur around an issue or pull request. This is useful both for display on issue/pull request information pages and also to determine who should be notified of comments. @@ -20,7 +20,7 @@ determine who should be notified of comments.
      The API URL for fetching the event.
      actor
      -
      Always the User object that generated the event.
      +
      The User object that generated the event.
      commit_id
      The String SHA of a commit that referenced this Issue
      @@ -35,8 +35,8 @@ determine who should be notified of comments.
      The timestamp indicating when the event occurred.
      label
      -
      The Label object including 'name' and 'color' attributes. Only provided for 'labeled' - and 'unlabeled' events.
      +
      The Label object including `name` and `color` attributes. Only provided for `labeled` + and `unlabeled` events.
      assignee
      The User object which was assigned to (or unassigned from) this Issue. Only provided for 'assigned' and 'unassigned' events.
      @@ -47,12 +47,12 @@ determine who should be notified of comments. {% endif %}
      milestone
      -
      The Milestone object including a 'title' attribute. Only provided for 'milestoned' and - 'demilestoned' events.
      +
      The Milestone object including a `title` attribute. Only provided for `milestoned` and + `demilestoned` events.
      rename
      -
      An object containing rename details including 'from' and 'to' attributes. Only - provided for 'renamed' events.
      +
      An object containing rename details including `from` and `to` attributes. Only + provided for `renamed` events.
      ### Events diff --git a/content/v3/issues/timeline.md b/content/v3/issues/timeline.md new file mode 100644 index 0000000000..f0e8888505 --- /dev/null +++ b/content/v3/issues/timeline.md @@ -0,0 +1,138 @@ +--- +title: Issue Timeline +--- + +# Timeline + +{:toc} + +Records various events that occur around an issue or pull request. This is +useful both for display on issue and pull request information pages, as well as to +determine who should be notified of comments. + +### Attributes + +
      +
      id
      +
      The Integer ID of the event.
      + +
      url
      +
      The API URL for fetching the event.
      + +
      actor
      +
      The User object that generated the event.
      + +
      commit_id
      +
      The String SHA of a commit that referenced this Issue.
      + +
      event
      +
      Identifies the actual type of Event that occurred.
      + +
      created_at
      +
      The timestamp indicating when the event occurred.
      + +
      label
      +
      The Label object including `name` and `color` attributes. Only provided for `labeled` + and `unlabeled` events.
      + +
      assignee
      +
      The User object which was assigned to (or unassigned from) this Issue. Only provided for `assigned` and `unassigned` events.
      + +
      assigner
      +
      The User object that performed the assignment (or unassignment) for this Issue. Only provided for `assigned` and `unassigned` events.
      + +
      milestone
      +
      The Milestone object including a `title` attribute. Only provided for `milestoned` and + `demilestoned` events.
      + +
      source
      +
      The `id`, `actor`, and `url` for the source of a reference from +another issue. Only provided for `cross-referenced` events.
      + +
      rename
      +
      An object containing rename details including `from` and `to` attributes. Only + provided for `renamed` events.
      +
      + +### Events + +
      +
      assigned
      +
      The issue was assigned to the actor.
      + +
      closed
      +
      The issue was closed by the actor. When the commit_id is present, it + identifies the commit that closed the issue using "closes / fixes #NN" + syntax.
      + +
      commented
      +
      A comment was added to the issue.
      + +
      committed
      +
      A commit was added to the pull request's `HEAD` branch. Only +provided for pull requests.
      + +
      cross-referenced
      +
      The issue was referenced from another issue. The `source` +attribute contains the `id`, `actor`, and `url` of the reference's +source.
      + +
      demilestoned
      +
      The issue was removed from a milestone.
      + +
      head_ref_deleted
      +
      The pull request's branch was deleted.
      + +
      head_ref_restored
      +
      The pull request's branch was restored.
      + +
      labeled
      +
      A label was added to the issue.
      + +
      locked
      +
      The issue was locked by the actor.
      + +
      mentioned
      +
      The actor was @mentioned in an issue body.
      + +
      merged
      +
      The issue was merged by the actor. The `commit_id` attribute is the SHA1 of + the HEAD commit that was merged.
      + +
      milestoned
      +
      The issue was added to a milestone.
      + +
      referenced
      +
      The issue was referenced from a commit message. The `commit_id` attribute is + the commit SHA1 of where that happened.
      + +
      renamed
      +
      The issue title was changed.
      + +
      reopened
      +
      The issue was reopened by the actor.
      + +
      subscribed
      +
      The actor subscribed to receive notifications for an issue.
      + +
      unassigned
      +
      The actor was unassigned from the issue.
      + +
      unlabeled
      +
      A label was removed from the issue.
      + +
      unlocked
      +
      The issue was unlocked by the actor.
      + +
      unsubscribed
      +
      The actor unsubscribed to stop receiving notifications for an issue.
      +
      + +## List events for an issue + + GET /repos/:owner/:repo/issues/:issue_number/timeline + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:issue_event) { |h| [h] } %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index c179fd3fc7..54ebad1a7b 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -47,6 +47,9 @@

      Events
    • Labels
    • Milestones
      • + <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] > 2.6) %> +
    • Timeline
      • + <% end %>

    • <% if @item[:version] == 'dotcom' %> From f8973391327caa89cca0caa5af616372ed5e368a Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 25 May 2016 05:28:09 -0700 Subject: [PATCH 13/81] Sync changes from upstream repository --- content/v3/orgs/members.md | 2 +- content/v3/orgs/teams.md | 6 +++--- content/v3/repos/collaborators.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/v3/orgs/members.md b/content/v3/orgs/members.md index e3f8175fd4..3088bebe09 100644 --- a/content/v3/orgs/members.md +++ b/content/v3/orgs/members.md @@ -25,7 +25,7 @@ Name | Type | Description [2fa-blog]: https://github.com/blog/1614-two-factor-authentication -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} {{#tip}} diff --git a/content/v3/orgs/teams.md b/content/v3/orgs/teams.md index 1aa57d3d87..07a233bea9 100644 --- a/content/v3/orgs/teams.md +++ b/content/v3/orgs/teams.md @@ -54,7 +54,7 @@ Name | Type | Description `privacy`|`string`| The level of privacy this team should have. Can be one of:
    * `secret` - only visible to organization owners and members of this team.
    * `closed` - visible to all members of this organization.
    Default: `secret`
    {% if page.version != 'dotcom' and page.version == 2.4 %}**This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %} `permission`|`string` | **Deprecated**. The permission that new repositories will be added to the team with when none is specified. Can be one of:
    * `pull` - team members can pull, but not push to or administer newly-added repositories.
    * `push` - team members can pull and push, but not administer newly-added repositories.
    * `admin` - team members can pull, push and administer newly-added repositories.
    Default: `pull` -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} {{#tip}} @@ -129,7 +129,7 @@ Name | Type | Description `privacy`|`string`| The level of privacy this team should have. Can be one of:
    * `secret` - only visible to organization owners and members of this team.
    * `closed` - visible to all members of this organization.
    Default: `secret`
    {% if page.version != 'dotcom' and page.version == 2.4 %}**This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %} `permission`|`string` | **Deprecated**. The permission that new repositories will be added to the team with when none is specified. Can be one of:
    * `pull` - team members can pull, but not push to or administer newly-added repositories.
    * `push` - team members can pull and push, but not administer newly-added repositories.
    * `admin` - team members can pull, push and administer newly-added repositories.
    Default: `pull` -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} {{#tip}} @@ -522,7 +522,7 @@ Name | Type | Description {% endif %} -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} {{#tip}} diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index b3ddcf3de7..2f5e94b9aa 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -22,7 +22,7 @@ collaborators list. <%= headers 200, :pagination => default_pagination_rels %> <%= json(:user) { |h| [h] } %> -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} ### Alternative response with extra repository information @@ -70,7 +70,7 @@ Name | Type | Description <%= fetch_content(:optional_put_content_length) %> -{% if page.version != 'dotcom' and (page.version == 2.4 or page.version == 2.5) %} +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} {{#tip}} From 8f3dd1456bd06a559e8431604b6339150b84e2c5 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 27 May 2016 00:31:25 -0700 Subject: [PATCH 14/81] Sync changes from upstream repository --- content/v3/issues/timeline.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/v3/issues/timeline.md b/content/v3/issues/timeline.md index f0e8888505..3d7b320593 100644 --- a/content/v3/issues/timeline.md +++ b/content/v3/issues/timeline.md @@ -2,6 +2,20 @@ title: Issue Timeline --- +{{#tip}} + + + + The API to get issue timeline events is currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-05-23-timeline-preview-api/) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.mockingbird-preview + +{{/tip}} + # Timeline {:toc} From a2437803c15f1073cfb46c7285f5d221391f11ff Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 27 May 2016 02:07:36 -0700 Subject: [PATCH 15/81] Sync changes from upstream repository --- content/v3/orgs.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/v3/orgs.md b/content/v3/orgs.md index 2a44ac3291..3ba152583b 100644 --- a/content/v3/orgs.md +++ b/content/v3/orgs.md @@ -21,6 +21,8 @@ This only lists organizations that your authorization allows you to operate on i <%= headers 200, :pagination => default_pagination_rels %> <%= json(:org) { |h| [h] } %> +{% if page.version == 'dotcom' or page.version >= 2.3 %} + ## List all organizations Lists all organizations, in the order that they were created on {{ site.data.variables.product.product_name }}. @@ -42,6 +44,8 @@ Name | Type | Description <%= headers 200, :pagination => { :next => 'https://api.github.com/organizations?since=135' } %> <%= json(:org) {|h| [h] } %> +{% endif %} + ## List user organizations List [public organization memberships](https://help.github.com/articles/publicizing-or-concealing-organization-membership) for the specified user. From 905164e658843d8c870a30da0f236ca1b18e2d38 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 27 May 2016 07:16:34 -0700 Subject: [PATCH 16/81] Sync changes from upstream repository --- content/v3/oauth.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/content/v3/oauth.md b/content/v3/oauth.md index f1eef51017..62cd4711d1 100644 --- a/content/v3/oauth.md +++ b/content/v3/oauth.md @@ -6,7 +6,7 @@ title: OAuth {:toc} -OAuth2 is a protocol that lets external apps request authorization to +OAuth2 is a protocol that lets external applications request authorization to private details in a user's {{ site.data.variables.product.product_name }} account without getting their password. This is preferred over [Basic Authentication](/v3/auth#basic-authentication) because tokens can be limited to specific types of data, and can be revoked by users at any @@ -34,8 +34,8 @@ This is a description of the OAuth2 flow from 3rd party web sites. Name | Type | Description -----|------|-------------- `client_id`|`string` | **Required**. The client ID you received from GitHub when you [registered](https://github.com/settings/applications/new). -`redirect_uri`|`string` | The URL in your app where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). -`scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list of scopes for users that don't have a valid token for the app. For users who do already have a valid token for the app, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow. +`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). +`scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope. `state`|`string` | An unguessable random string. It is used to protect against cross-site request forgery attacks. `allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. @@ -57,7 +57,7 @@ Name | Type | Description `client_id`|`string` | **Required**. The client ID you received from GitHub when you [registered](https://github.com/settings/applications/new). `client_secret`|`string` | **Required**. The client secret you received from GitHub when you [registered](https://github.com/settings/applications/new). `code`|`string` | **Required**. The code you received as a response to [Step 1](#1-redirect-users-to-request-github-access). -`redirect_uri`|`string` | The URL in your app where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). +`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). `state`|`string` | The unguessable random string you optionally provided in [Step 1](#1-redirect-users-to-request-github-access). ### Response @@ -79,6 +79,19 @@ header: e72e16c7e42f292c6912e7710c838347ae178b4a +#### Multiple tokens + +GitHub allows multiple tokens to exist for a user/application/scope combination. +This can be used to create tokens for specific use cases. For example, your +application might support one workflow that uses GitHub for sign in, and only +requires basic user information. And, your application might support a different +workflow that requires access to a user's private repositories. Using multiple +tokens, your application can perform the web flow for each use case, requesting +only the scopes needed. If a user only uses your application to sign in, they +are never required to grant your application access to their private +repositories. Note, there is a limit to the number of tokens that are issued per +user/application/scope combination. If your application requests enough tokens +to go over one of the limits, older tokens will stop working. #### Requested scopes vs. granted scopes @@ -319,7 +332,7 @@ and get a new code. Users can review and revoke their application authorizations from the [settings screen within GitHub][authorized-apps]. A user's organizations [control whether an application can access organization data][org-app-policies]. Integrators can -deep link to the authorization information for their particular app to let their +deep link to the authorization information for their particular application to let their end users review these details. To build this link, you'll need your OAuth application's `client_id` you From e0d08feb2f3a17379a0572bccd56df10df37785a Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 27 May 2016 10:01:08 -0700 Subject: [PATCH 17/81] Sync changes from upstream repository --- .../changes/2016-5-27-multiple-assignees.md | 23 ++++++ content/v3/issues.md | 71 +++++++++++++++++++ content/v3/issues/assignees.md | 59 +++++++++++++++ lib/responses/issues_and_prs.rb | 7 ++ 4 files changed, 160 insertions(+) create mode 100644 content/changes/2016-5-27-multiple-assignees.md diff --git a/content/changes/2016-5-27-multiple-assignees.md b/content/changes/2016-5-27-multiple-assignees.md new file mode 100644 index 0000000000..a9646fc5c2 --- /dev/null +++ b/content/changes/2016-5-27-multiple-assignees.md @@ -0,0 +1,23 @@ +--- +title: API changes for Multiple Issue Assignees +author_name: nakajima +--- +GitHub recently added the ability to assign up to ten people to issues. We're updating Issue payloads and adding a couple new endpoints to help you build apps. You can enable these changes during the preview period by providing a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.cerberus-preview + +For example: + +``` command-line +curl "https://api.github.com/repos/github/hubot/issues" \ + -H 'Authorization: token TOKEN' \ + -H "Accept: application/vnd.github.cerberus-preview" \ +``` + +The issues returned in this list will include the new `assignees` key. + +You can learn more about the new responses and endpoints in the updated [Issues][issues] and [Issue Assignees][issue-assignees] documentation + +[media-type]: /v3/media +[issues]: /v3/issues +[issue-assignees]: /v3/issues/assignees diff --git a/content/v3/issues.md b/content/v3/issues.md index 63f3f65a22..dbc5f8ef7b 100644 --- a/content/v3/issues.md +++ b/content/v3/issues.md @@ -162,6 +162,23 @@ Name | Type | Description `assignee`|`string` | Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise._ `milestone`|`integer` | The `number` of the milestone to associate this issue with. _NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. _NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise._ +`assignees`|`array` of `strings` | Logins for Users to assign to this issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ + +{{#tip}} + + + +The `assignees` parameter is currently available for developers to preview. +During the preview period, the API may change without advance notice. +Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + +To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview+json + +The `assignees` key will only be accepted in issue payloads if this header is passed. + +{{/tip}} #### Example @@ -178,6 +195,25 @@ Name | Type | Description <%= headers 201, :Location => get_resource(:full_issue)['url'] %> <%= json :full_issue %> +{% if page.version == 'dotcom' %} +#### Multiple Assignees + +{{#tip}} + + + + An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview + + The `assignees` key will be an Array of Users who are assigned to the issue. + +{{/tip}} +{% endif %} + ## Edit an issue Issue owners and users with push access can edit an issue. @@ -194,7 +230,23 @@ Name | Type | Description `state`|`string` | State of the issue. Either `open` or `closed`. `milestone`|`integer` | The `number` of the milestone to associate this issue with or `null` to remove current. _NOTE: Only users with push access can set the milestone for issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. Pass one or more Labels to _replace_ the set of Labels on this Issue. Send an empty array (`[]`) to clear all Labels from the Issue. _NOTE: Only users with push access can set labels for issues. Labels are silently dropped otherwise._ +`assignees`|`array` of `strings` | Logins for Users to assign to this issue. Pass one or more user logins to _replace_ the set of assignees on this Issue. .Send an empty array (`[]`) to clear all assignees from the Issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ +{{#tip}} + + + +The `assignees` parameter is currently available for developers to preview. +During the preview period, the API may change without advance notice. +Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + +To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview+json + +The `assignees` key will only be present in issue payloads if this header is passed. + +{{/tip}} #### Example @@ -212,6 +264,25 @@ Name | Type | Description <%= headers 200 %> <%= json :full_issue %> +{% if page.version == 'dotcom' %} +#### Multiple Assignees + +{{#tip}} + + + + An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview + + The `assignees` key will be an Array of Users who are assigned to the issue. + +{{/tip}} +{% endif %} + {% if page.version == 'dotcom' %} ## Lock an issue diff --git a/content/v3/issues/assignees.md b/content/v3/issues/assignees.md index 8a48cdb867..e6e1f8927f 100644 --- a/content/v3/issues/assignees.md +++ b/content/v3/issues/assignees.md @@ -35,3 +35,62 @@ Otherwise a `404` status code is returned. <%= headers 404 %> [available assignees]: https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/ + +## Add assignees to an Issue + +{{#tip}} + + + +This endpoint is currently available for developers to preview. +During the preview period, the API may change without advance notice. +Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + +To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview+json + +{{/tip}} + + +This call adds the users passed in the `assignees` key (as their logins) to the issue. + + POST /repos/:owner/:repo/issues/:number/assignees + +### Input + +<%= json({"assignees" => %w(hubot other_assignee)}) %> + +### Response + +<%= headers 201 %> +<%= json(:issue_with_assignees) { |h| [h] } %> + +## Remove assignees from an Issue + +{{#tip}} + + + +This endpoint is currently available for developers to preview. +During the preview period, the API may change without advance notice. +Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. + +To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.cerberus-preview+json + +{{/tip}} + +This call removes the users passed in the `assignees` key (as their logins) from the issue. + + DELETE /repos/:owner/:repo/issues/:number/assignees + +### Input + +<%= json({"assignees" => %w(hubot other_assignee)}) %> + +### Response + +<%= headers 200 %> +<%= json(:issue_with_assignees) { |h| [h] } %> diff --git a/lib/responses/issues_and_prs.rb b/lib/responses/issues_and_prs.rb index 897e4d8cb8..d955cb1744 100644 --- a/lib/responses/issues_and_prs.rb +++ b/lib/responses/issues_and_prs.rb @@ -133,6 +133,13 @@ module Responses "closed_by" => USER }) + ISSUE_WITH_ASSIGNEES ||= ISSUE.merge({ + "assignees" => [ + USER.merge("login" => "hubot"), + USER.merge("login" => "other_user") + ] + }) + ISSUE_COMMENT ||= { "id" => 1, "url" => "https://api.github.com/repos/octocat/Hello-World/issues/comments/1", From caa977f704af87c5e474f6c498556f749b179385 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 2 Jun 2016 07:38:51 -0700 Subject: [PATCH 18/81] Sync changes from upstream repository --- content/v3/git/commits.md | 31 +++++++++++++++++++++++++++++++ content/v3/git/tags.md | 30 ++++++++++++++++++++++++++++++ content/v3/repos/commits.md | 31 +++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+) diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md index 3287363520..8b6a43bcd0 100644 --- a/content/v3/git/commits.md +++ b/content/v3/git/commits.md @@ -83,4 +83,35 @@ To receive signature verification data in commit objects you must provide a cust <%= headers 200 %> <%= json(:signed_git_commit) %> +### The `verification` object + +The response will include a `verification` field whose value is an object describing the result of verifying the commit's signature. The following fields are included in the `verification` object: + +Name | Type | Description +-----|------|-------------- +`verified`|`boolean` | Does GitHub consider the signature in this commit to be verified? +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`signature`|`string` | The signature that was extracted from the commit. +`payload`|`string` | The value that was signed. + +#### The `reason` field + +The following are possible `reason`s that may be included in the `verification` object: + +Value | Description +------|------------ +`expired_key` | The key that made the signature is expired. +`not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. +`gpgverify_error` | There was an error communicating with the signature-verification service. +`gpgverify_unavailable` | The signature-verification service is currently unavailable. +`unsigned` | The object does not include a signature. +`unkown_signature_type` | A non-PGP signature was found in the commit. +`no_user` | No user was associated with the `committer` email address in the commit. +`unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account. +`bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. +`unknown_key` | The key that made the signature has not been registered with any user's account. +`malformed_signature` | There was an error parsing the signature. +`invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. +`valid` | None of the above errors applied, so the signature is considered to be verified. + {% endif %} diff --git a/content/v3/git/tags.md b/content/v3/git/tags.md index e19e4d6613..42ce97eca8 100644 --- a/content/v3/git/tags.md +++ b/content/v3/git/tags.md @@ -87,5 +87,35 @@ To receive signature verification data in tag objects you must provide a custom <%= headers 200 %> <%= json(:signed_gittag) %> +### The `verification` object + +The response will include a `verification` field whose value is an object describing the result of verifying the tag's signature. The following fields are included in the `verification` object: + +Name | Type | Description +-----|------|-------------- +`verified`|`boolean` | Does GitHub consider the signature in this tag to be verified? +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`signature`|`string` | The signature that was extracted from the tag. +`payload`|`string` | The value that was signed. + +#### The `reason` field + +The following are possible `reason`s that may be included in the `verification` object: + +Value | Description +------|------------ +`expired_key` | The key that made the signature is expired. +`not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. +`gpgverify_error` | There was an error communicating with the signature-verification service. +`gpgverify_unavailable` | The signature-verification service is currently unavailable. +`unsigned` | The object does not include a signature. +`unkown_signature_type` | A non-PGP signature was found in the tag. +`no_user` | No user was associated with the `tagger` email address in the tag. +`unverified_email` | The `tagger` email address in the tag was associated with a user, but the email address is not verified on her/his account. +`bad_email` | The `tagger` email address in the tag is not included in the identities of the PGP key that made the signature. +`unknown_key` | The key that made the signature has not been registered with any user's account. +`malformed_signature` | There was an error parsing the signature. +`invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. +`valid` | None of the above errors applied, so the signature is considered to be verified. {% endif %} diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md index 80368b7deb..7c5020a242 100644 --- a/content/v3/repos/commits.md +++ b/content/v3/repos/commits.md @@ -109,4 +109,35 @@ To receive signature verification data in commit objects you must provide a cust <%= headers 200 %> <%= json(:signed_commit) %> +### The `verification` object + +The response will include a `verification` field whose value is an object describing the result of verifying the commit's signature. The following fields are included in the `verification` object: + +Name | Type | Description +-----|------|-------------- +`verified`|`boolean` | Does GitHub consider the signature in this commit to be verified? +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`signature`|`string` | The signature that was extracted from the commit. +`payload`|`string` | The value that was signed. + +#### The `reason` field + +The following are possible `reason`s that may be included in the `verification` object: + +Value | Description +------|------------ +`expired_key` | The key that made the signature is expired. +`not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. +`gpgverify_error` | There was an error communicating with the signature-verification service. +`gpgverify_unavailable` | The signature-verification service is currently unavailable. +`unsigned` | The object does not include a signature. +`unkown_signature_type` | A non-PGP signature was found in the commit. +`no_user` | No user was associated with the `committer` email address in the commit. +`unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account. +`bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. +`unknown_key` | The key that made the signature has not been registered with any user's account. +`malformed_signature` | There was an error parsing the signature. +`invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. +`valid` | None of the above errors applied, so the signature is considered to be verified. + {% endif %} From 94a7e9a244ca3efde9a476176026610b04e8b5a9 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 2 Jun 2016 12:17:56 -0700 Subject: [PATCH 19/81] Sync changes from upstream repository --- CONTRIBUTING.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63fd16f7f0..f06489cd3c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,68 @@ -Found a typo? Have an idea for improving the docs? Feel free to open a pull request and we'll get it merged as soon as we can! +# Contributing to this repository -If you have a specific question or issues with the API, please [let us know](https://github.com/contact). +Use this repository to: -## Do you work at GitHub? +- Report bugs in the documentation. +- Propose minor updates to content such as typo fixes or clarifications. -If you're a GitHub employee, please take a look at [our GitHubber article](https://githubber.com/article/crafts/writing/everything-you-need-to-know-about-the-Developer-blog) for more specific information on contributing. +If you have a specific question or issues with the API, please [let us know by contacing GitHub Support](https://github.com/contact). + +## API Reference Style Guide + +The API reference refers to most of the content under . The format of these pages is consistent: + +- Endpoints are introduced with an `h2` that describes the API. + + For example: `## List issues for a repository` + +- The endpoint itself is wrapped in a codeblock. Capitalize the HTTP verb followed by the endpoint URL. + + For example: `GET /repos/:owner/:repo/issues` + +- Introduce the parameters with an `h3`. + + For example: `### Parameters`. + +- Write a table with three columns that describes any parameters. The three column headings are: + - `Name`, which identifies the name of the parameter. + - `Type`, which identifies the type of the parameter. + - `Description`, which describes the parameter. Start the description with the phrase **Required.** if it's required. If it's an optional parameter, end the description by listing the default value, if any. +- Provide the endpoint's response. Responses are stored in the _lib/responses_ folder. + +Optionally, you may choose to include an example. Examples should be introduced with an `h3`, and should occur after the parameters are introduced and before the response. + +## Platform Guides + +Platform Guides refer to the content under . They are longer form content that solve a specific problem for the reader. Each guide follows a three-section pattern: + +- An introduction stating any minimum requirements, such as installed dependencies, as well as a description of the problem to solve. +- A body that breaks down the solution to the problem with clear guidelines. Include code samples that are preceded with how the sample could be used. +- A conclusion that summarizes that guide and offers next steps for any advanced topics. + +Please submit the full sample code for a guide to . + +## Versioning content + +Our documentation is single sourced and versioned to also apply to GitHub Enterprise users. We use [Liquid tags](https://help.shopify.com/themes/liquid/basics#tags) to include or exclude content for various builds. + +Each GitHub Enterprise release represent a "point in time" for the GitHub.com design and feature set. As a result, the APIs available on GitHub Enterprise are also the same APIs available on GitHub.com at the point when the new version was created. For example, if GitHub Enterprise 2.5 was released on December 15th, the APIs available to users are the same as whatever was available on December 15th. 2.5.x patch releases might introduce bug fixes and updates, but will rarely, if ever, contain brand new API endpoints. + +When writing API documentation, we filter sections meant just for GitHub.com using Liquid tags, like this: + +``` +{% if page.version == 'dotcom' %} + +You need to use an HTTP client which supports... + +{% endif %} +``` + +Similarly, content for GitHub Enterprise is versioned based on the release number, like this: + +``` +{% if page.version != 'dotcom' and page.version >= 2.2 %} + +If your GitHub Enterprise appliance has LDAP Sync enabled... + +{% endif %} +``` From fec818ec4aa0976be79eadb84d36cdf95f0504e0 Mon Sep 17 00:00:00 2001 From: Hubot Date: Sat, 4 Jun 2016 17:45:54 -0700 Subject: [PATCH 20/81] Sync changes from upstream repository --- content/v3.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/content/v3.md b/content/v3.md index 916d387e63..d73a059c18 100644 --- a/content/v3.md +++ b/content/v3.md @@ -482,9 +482,19 @@ $ curl -iH 'User-Agent: ' {{ site.data.variables.product.api_url_pre }}/meta Most responses return an `ETag` header. Many responses also return a `Last-Modified` header. You can use the values of these headers to make subsequent requests to those resources using the `If-None-Match` and `If-Modified-Since` headers, respectively. If the resource -has not changed, the server will return a `304 Not Modified`. Also note: making -a conditional request and receiving a 304 response does not count against your -[Rate Limit](#rate-limiting), so we encourage you to use it whenever possible. +has not changed, the server will return a `304 Not Modified`. + +{% if page.version == 'dotcom' %} + +{{#tip}} + +**Note**: Making a conditional request and receiving a 304 response does not +count against your [Rate Limit](#rate-limiting), so we encourage you to use it +whenever possible. + +{{/tip}} + +{% endif %} ``` command-line $ curl -i {{ site.data.variables.product.api_url_pre }}/user From 3f40d00c588e90bb879726a2d03372098e29b5b3 Mon Sep 17 00:00:00 2001 From: Brendan Forster Date: Tue, 7 Jun 2016 09:30:31 +0200 Subject: [PATCH 21/81] correct Accept media type to remove sha suffix --- content/v3/git/commits.md | 2 +- content/v3/git/tags.md | 2 +- content/v3/repos/commits.md | 2 +- content/v3/users/gpg_keys.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md index 8b6a43bcd0..2f1a35036a 100644 --- a/content/v3/git/commits.md +++ b/content/v3/git/commits.md @@ -72,7 +72,7 @@ Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full To receive signature verification data in commit objects you must provide a custom [media type](/v3/media) in the `Accept` header: - application/vnd.github.cryptographer-preview+sha + application/vnd.github.cryptographer-preview {{/tip}} diff --git a/content/v3/git/tags.md b/content/v3/git/tags.md index 42ce97eca8..6a56694a48 100644 --- a/content/v3/git/tags.md +++ b/content/v3/git/tags.md @@ -76,7 +76,7 @@ Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full To receive signature verification data in tag objects you must provide a custom [media type](/v3/media) in the `Accept` header: - application/vnd.github.cryptographer-preview+sha + application/vnd.github.cryptographer-preview {{/tip}} diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md index 7c5020a242..a9fbac3e40 100644 --- a/content/v3/repos/commits.md +++ b/content/v3/repos/commits.md @@ -98,7 +98,7 @@ Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full To receive signature verification data in commit objects you must provide a custom [media type](/v3/media) in the `Accept` header: - application/vnd.github.cryptographer-preview+sha + application/vnd.github.cryptographer-preview {{/tip}} diff --git a/content/v3/users/gpg_keys.md b/content/v3/users/gpg_keys.md index 935f7ecab3..448737dc56 100644 --- a/content/v3/users/gpg_keys.md +++ b/content/v3/users/gpg_keys.md @@ -16,7 +16,7 @@ title: User GPG Keys To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - application/vnd.github.cryptographer-preview+sha + application/vnd.github.cryptographer-preview {{/tip}} From d9b855c457597d6e0c1be743d99710c38b3a44a1 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 7 Jun 2016 14:59:08 -0700 Subject: [PATCH 22/81] Sync changes from upstream repository --- .../2016-06-07-reactions-api-update.md | 46 +++++++++++++++++++ lib/responses/reactions.rb | 4 +- 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 content/changes/2016-06-07-reactions-api-update.md diff --git a/content/changes/2016-06-07-reactions-api-update.md b/content/changes/2016-06-07-reactions-api-update.md new file mode 100644 index 0000000000..ea6f17bb45 --- /dev/null +++ b/content/changes/2016-06-07-reactions-api-update.md @@ -0,0 +1,46 @@ +--- +title: Reactions API Preview now includes user information +author_name: kneemer +--- + +To avoid making extra API calls, we've updated the [Reactions API preview][initial-reaction-api-post] to include additional user information when listing Reactions. + +**This is a breaking change for Reaction payloads**. If you're trying out this new API during its preview period, you'll need to update your code to continue working with it. + +## JSON Payload Changes + +We're replacing the `user_id` attribute with `user` and changing the schema type from a number to a JSON object. + +## Example Reaction JSON +```json +[ + { + "id": 1, + "user": { + "login": "octocat", + "id": 1, + "avatar_url": "https://github.com/images/error/octocat_happy.gif", + "gravatar_id": "", + "url": "https://api.github.com/users/octocat", + "html_url": "https://github.com/octocat", + "followers_url": "https://api.github.com/users/octocat/followers", + "following_url": "https://api.github.com/users/octocat/following{/other_user}", + "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", + "organizations_url": "https://api.github.com/users/octocat/orgs", + "repos_url": "https://api.github.com/users/octocat/repos", + "events_url": "https://api.github.com/users/octocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/octocat/received_events", + "type": "User", + "site_admin": false + }, + "content": "heart" + } +] +``` + +As always, if you have any questions or feedback, please [get in touch][contact]. + +[initial-reaction-api-post]: /changes/2016-05-12-reactions-api-preview +[contact]: https://github.com/contact?form%5Bsubject%5D=Reactions+API+Preview diff --git a/lib/responses/reactions.rb b/lib/responses/reactions.rb index cdef1d59fd..b0af2ddd69 100644 --- a/lib/responses/reactions.rb +++ b/lib/responses/reactions.rb @@ -1,9 +1,11 @@ +require_relative 'user' + module GitHub module Resources module Responses REACTION ||= { "id": 1, - "user_id": 1, + "user" => USER, "content": "heart" } From 67ab105915e4ee11b7a723e736d9b02d472da520 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 7 Jun 2016 15:59:15 -0700 Subject: [PATCH 23/81] Sync changes from upstream repository --- .../2016-06-07-reactions-api-update.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/content/changes/2016-06-07-reactions-api-update.md b/content/changes/2016-06-07-reactions-api-update.md index ea6f17bb45..017d189394 100644 --- a/content/changes/2016-06-07-reactions-api-update.md +++ b/content/changes/2016-06-07-reactions-api-update.md @@ -16,26 +16,26 @@ We're replacing the `user_id` attribute with `user` and changing the schema type [ { "id": 1, - "user": { - "login": "octocat", - "id": 1, - "avatar_url": "https://github.com/images/error/octocat_happy.gif", - "gravatar_id": "", - "url": "https://api.github.com/users/octocat", - "html_url": "https://github.com/octocat", - "followers_url": "https://api.github.com/users/octocat/followers", - "following_url": "https://api.github.com/users/octocat/following{/other_user}", - "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", - "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", - "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", - "organizations_url": "https://api.github.com/users/octocat/orgs", - "repos_url": "https://api.github.com/users/octocat/repos", - "events_url": "https://api.github.com/users/octocat/events{/privacy}", - "received_events_url": "https://api.github.com/users/octocat/received_events", - "type": "User", - "site_admin": false - }, - "content": "heart" + "user": { + "login": "octocat", + "id": 1, + "avatar_url": "https://github.com/images/error/octocat_happy.gif", + "gravatar_id": "", + "url": "https://api.github.com/users/octocat", + "html_url": "https://github.com/octocat", + "followers_url": "https://api.github.com/users/octocat/followers", + "following_url": "https://api.github.com/users/octocat/following{/other_user}", + "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", + "organizations_url": "https://api.github.com/users/octocat/orgs", + "repos_url": "https://api.github.com/users/octocat/repos", + "events_url": "https://api.github.com/users/octocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/octocat/received_events", + "type": "User", + "site_admin": false + }, + "content": "heart" } ] ``` From 767476678421e4a13bfb25e1d832f3d7b4f626f4 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 8 Jun 2016 10:01:53 -0700 Subject: [PATCH 24/81] Sync changes from upstream repository --- lib/responses/reactions.rb | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/lib/responses/reactions.rb b/lib/responses/reactions.rb index b0af2ddd69..7dfe78f88e 100644 --- a/lib/responses/reactions.rb +++ b/lib/responses/reactions.rb @@ -4,19 +4,20 @@ module GitHub module Resources module Responses REACTION ||= { - "id": 1, + "id" => 1, "user" => USER, - "content": "heart" + "content" => "heart", + "created_at" => "2016-05-20T20:09:31Z" } REACTION_SUMMARY ||= { - "total_count": 5, - "+1": 3, - "-1": 1, - "laugh": 0, - "confused": 0, - "heart": 1, - "hooray": 0 + "total_count" => 5, + "+1" => 3, + "-1" => 1, + "laugh" => 0, + "confused" => 0, + "heart" => 1, + "hooray" => 0 } end end From 6c4859d70308493281f0835343a9b755f19f706c Mon Sep 17 00:00:00 2001 From: Jakub Wilk Date: Thu, 9 Jun 2016 23:10:34 +0200 Subject: [PATCH 25/81] Fix typos --- content/changes/2012-11-29-gitignore-templates.html | 2 +- content/changes/2014-04-22-deprecating-beta-media-type.md | 2 +- .../changes/2014-10-21-deployment-webhook-payload-changes.md | 2 +- content/changes/2014-10-24-status-api-limits.md | 2 +- content/changes/2014-12-08-removing-authorizations-token.md | 4 ++-- content/changes/2015-06-24-licenses-api-update.md | 2 +- content/guides/delivering-deployments.md | 2 +- content/guides/traversing-with-pagination.md | 2 +- content/v3/gists.md | 2 +- content/v3/git/commits.md | 2 +- content/v3/git/tags.md | 2 +- content/v3/migration/source_imports.md | 2 +- content/v3/repos/commits.md | 2 +- content/v3/repos/hooks.md | 2 +- 14 files changed, 15 insertions(+), 15 deletions(-) diff --git a/content/changes/2012-11-29-gitignore-templates.html b/content/changes/2012-11-29-gitignore-templates.html index 46cb7574aa..d88d39b88f 100644 --- a/content/changes/2012-11-29-gitignore-templates.html +++ b/content/changes/2012-11-29-gitignore-templates.html @@ -6,7 +6,7 @@ We recently [made it easy][init-post] to initialize a repository when you create it [via the API][repo-create]. One of the options you can pass when creating a repository is `gitignore_template`. This value is the name of one of the -templates from the the public [GitHub .gitignore repository][templates-repo]. +templates from the public [GitHub .gitignore repository][templates-repo]. The [Gitignore Templates API][new-api] makes it easy to list those templates: diff --git a/content/changes/2014-04-22-deprecating-beta-media-type.md b/content/changes/2014-04-22-deprecating-beta-media-type.md index 94137ccf9c..e212e5ae0e 100644 --- a/content/changes/2014-04-22-deprecating-beta-media-type.md +++ b/content/changes/2014-04-22-deprecating-beta-media-type.md @@ -5,7 +5,7 @@ author_name: jasonrudolph Now that the GitHub API is [serving the v3 media type by default][v3-default], we are deprecating the legacy [beta media type][beta]. -We will eventually remove support for the beta media type, but we have no official retirement date to annouce at the moment. When the time comes, rest assured that we'll announce the retirement with plenty of notice. In the meantime, existing API clients that rely on the beta media type should start making plans to migrate to v3. The beta media type differs from v3 in [just a few places][differences]. In most cases, migrating an application from the beta media type to the v3 media type is smooth and painless. +We will eventually remove support for the beta media type, but we have no official retirement date to announce at the moment. When the time comes, rest assured that we'll announce the retirement with plenty of notice. In the meantime, existing API clients that rely on the beta media type should start making plans to migrate to v3. The beta media type differs from v3 in [just a few places][differences]. In most cases, migrating an application from the beta media type to the v3 media type is smooth and painless. As always, if you have any questions, please [get in touch][contact]. diff --git a/content/changes/2014-10-21-deployment-webhook-payload-changes.md b/content/changes/2014-10-21-deployment-webhook-payload-changes.md index b982566a20..e74d85137c 100644 --- a/content/changes/2014-10-21-deployment-webhook-payload-changes.md +++ b/content/changes/2014-10-21-deployment-webhook-payload-changes.md @@ -3,7 +3,7 @@ title: Deployment webhook payload changes author_name: atmos --- -On November 4th, 2014, we will begin sending a new format for [deployment][1] and [deployment status][2] payloads for webhooks. In the meantime we'll be running in a compatability mode that will give integrators the time needed to start taking advantage of the new format. Integrators who are working with webhooks and deployments are advised to upgrade to the new payload format to avoid service interruption. +On November 4th, 2014, we will begin sending a new format for [deployment][1] and [deployment status][2] payloads for webhooks. In the meantime we'll be running in a compatibility mode that will give integrators the time needed to start taking advantage of the new format. Integrators who are working with webhooks and deployments are advised to upgrade to the new payload format to avoid service interruption. This change brings the payloads for these events more inline with the responses you'd receive from the API. Instead of having deployment and deployment status attributes as top-level keys, we will now nest them under `deployment` and `deployment_status` keys. Since we're still in the [preview period][3] for the deployments API we felt it was best to correct this inconsistency now. diff --git a/content/changes/2014-10-24-status-api-limits.md b/content/changes/2014-10-24-status-api-limits.md index d748a17565..c58ae0ebe4 100644 --- a/content/changes/2014-10-24-status-api-limits.md +++ b/content/changes/2014-10-24-status-api-limits.md @@ -9,7 +9,7 @@ to 1000 per commit SHA, repository, and context. Beginning Monday, November 3rd, we will trim existing data sets that exceed this limit, deleting the oldest records first. Attempts to create statuses beyond that limit will result in a [validation error]. -If you have any feedback or questions, please don't hesistate to [contact] us. +If you have any feedback or questions, please don't hesitate to [contact] us. [statuses]: /v3/repos/statuses/ [validation error]: https://developer.github.com/v3/#client-errors diff --git a/content/changes/2014-12-08-removing-authorizations-token.md b/content/changes/2014-12-08-removing-authorizations-token.md index a5fb8002ac..994fe04884 100644 --- a/content/changes/2014-12-08-removing-authorizations-token.md +++ b/content/changes/2014-12-08-removing-authorizations-token.md @@ -5,7 +5,7 @@ author_name: ptoomey3 Since OAuth access tokens function like passwords, they should be treated with care. Today we are making it easier to more securely work with authorizations -via the Authorizations API. We are deprecating the use use of the `token` +via the Authorizations API. We are deprecating the use of the `token` attribute in the majority of the [Authorizations API](/v3/oauth_authorizations/) responses. For the [affected APIs][authorizations-token-deprecation-notice], the `token` attribute will soon return an empty string. To get ready for that @@ -60,7 +60,7 @@ for the same client ID and user. [OAuth applications listing on GitHub][app-listing]. * [Get-or-create an authorization for a specific app and fingerprint][get-or-create-for-app-fingerprint] -is a new API that is analagous to the +is a new API that is analogous to the [Get-or-create an authorization for a specific app][get-or-create-for-app] API, but adds support for the new `fingerprint` request parameter. diff --git a/content/changes/2015-06-24-licenses-api-update.md b/content/changes/2015-06-24-licenses-api-update.md index 67c7ffaded..26f5b340d3 100644 --- a/content/changes/2015-06-24-licenses-api-update.md +++ b/content/changes/2015-06-24-licenses-api-update.md @@ -9,7 +9,7 @@ Before, license information was only returned for an individual repository: GET /repos/github/hubot -Now, license information will also be included in reponses from endpoints that list multiple repositories, such as [List organization repositories](/v3/repos/#list-organization-repositories): +Now, license information will also be included in responses from endpoints that list multiple repositories, such as [List organization repositories](/v3/repos/#list-organization-repositories): GET /orgs/github/repos diff --git a/content/guides/delivering-deployments.md b/content/guides/delivering-deployments.md index 7ddb32df8a..218cadfd9b 100644 --- a/content/guides/delivering-deployments.md +++ b/content/guides/delivering-deployments.md @@ -125,7 +125,7 @@ Deployments can have some metadata attached to them, in the form of a `payload` and a `description`. Although these values are optional, it's helpful to use for logging and representing information. -When a new deployment is created, a completely separate event is trigged. That's +When a new deployment is created, a completely separate event is triggered. That's why we have a new `switch` case in the event handler for `deployment`. You can use this information to be notified when a deployment has been triggered. diff --git a/content/guides/traversing-with-pagination.md b/content/guides/traversing-with-pagination.md index 498f9b2c82..ff4d11cf0b 100644 --- a/content/guides/traversing-with-pagination.md +++ b/content/guides/traversing-with-pagination.md @@ -241,7 +241,7 @@ clicked_results = client.search_code('addClass user:mozilla', :page => random_pa ``` If we wanted to get fancy, we could also grab the previous and next pages, in -order to generate links for back (`<<`) and foward (`>>`) elements: +order to generate links for back (`<<`) and forward (`>>`) elements: ``` ruby prev_page_href = client.last_response.rels[:prev] ? client.last_response.rels[:prev].href : "(none)" diff --git a/content/v3/gists.md b/content/v3/gists.md index 127940e465..1038a72acb 100644 --- a/content/v3/gists.md +++ b/content/v3/gists.md @@ -20,7 +20,7 @@ The Gist API provides up to one megabyte of content for each file in the gist. E If you need the full contents of the file, you can make a `GET` request to the URL specified by `raw_url`. Be aware that for files larger than ten megabytes, you'll need to clone the gist via the URL provided by `git_pull_url`. -In addition to a specific file's contents being truncated, the entire files list may be trucated if the total number exceeds 300 files. If the top level `truncated` key is `true`, only the first 300 files have been returned in the files list. If you need to fetch all of the gist's files, you'll need to clone the gist via the URL provided by `git_pull_url`. +In addition to a specific file's contents being truncated, the entire files list may be truncated if the total number exceeds 300 files. If the top level `truncated` key is `true`, only the first 300 files have been returned in the files list. If you need to fetch all of the gist's files, you'll need to clone the gist via the URL provided by `git_pull_url`. ## List a user's gists diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md index 8b6a43bcd0..e26e272085 100644 --- a/content/v3/git/commits.md +++ b/content/v3/git/commits.md @@ -90,7 +90,7 @@ The response will include a `verification` field whose value is an object descri Name | Type | Description -----|------|-------------- `verified`|`boolean` | Does GitHub consider the signature in this commit to be verified? -`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table below. `signature`|`string` | The signature that was extracted from the commit. `payload`|`string` | The value that was signed. diff --git a/content/v3/git/tags.md b/content/v3/git/tags.md index 42ce97eca8..5b98a0dd3f 100644 --- a/content/v3/git/tags.md +++ b/content/v3/git/tags.md @@ -94,7 +94,7 @@ The response will include a `verification` field whose value is an object descri Name | Type | Description -----|------|-------------- `verified`|`boolean` | Does GitHub consider the signature in this tag to be verified? -`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table below. `signature`|`string` | The signature that was extracted from the tag. `payload`|`string` | The value that was signed. diff --git a/content/v3/migration/source_imports.md b/content/v3/migration/source_imports.md index 48b778ea0c..044cc0079e 100644 --- a/content/v3/migration/source_imports.md +++ b/content/v3/migration/source_imports.md @@ -175,7 +175,7 @@ This section includes details about Git LFS related fields that may be present i * `use_lfs` - describes whether the import has been opted in or out of using Git LFS. The value can be `opt_in`, `opt_out`, or `undecided` if no action has been taken. * `has_large_files` - the boolean value describing whether files larger than 100MB were found during the `importing` step. * `large_files_size` - the total size in gigabytes of files larger than 100MB found in the originating repository. -* `large_files_count` - the total number of of files larger than 100MB found in the originating repository. To see a list of these files, make a "Get Large Files" request. +* `large_files_count` - the total number of files larger than 100MB found in the originating repository. To see a list of these files, make a "Get Large Files" request. ## Update existing import diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md index 7c5020a242..7c7fe281ca 100644 --- a/content/v3/repos/commits.md +++ b/content/v3/repos/commits.md @@ -116,7 +116,7 @@ The response will include a `verification` field whose value is an object descri Name | Type | Description -----|------|-------------- `verified`|`boolean` | Does GitHub consider the signature in this commit to be verified? -`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table bellow. +`reason`|`string` | The reason for `verified` value. Possible values and their meanings are enumerated in the table below. `signature`|`string` | The signature that was extracted from the commit. `payload`|`string` | The value that was signed. diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md index 5df7278423..2208924598 100644 --- a/content/v3/repos/hooks.md +++ b/content/v3/repos/hooks.md @@ -10,7 +10,7 @@ The Repository Webhooks API allows repository admins to manage the post-receive hooks for a repository. Webhooks can be managed using the JSON HTTP API, or the [PubSubHubbub API](#pubsubhubbub). -If you would like to set up a single webhook to receive events from all of your organization's respositories, check out our [API documentation for Organization Webhooks][org-hooks]. +If you would like to set up a single webhook to receive events from all of your organization's repositories, check out our [API documentation for Organization Webhooks][org-hooks]. ## List hooks From dcffd34435d9d48b2bd84ba629072948c6c0e06d Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 9 Jun 2016 16:26:38 -0700 Subject: [PATCH 26/81] Sync changes from upstream repository --- content/v3/issues/timeline.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/v3/issues/timeline.md b/content/v3/issues/timeline.md index 3d7b320593..c1ba039e0e 100644 --- a/content/v3/issues/timeline.md +++ b/content/v3/issues/timeline.md @@ -52,9 +52,6 @@ determine who should be notified of comments.
    assignee
    The User object which was assigned to (or unassigned from) this Issue. Only provided for `assigned` and `unassigned` events.
    -
    assigner
    -
    The User object that performed the assignment (or unassignment) for this Issue. Only provided for `assigned` and `unassigned` events.
    -
    milestone
    The Milestone object including a `title` attribute. Only provided for `milestoned` and `demilestoned` events.
    @@ -72,7 +69,7 @@ another issue. Only provided for `cross-referenced` events.
    assigned
    -
    The issue was assigned to the actor.
    +
    The issue was assigned to the assignee.
    closed
    The issue was closed by the actor. When the commit_id is present, it @@ -130,7 +127,7 @@ source.
    The actor subscribed to receive notifications for an issue.
    unassigned
    -
    The actor was unassigned from the issue.
    +
    The assignee was unassigned from the issue.
    unlabeled
    A label was removed from the issue.
    From cdc5defb0ae33f8460e946dde8da9d80fed7555d Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 10 Jun 2016 08:13:39 -0700 Subject: [PATCH 27/81] Sync changes from upstream repository --- content/v3/git/commits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md index e26e272085..b9cd4f22b9 100644 --- a/content/v3/git/commits.md +++ b/content/v3/git/commits.md @@ -105,7 +105,7 @@ Value | Description `gpgverify_error` | There was an error communicating with the signature-verification service. `gpgverify_unavailable` | The signature-verification service is currently unavailable. `unsigned` | The object does not include a signature. -`unkown_signature_type` | A non-PGP signature was found in the commit. +`unknown_signature_type` | A non-PGP signature was found in the commit. `no_user` | No user was associated with the `committer` email address in the commit. `unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account. `bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. From 218b121a456f63b6791204a05e6a49e063228672 Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 13 Jun 2016 15:47:47 -0700 Subject: [PATCH 28/81] Sync changes from upstream repository --- content/changes/2016-5-27-multiple-assignees.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/changes/2016-5-27-multiple-assignees.md b/content/changes/2016-5-27-multiple-assignees.md index a9646fc5c2..1a9c70fbb0 100644 --- a/content/changes/2016-5-27-multiple-assignees.md +++ b/content/changes/2016-5-27-multiple-assignees.md @@ -16,8 +16,13 @@ curl "https://api.github.com/repos/github/hubot/issues" \ The issues returned in this list will include the new `assignees` key. -You can learn more about the new responses and endpoints in the updated [Issues][issues] and [Issue Assignees][issue-assignees] documentation +You can learn more about the new responses and endpoints in the updated [Issues][issues] and [Issue Assignees][issue-assignees] documentation. + +If you have any questions or feedback, please [let us know][contact]! + [media-type]: /v3/media [issues]: /v3/issues [issue-assignees]: /v3/issues/assignees +[contact]: https://github.com/contact?form%5Bsubject%5D=Multiple+Assignees+API + From 1ee6be92c6d301a0ca06b6a90797e59e6115c1df Mon Sep 17 00:00:00 2001 From: Ruben Dijkstra Date: Wed, 15 Jun 2016 00:27:54 +0200 Subject: [PATCH 29/81] Add the original assignee to the list of assignees --- lib/responses/issues_and_prs.rb | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/responses/issues_and_prs.rb b/lib/responses/issues_and_prs.rb index d955cb1744..0f7d9a0fb9 100644 --- a/lib/responses/issues_and_prs.rb +++ b/lib/responses/issues_and_prs.rb @@ -135,6 +135,7 @@ module Responses ISSUE_WITH_ASSIGNEES ||= ISSUE.merge({ "assignees" => [ + USER, USER.merge("login" => "hubot"), USER.merge("login" => "other_user") ] From aae43caa7b147a24b6b3b1989493ee364cd5cb21 Mon Sep 17 00:00:00 2001 From: Ruben Dijkstra Date: Wed, 15 Jun 2016 00:28:42 +0200 Subject: [PATCH 30/81] Rename the USERS to the right user This introduces new constants, so that they can be used in other places as well. This makes the data a little more realistic. --- lib/responses/issues_and_prs.rb | 4 ++-- lib/responses/user.rb | 40 +++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/lib/responses/issues_and_prs.rb b/lib/responses/issues_and_prs.rb index 0f7d9a0fb9..847579d06a 100644 --- a/lib/responses/issues_and_prs.rb +++ b/lib/responses/issues_and_prs.rb @@ -136,8 +136,8 @@ module Responses ISSUE_WITH_ASSIGNEES ||= ISSUE.merge({ "assignees" => [ USER, - USER.merge("login" => "hubot"), - USER.merge("login" => "other_user") + HUBOT, + OTHER_USER ] }) diff --git a/lib/responses/user.rb b/lib/responses/user.rb index 402ad59936..300cd900e6 100644 --- a/lib/responses/user.rb +++ b/lib/responses/user.rb @@ -21,6 +21,46 @@ module Responses "site_admin" => false } + HUBOT ||= { + "login" => "hubot", + "id" => 1, + "avatar_url" => "https://github.com/images/error/hubot_happy.gif", + "gravatar_id" => "", + "url" => "https://api.github.com/users/hubot", + "html_url" => "https://github.com/hubot", + "followers_url" => "https://api.github.com/users/hubot/followers", + "following_url" => "https://api.github.com/users/hubot/following{/other_user}", + "gists_url" => "https://api.github.com/users/hubot/gists{/gist_id}", + "starred_url" => "https://api.github.com/users/hubot/starred{/owner}{/repo}", + "subscriptions_url" => "https://api.github.com/users/hubot/subscriptions", + "organizations_url" => "https://api.github.com/users/hubot/orgs", + "repos_url" => "https://api.github.com/users/hubot/repos", + "events_url" => "https://api.github.com/users/hubot/events{/privacy}", + "received_events_url" => "https://api.github.com/users/hubot/received_events", + "type" => "User", + "site_admin" => true + } + + OTHER_USER ||= { + "login" => "other_user", + "id" => 1, + "avatar_url" => "https://github.com/images/error/other_user_happy.gif", + "gravatar_id" => "", + "url" => "https://api.github.com/users/other_user", + "html_url" => "https://github.com/other_user", + "followers_url" => "https://api.github.com/users/other_user/followers", + "following_url" => "https://api.github.com/users/other_user/following{/other_user}", + "gists_url" => "https://api.github.com/users/other_user/gists{/gist_id}", + "starred_url" => "https://api.github.com/users/other_user/starred{/owner}{/repo}", + "subscriptions_url" => "https://api.github.com/users/other_user/subscriptions", + "organizations_url" => "https://api.github.com/users/other_user/orgs", + "repos_url" => "https://api.github.com/users/other_user/repos", + "events_url" => "https://api.github.com/users/other_user/events{/privacy}", + "received_events_url" => "https://api.github.com/users/other_user/received_events", + "type" => "User", + "site_admin" => false + } + CONTRIBUTOR ||= USER.merge({ "contributions" => 32 }) From 40e5d048e54400ac3c327edd26788e9e39a09cc6 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 16 Jun 2016 06:15:15 -0700 Subject: [PATCH 31/81] Sync changes from upstream repository --- .../2016-06-14-repository-invitations.md | 28 ++++++ content/v3/oauth.md | 2 +- content/v3/repos/collaborators.md | 16 +++ content/v3/repos/invitations.md | 98 +++++++++++++++++++ layouts/sidebar.html | 1 + lib/responses/repos.rb | 12 +++ 6 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 content/changes/2016-06-14-repository-invitations.md create mode 100644 content/v3/repos/invitations.md diff --git a/content/changes/2016-06-14-repository-invitations.md b/content/changes/2016-06-14-repository-invitations.md new file mode 100644 index 0000000000..5d39cdf46c --- /dev/null +++ b/content/changes/2016-06-14-repository-invitations.md @@ -0,0 +1,28 @@ +--- +title: API changes for Repository Invitations +author_name: CoralineAda +--- + +We announced [repository invitation functionality][repo-invitations-announcement] on May 23. Using the site, you can invite collaborators to work on your repository. Invitees will receive an email with the invitation and have the option to accept or decline. + +We have now have endpoints for managing repository invitations for both repository administrators and invitation recipients through the GitHub API. You can enable these changes during the preview period by providing a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.swamp-thing-preview + +For example: + + ``` command-line + curl "https://api.github.com/api/v3/repositories/1313/invitations" \ + -H 'Authorization: token TOKEN' \ + -H "Accept: application/vnd.github.swamp-thing-preview" \ + ``` + +You can learn more about the new endpoints in the updated [Collaborators][collaborators] and new [Repository Invitations][repo-invitations] documentation. + +If you have any questions or feedback, please [let us know][contact]. + +[media-type]: /v3/media +[collaborators]: /v3/repos/collaborators +[repo-invitations]: /v3/repos/invitations +[repo-invitations-announcement]: https://github.com/blog/2170-repository-invitations +[contact]: https://github.com/contact?form%5Bsubject%5D=Reactions+Repository+Invitations+API+Preview diff --git a/content/v3/oauth.md b/content/v3/oauth.md index 62cd4711d1..435cd815f8 100644 --- a/content/v3/oauth.md +++ b/content/v3/oauth.md @@ -196,7 +196,7 @@ Name | Description `user:email`| Grants read access to a user's email addresses. `user:follow`| Grants access to follow or unfollow other users. `public_repo`| Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories. -`repo`| Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public and private repositories and organizations. +`repo`| Grants read/write access to code, commit statuses, repository invitations, collaborators, and deployment statuses for public and private repositories and organizations. `repo_deployment`| Grants access to [deployment statuses][deployments] for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code. `repo:status`| Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code. `delete_repo`| Grants access to delete adminable repositories. diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index 2f5e94b9aa..15c94f9856 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -69,6 +69,17 @@ Name | Type | Description <%= fetch_content(:optional_put_content_length) %> +{{#tip}} + +We're currently offering a preview period allowing applications to opt in to the Repository Invitations API. + +To send an invitation to a collaborator rather than directly adding them, you must provide a custom [media type](/v3/media) in the `Accept` header: + +``` +application/vnd.github.swamp-thing-preview+json +``` + +{{/tip}} {% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} @@ -98,6 +109,11 @@ application/vnd.github.ironman-preview+json <%= headers 204 %> +### Response with preview media type + +<%= headers 200 %> +<%= json(:repository_invitation) { |h| [h] } %> + ## Remove user as a collaborator DELETE /repos/:owner/:repo/collaborators/:username diff --git a/content/v3/repos/invitations.md b/content/v3/repos/invitations.md new file mode 100644 index 0000000000..a9e327754f --- /dev/null +++ b/content/v3/repos/invitations.md @@ -0,0 +1,98 @@ +--- +title: Repository Invitations +--- + +# Repository Invitations + +{{#tip}} + +We're currently offering a preview of the Repository Invitations API. + +To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + +``` +application/vnd.github.swamp-thing-preview+json +``` + +{{/tip}} + +{:toc} + + + +## Invite a user to a repository + +Use the API endpoint for adding a collaborator [here](/v3/repos/collaborators). + + + +## List invitations for a repository + + GET /repositories/:repo_id/invitations + +When authenticating as a user with admin rights to a repository, this endpoint will list all currently open repository invitations. + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:repository_invitation) { |h| [h] } %> + + + +## Delete a repository invitation + + DELETE /repositories/:repo_id/invitations/:invitation_id + +### Response + +<%= headers 204 %> + + + +## Update a repository invitation + + PATCH /repositories/:repo_id/invitations/:invitation_id + +### Input + +Name | Type | Description +-----|------|-------------- +`permissions`|`string` | The permissions that the associated user will have on the repository. Valid values are `read`, `write`, and `admin`. + +### Response + +<%= headers 200 %> +<%= json(:repository_invitation) %> + + + +## List a user's repository invitations + + GET /user/repository_invitations + +When authenticating as a user, this endpoint will list all currently open repository invitations for that user. + +### Response + +<%= headers 200 %> +<%= json(:repository_invitation) { |h| [h] } %> + + + +## Accept a repository invitation + + PATCH /repositories/:repo_id/invitations/:invitation_id + +### Response + +<%= headers 204 %> + + + +## Decline a repository invitation + + DELETE /repositories/:repo_id/invitations/:invitation_id + +### Response + +<%= headers 204 %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 54ebad1a7b..bf98850e20 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -106,6 +106,7 @@

    Deployments
  • Downloads
  • Forks
    • +
  • Invitations
  • Merging
  • Pages
  • Releases
    • diff --git a/lib/responses/repos.rb b/lib/responses/repos.rb index 3f1dfc5c9d..843e942420 100644 --- a/lib/responses/repos.rb +++ b/lib/responses/repos.rb @@ -134,6 +134,18 @@ module Responses [0,1,43], [0,2,21] ] + + REPOSITORY_INVITATION ||= { + "id" => 1, + "repository" => REPO, + "invitee" => USER, + "inviter" => USER, + "permissions" => "write", + "created_at" => "2016-06-13T14:52:50-05:00", + "url" => "https://api.github.com/api/v3/repositories/1296269/invitations/", + "html_url" => "#{SIMPLE_REPO['html_url']}/invitations" + } + end end end From 221e99b9e319f3d6713ed44f2b43a9dc98b5c0a3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 16 Jun 2016 06:41:04 -0700 Subject: [PATCH 32/81] Sync changes from upstream repository --- content/changes/2016-06-14-repository-invitations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/changes/2016-06-14-repository-invitations.md b/content/changes/2016-06-14-repository-invitations.md index 5d39cdf46c..1c043cf991 100644 --- a/content/changes/2016-06-14-repository-invitations.md +++ b/content/changes/2016-06-14-repository-invitations.md @@ -11,11 +11,11 @@ We have now have endpoints for managing repository invitations for both reposito For example: - ``` command-line - curl "https://api.github.com/api/v3/repositories/1313/invitations" \ - -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.swamp-thing-preview" \ - ``` +``` command-line +curl "https://api.github.com/api/v3/repositories/1313/invitations" \ + -H 'Authorization: token TOKEN' \ + -H "Accept: application/vnd.github.swamp-thing-preview" \ +``` You can learn more about the new endpoints in the updated [Collaborators][collaborators] and new [Repository Invitations][repo-invitations] documentation. From 397d4b5117a3a912d801819383d237f5efa33b02 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 16 Jun 2016 08:43:32 -0700 Subject: [PATCH 33/81] Sync changes from upstream repository --- content/changes/2016-06-14-repository-invitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/changes/2016-06-14-repository-invitations.md b/content/changes/2016-06-14-repository-invitations.md index 1c043cf991..f02f5c1f11 100644 --- a/content/changes/2016-06-14-repository-invitations.md +++ b/content/changes/2016-06-14-repository-invitations.md @@ -25,4 +25,4 @@ If you have any questions or feedback, please [let us know][contact]. [collaborators]: /v3/repos/collaborators [repo-invitations]: /v3/repos/invitations [repo-invitations-announcement]: https://github.com/blog/2170-repository-invitations -[contact]: https://github.com/contact?form%5Bsubject%5D=Reactions+Repository+Invitations+API+Preview +[contact]: https://github.com/contact?form%5Bsubject%5D=Repository+Invitations+API+Preview From 094b17ce10f8d2e3d5807478e5b4bfc59f840c23 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 16 Jun 2016 10:53:11 -0700 Subject: [PATCH 34/81] Sync changes from upstream repository --- content/v3/repos/invitations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/v3/repos/invitations.md b/content/v3/repos/invitations.md index a9e327754f..6ba3c9326e 100644 --- a/content/v3/repos/invitations.md +++ b/content/v3/repos/invitations.md @@ -18,11 +18,11 @@ application/vnd.github.swamp-thing-preview+json {:toc} - + -## Invite a user to a repository +## Invite a user to a repository -Use the API endpoint for adding a collaborator [here](/v3/repos/collaborators). +Use the API endpoint for adding a collaborator [here](/v3/repos/collaborators). @@ -81,7 +81,7 @@ When authenticating as a user, this endpoint will list all currently open reposi ## Accept a repository invitation - PATCH /repositories/:repo_id/invitations/:invitation_id + PATCH /user/repository_invitations/:invitation_id ### Response @@ -91,7 +91,7 @@ When authenticating as a user, this endpoint will list all currently open reposi ## Decline a repository invitation - DELETE /repositories/:repo_id/invitations/:invitation_id + DELETE /user/repository_invitations/:invitation_id ### Response From c9054d2c8708b97f11ac43a1dbf7f9b20a6b49ae Mon Sep 17 00:00:00 2001 From: Pavan Ravipati Date: Thu, 16 Jun 2016 14:27:55 -0700 Subject: [PATCH 35/81] Fix capitalization for "pull request" --- content/guides/delivering-deployments.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/guides/delivering-deployments.md b/content/guides/delivering-deployments.md index 218cadfd9b..cc303407e4 100644 --- a/content/guides/delivering-deployments.md +++ b/content/guides/delivering-deployments.md @@ -14,9 +14,9 @@ the moment your code lands on `master`. This guide will use that API to demonstrate a setup that you can use. In our scenario, we will: -* Merge a Pull Request -* When the CI is finished, we'll set the Pull Request's status accordingly. -* When the Pull Request is merged, we'll run our deployment to our server. +* Merge a pull request +* When the CI is finished, we'll set the pull request's status accordingly. +* When the pull request is merged, we'll run our deployment to our server. Our CI system and host server will be figments of our imagination. They could be Heroku, Amazon, or something else entirely. The crux of this guide will be setting up @@ -50,7 +50,7 @@ Start this server up. By default, Sinatra starts on port `4567`, so you'll want to configure ngrok to start listening for that, too. In order for this server to work, we'll need to set a repository up with a webhook. -The webhook should be configured to fire whenever a Pull Request is created, or merged. +The webhook should be configured to fire whenever a pull request is created, or merged. Go ahead and create a repository you're comfortable playing around in. Might we suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)? After that, you'll create a new webhook in your repository, feeding it the URL @@ -64,10 +64,10 @@ Great! Click on **Let me select individual events.**, and select the following: * Deployment * Deployment status -* Pull Request +* pull request These are the events {{ site.data.variables.product.product_name }} will send to our server whenever the relevant action -occurs. We'll configure our server to *just* handle when Pull Requests are merged +occurs. We'll configure our server to *just* handle when pull requests are merged right now: ``` ruby From d7502f61c087d23b4325e2285e195fa227f1acc6 Mon Sep 17 00:00:00 2001 From: Pavan Ravipati Date: Thu, 16 Jun 2016 14:33:32 -0700 Subject: [PATCH 36/81] Recapitalize pull request when referred to as a feature --- content/guides/delivering-deployments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/delivering-deployments.md b/content/guides/delivering-deployments.md index cc303407e4..9d50dd5527 100644 --- a/content/guides/delivering-deployments.md +++ b/content/guides/delivering-deployments.md @@ -64,7 +64,7 @@ Great! Click on **Let me select individual events.**, and select the following: * Deployment * Deployment status -* pull request +* Pull Request These are the events {{ site.data.variables.product.product_name }} will send to our server whenever the relevant action occurs. We'll configure our server to *just* handle when pull requests are merged From 95609e61ebef9634d0613e6828e00986d068ce28 Mon Sep 17 00:00:00 2001 From: Jakub Wilk Date: Sat, 18 Jun 2016 19:40:48 +0200 Subject: [PATCH 37/81] Fix spelling of "etc." --- content/guides/delivering-deployments.md | 2 +- content/v3/troubleshooting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/guides/delivering-deployments.md b/content/guides/delivering-deployments.md index 218cadfd9b..7b155155e9 100644 --- a/content/guides/delivering-deployments.md +++ b/content/guides/delivering-deployments.md @@ -138,7 +138,7 @@ the output. First, let's complete our `process_deployment` method: ``` ruby def process_deployment payload = JSON.parse(@payload['payload']) - # you can send this information to your chat room, monitor, pager, e.t.c. + # you can send this information to your chat room, monitor, pager, etc. puts "Processing '#{@payload['description']}' for #{payload['deploy_user']} to #{payload['environment']}" sleep 2 # simulate work @client.create_deployment_status("repos/#{@payload['repository']['full_name']}/deployments/#{@payload['id']}", 'pending') diff --git a/content/v3/troubleshooting.md b/content/v3/troubleshooting.md index 9536fd7373..09a0d04864 100644 --- a/content/v3/troubleshooting.md +++ b/content/v3/troubleshooting.md @@ -20,7 +20,7 @@ To troubleshoot, ensure [you're authenticating correctly](/guides/getting-starte ## Why am I not seeing all my results? -Most API calls accessing a list of resources (_e.g._, users, issues, _e.t.c._) support +Most API calls accessing a list of resources (_e.g._, users, issues, _etc._) support pagination. If you're making requests and receiving an incomplete set of results, you're probably only seeing the first page. You'll need to request the remaining pages in order to get more results. From f62a21455e1c034ed6fa36e79ece18ea3f80d59a Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Sun, 19 Jun 2016 20:16:46 -0700 Subject: [PATCH 38/81] Fix formatting of Decline a repository invitation endpoint. --- content/v3/repos/invitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/repos/invitations.md b/content/v3/repos/invitations.md index 6ba3c9326e..50469923aa 100644 --- a/content/v3/repos/invitations.md +++ b/content/v3/repos/invitations.md @@ -91,7 +91,7 @@ When authenticating as a user, this endpoint will list all currently open reposi ## Decline a repository invitation - DELETE /user/repository_invitations/:invitation_id + DELETE /user/repository_invitations/:invitation_id ### Response From 59834eabf16f4bb592510fe2ff9734f58c0cba5f Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 22 Jun 2016 16:01:27 -0700 Subject: [PATCH 39/81] Sync changes from upstream repository --- ...2016-06-22-issue-locking-api-is-now-official.md | 14 ++++++++++++++ content/v3/issues.md | 7 +++++-- 2 files changed, 19 insertions(+), 2 deletions(-) create mode 100644 content/changes/2016-06-22-issue-locking-api-is-now-official.md diff --git a/content/changes/2016-06-22-issue-locking-api-is-now-official.md b/content/changes/2016-06-22-issue-locking-api-is-now-official.md new file mode 100644 index 0000000000..432a14a0a5 --- /dev/null +++ b/content/changes/2016-06-22-issue-locking-api-is-now-official.md @@ -0,0 +1,14 @@ +--- +title: Issue locking and unlocking APIs are now official +author_name: davidcelis +--- + +We're making the [Issue locking and unlocking APIs][issue-locking-blog-post] part of the official GitHub API. + +During the preview period you needed to provide the `application/vnd.github.the-key-preview+sha` preview media type in the `Accept` header to opt-in to the new endpoints. Now that the preview period has ended, you no longer need to specify this custom [media type][custom-media-types]. + +If you have any questions or feedback, please [get in touch with us][contact]! + +[issue-locking-blog-post]: /changes/2016-02-11-issue-locking-api/ +[custom-media-types]: /v3/media/ +[contact]: https://github.com/contact?form[subject]=Issue+Locking+and+Unlocking+API diff --git a/content/v3/issues.md b/content/v3/issues.md index dbc5f8ef7b..e2f9b9f5f4 100644 --- a/content/v3/issues.md +++ b/content/v3/issues.md @@ -283,10 +283,10 @@ The `assignees` key will only be present in issue payloads if this header is pas {{/tip}} {% endif %} -{% if page.version == 'dotcom' %} - +{% if page.version == 'dotcom' or page.version >= 2.6 %} ## Lock an issue +{% if page.version == 2.6 %} {{#tip}} @@ -300,6 +300,7 @@ The `assignees` key will only be present in issue payloads if this header is pas application/vnd.github.the-key-preview+json {{/tip}} +{% endif %} Users with push access can lock an issue's conversation. @@ -313,6 +314,7 @@ Users with push access can lock an issue's conversation. ## Unlock an issue +{% if page.version == 2.6 %} {{#tip}} @@ -326,6 +328,7 @@ Users with push access can lock an issue's conversation. application/vnd.github.the-key-preview+json {{/tip}} +{% endif %} Users with push access can unlock an issue's conversation. From 145091012d885ab720571a5fb7909b00f199a4b3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Sat, 25 Jun 2016 17:48:57 -0700 Subject: [PATCH 40/81] Sync changes from upstream repository --- content/v3/repos/collaborators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index 15c94f9856..726a9d84da 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -111,7 +111,7 @@ application/vnd.github.ironman-preview+json ### Response with preview media type -<%= headers 200 %> +<%= headers 201 %> <%= json(:repository_invitation) { |h| [h] } %> ## Remove user as a collaborator From 6f4a515a07f36069261ee6cfba7f91c66e4d5fd6 Mon Sep 17 00:00:00 2001 From: Hubot Date: Sat, 25 Jun 2016 18:05:55 -0700 Subject: [PATCH 41/81] Sync changes from upstream repository --- content/v3/repos/collaborators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index 726a9d84da..5bd3ad05b4 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -112,7 +112,7 @@ application/vnd.github.ironman-preview+json ### Response with preview media type <%= headers 201 %> -<%= json(:repository_invitation) { |h| [h] } %> +<%= json(:repository_invitation) %> ## Remove user as a collaborator From b403633f4b51e3bbb25da88aced2e3ae0c696a7a Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 27 Jun 2016 02:03:48 -0700 Subject: [PATCH 42/81] Sync changes from upstream repository --- assets/javascripts/initial.js | 10 + .../2014-03-18-paginating-method-changes.md | 2 +- .../2015-11-11-protected-branches-api.md | 4 +- ...016-06-27-protected-branches-api-update.md | 22 + content/v3/repos.md | 116 ---- content/v3/repos/branches.md | 522 ++++++++++++++++++ layouts/sidebar.html | 1 + lib/redirect_generator.rb | 2 +- lib/responses/git.rb | 14 - lib/responses/repos.rb | 21 + spec/spec_helper.rb | 2 +- 11 files changed, 582 insertions(+), 134 deletions(-) create mode 100644 content/changes/2016-06-27-protected-branches-api-update.md create mode 100644 content/v3/repos/branches.md diff --git a/assets/javascripts/initial.js b/assets/javascripts/initial.js index 08467f032a..be7d49d2fd 100644 --- a/assets/javascripts/initial.js +++ b/assets/javascripts/initial.js @@ -1,8 +1,18 @@ // before anything happens, check if this is a versionless enterprise URL path = window.location.pathname; +hash = window.location.hash; paths = path.split("/"); if (paths[1] == "enterprise" && (paths[2].length === 0 || isNaN(paths[2]))) { paths.splice(2, 0, String({{ site.version }})); suffix = window.location.search || window.location.hash; window.location.href = window.location.protocol + "//" + window.location.host + paths.join("/") + suffix; } +if (path == "/v3/repos/" && hash == "#enabling-and-disabling-branch-protection") { + window.location.href = "/v3/repos/branches/#get-branch-protection"; +} +if (path == "/v3/repos/" && hash == "#list-branches") { + window.location.href = "/v3/repos/branches/#list-branches"; +} +if (path == "/v3/repos/" && hash == "#get-branch") { + window.location.href = "/v3/repos/branches/#get-branch"; +} diff --git a/content/changes/2014-03-18-paginating-method-changes.md b/content/changes/2014-03-18-paginating-method-changes.md index 7909758b7e..9cba74b8db 100644 --- a/content/changes/2014-03-18-paginating-method-changes.md +++ b/content/changes/2014-03-18-paginating-method-changes.md @@ -119,7 +119,7 @@ Here's the complete list of updated methods: [Pull Request files]: /v3/pulls/#list-pull-requests-files [Release assets]: /v3/repos/releases/#list-assets-for-a-release [Repository contributors]: /v3/repos/#list-contributors -[Repository branches]: /v3/repos/#list-branches +[Repository branches]: /v3/repos/branches/#list-branches [Repository tags]: /v3/repos/#list-tags [Repository teams]: /v3/repos/#list-teams [Team members]: /v3/orgs/teams/#list-team-members diff --git a/content/changes/2015-11-11-protected-branches-api.md b/content/changes/2015-11-11-protected-branches-api.md index 3510ed9866..6b09f0ac9b 100644 --- a/content/changes/2015-11-11-protected-branches-api.md +++ b/content/changes/2015-11-11-protected-branches-api.md @@ -3,6 +3,8 @@ title: Protected Branches API Preview Period author_name: nakajima --- +**UPDATE (2016-06-27):** As [announced](/changes/2016-06-27-protected-branches-api-update/), there is an extended version of the protected branches API available. This older version will be removed once the new one becomes official. + We're starting a preview period for the [protected branches](https://github.com/blog/2051-protected-branches-and-required-status-checks) API. Protecting a branch prevents force-pushes to it as well as deleting it. You can also specify required status checks that are required to merge code into the branch. To protect a branch, make a `PATCH` request to the URL of the branch: @@ -33,6 +35,6 @@ To access this functionality during the preview period, you’ll need to provide application/vnd.github.loki-preview+json ``` -Take a look at [the docs here](/v3/repos/#enabling-and-disabling-branch-protection). +Take a look at [the docs here](/v3/repos/branches/). If you have any questions, please [get in touch](https://github.com/contact?form%5Bsubject%5D=Protected+Branches+API+Preview). diff --git a/content/changes/2016-06-27-protected-branches-api-update.md b/content/changes/2016-06-27-protected-branches-api-update.md new file mode 100644 index 0000000000..6ce7053298 --- /dev/null +++ b/content/changes/2016-06-27-protected-branches-api-update.md @@ -0,0 +1,22 @@ +--- +title: Update to Protected Branches API Preview +author_name: tma +--- + +Over the past few months, we've made a few [improvements](https://github.com/blog/2137-protected-branches-improvements) to the way [protected branches](https://github.com/blog/2051-protected-branches-and-required-status-checks) work in our web interface. Today, we're modifying the protected branches API [preview period](https://developer.github.com/changes/2015-11-11-protected-branches-api/) to include these improvements. + +Included in these API changes is the ability to allow organizations to specify which members and teams should be able to push to a protected branch, as well as providing a new setting for required status checks which will remove the requirement of a pull request to be up to date before merging. + +You'll notice a new endpoint structure. One set of endpoints for modifying the branch settings as a whole (`PATCH /repos/:owner/:repo/branches/:branch` has been updated to be `PUT /repos/:owner/:repo/branches/:branch/protection`), and a series of more granular endpoints to modify a subset of the branch protection settings. + +**This will be a breaking change for the protected branch API.** The deprecated API endpoint will be removed when the protected branches API will leave the preview period. If you're trying out the old protected branches API, you'll need to update your code. + +#### How can I try it? + +To access this functionality during the preview period, you’ll need to provide the following custom media type in the Accept header: + +``` +application/vnd.github.loki-preview+json +``` + +Take a look at [the docs here](/v3/repos/branches/). If you have any questions, please [get in touch](https://github.com/contact?form%5Bsubject%5D=Protected+Branches+API+Preview). diff --git a/content/v3/repos.md b/content/v3/repos.md index e4f1240ddf..2e8b726228 100644 --- a/content/v3/repos.md +++ b/content/v3/repos.md @@ -250,122 +250,6 @@ List languages for the specified repository. The value on the right of a languag <%= headers 200, :pagination => default_pagination_rels %> <%= json(:tag) { |h| [h] } %> -## List Branches - - GET /repos/:owner/:repo/branches - -### Parameters - -Name | Type | Description ------|------|------------- -`protected`|`string` | Set to `1` or `true` to only return protected branches. - -{{#tip}} - - - - The `protected` parameter is currently available for developers to preview. - During the preview period, the API may change without advance notice. - Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. - - To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.loki-preview+json - - The `protection` key will only be present in branch payloads if this header is passed. - -{{/tip}} - -### Response - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json(:branches) %> - -## Get Branch - - GET /repos/:owner/:repo/branches/:branch - -### Response - -{{#tip}} - - - - The Protected Branch API is currently available for developers to preview. - During the preview period, the API may change without advance notice. - Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. - - To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.loki-preview+json - - The `protection` key will only be present in branch payloads if this header is passed. - -{{/tip}} - -<%= headers 200 %> -<%= json(:branch) %> - -{% if page.version == 'dotcom' or page.version >= 2.5 %} - -## Enabling and disabling branch protection - -{{#tip}} - - - - The Protected Branch API is currently available for developers to preview. - During the preview period, the API may change without advance notice. - Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. - - To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.loki-preview+json - -{{/tip}} - -Protecting a branch requires admin access. - - PATCH /repos/:owner/:repo/branches/:branch - -### Input - -You need to pass a `protection` object. - -Name | Type | Description ------|------|------------- -`enabled`|`boolean` | **Required**. Should this branch be protected or not -`required_status_checks`|`object`| Configure required status checks here - -The `required_status_checks` object must have the following keys: - -Name | Type | Description ------|------|------------- -`enforcement_level`|`string` | **Required**. Who required status checks apply to. Options are `off`, `non_admins` or `everyone`. -`contexts`|`array` | **Required**. The list of status checks to require in order to merge into this branch - -The `enforcement_level` key can have the following values: - -Name | Description -------|------------ -`off` | Turn off required status checks for this branch. -`non_admins` | Required status checks will be enforced for non-admins. -`everyone` | Required status checks will be enforced for everyone (including admins). - -#### Example - -<%= json \ - "protection" => { - "enabled" => true, - "required_status_checks" => { - "enforcement_level" => "everyone", - "contexts" => ["continuous-integration/travis-ci"] - } - } -%> - -{% endif %} - ## Delete a Repository Deleting a repository requires admin access. If OAuth is used, the diff --git a/content/v3/repos/branches.md b/content/v3/repos/branches.md new file mode 100644 index 0000000000..1c11628394 --- /dev/null +++ b/content/v3/repos/branches.md @@ -0,0 +1,522 @@ +--- +title: Branches +--- + +# Branches + +{:toc} + +{% if page.version != 'dotcom' and page.version >= 2.5 and page.version < 2.7 %} + +## List Branches + + GET /repos/:owner/:repo/branches + +### Parameters + +Name | Type | Description +-----|------|------------- +`protected`| `boolean` | Set to `true` to only return protected branches + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + + The `protection` key will only be present in branch payloads if this header is passed. + +{{/tip}} + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:branches) { |a| a.each { |b| b.merge!("protection" => { + "enabled" => false, + "required_status_checks" => { + "enforcement_level" => "off", + "contexts" => [] + } +}) } } %> + +## Get Branch + + GET /repos/:owner/:repo/branches/:branch + +### Response + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + + The `protection` key will only be present in branch payloads if this header is passed. + +{{/tip}} + +<%= headers 200 %> +<%= json(:branch) { |h| h.merge!("protection" => { + "enabled" => false, + "required_status_checks" => { + "enforcement_level" => "off", + "contexts" => [] + } +}) } %> + +## Enabling and disabling branch protection + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2015-11-11-protected-branches-api) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + +{{/tip}} + +Protecting a branch requires admin access. + + PATCH /repos/:owner/:repo/branches/:branch + +### Parameters + +You need to pass a `protection` object. + +Name | Type | Description +-----|------|------------- +`enabled`|`boolean` | **Required**. Should this branch be protected or not +`required_status_checks`|`object`| Configure required status checks here + +The `required_status_checks` object must have the following keys: + +Name | Type | Description +-----|------|------------- +`enforcement_level`|`string` | **Required**. Who required status checks apply to. Options are `off`, `non_admins` or `everyone`. +`contexts`|`array` | **Required**. The list of status checks to require in order to merge into this branch + +The `enforcement_level` key can have the following values: + +Name | Description +------|------------ +`off` | Turn off required status checks for this branch. +`non_admins` | Required status checks will be enforced for non-admins. +`everyone` | Required status checks will be enforced for everyone (including admins). + +#### Example + +<%= json \ + "protection" => { + "enabled" => true, + "required_status_checks" => { + "enforcement_level" => "everyone", + "contexts" => ["continuous-integration/travis-ci"] + } + } +%> + +{% endif %} + +{% if page.version == 'dotcom' or page.version >= 2.7 %} + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2016-06-27-protected-branches-api-update) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + +{{/tip}} + +## List Branches + + GET /repos/:owner/:repo/branches + +### Parameters + +Name | Type | Description +-----|------|------------- +`protected` | `boolean` | Set to `true` to only return protected branches + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2016-06-27-protected-branches-api-update) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + + The `protected` key will only be present in branch payloads if this header is passed. + +{{/tip}} + +### Response + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json(:branches) { |a| a.each { |b| b.merge!( + "protected": true, + "protection_url": "https://api.github.com/repos/octocat/Hello-World/branches/#{b["name"]}/protection", +) } } %> + +## Get Branch + + GET /repos/:owner/:repo/branches/:branch + +### Response + +{{#tip}} + + + + The Protected Branch API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + Please see the [blog post](/changes/2016-06-27-protected-branches-api-update) for full details. + + To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.loki-preview+json + + The `protected` key will only be present in branch payloads if this header is passed. + +{{/tip}} + +<%= headers 200 %> +<%= json(:branch) { |h| h.merge!( + "protected": true, + "protection_url": "https://api.github.com/repos/octocat/Hello-World/branches/#{h["name"]}/protection", +) } %> + + +## Get branch protection + + GET /repos/:owner/:repo/branches/:branch/protection + +<%= headers 200 %> +<%= json(:repo_branch_protection) %> + +## Update branch protection + +Protecting a branch requires admin access. + + PUT /repos/:owner/:repo/branches/:branch/protection + +### Parameters + +You can pass two objects: `required_status_checks` and `restrictions`. Both can have the value `null` for disabled. + +The `required_status_checks` object must have the following keys: + +Name | Type | Description +-----|------|------------- +`include_admins` | `boolean` | **Required**. Enforce required status checks for repository administrators. +`strict` | `boolean` | **Required**. Require branches to be up to date before merging. +`contexts` | `array` | **Required**. The list of status checks to require in order to merge into this branch + +The `restrictions` object must have the following keys: + +Name | Type | Description +-----|------|------------- +`users` | `array` | The list of user `login`s with push access +`teams` | `array` | The list of team `slug`s with push access + +{{#tip}} + +* Teams and users `restrictions` are only available for organization-owned repositories. +* The list of users and teams in total is limited to 100 items. + +{{/tip}} + +### Example + +<%= json \ + "required_status_checks" => { + "include_admins" => true, + "strict" => true, + "contexts" => ["continuous-integration/travis-ci"] + }, + "restrictions" => { + "users" => ["octocat"], + "teams" => ["justice-league"] + } +%> + +### Response + +<%= headers 200 %> +<%= json(:repo_branch_protection) %> + +## Remove branch protection + + DELETE /repos/:owner/:repo/branches/:branch/protection + +<%= headers 204 %> + +## Get required status checks of protected branch + + GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks + +<%= headers 200 %> +<%= json(:repo_branch_protection_required_status_checks) %> + +## Update required status checks of protected branch + +Updating required status checks requires admin access and branch protection to be enabled. + + PATCH /repos/:owner/:repo/branches/:branch/protection/required_status_checks + +### Parameters + +The object passed can have the following keys: + +Name | Type | Description +-----|------|------------- +`include_admins`|`boolean` | Enforce required status checks for repository administrators. +`strict`|`boolean` | Require branches to be up to date before merging. +`contexts`|`array` | The list of status checks to require in order to merge into this branch + +### Example + +<%= json \ + "include_admins" => true, + "strict" => true, + "contexts" => ["continuous-integration/travis-ci"] +%> + +### Response + +<%= headers 200 %> +<%= json(:repo_branch_protection_required_status_checks) %> + +## Remove required status checks of protected branch + + DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks + +<%= headers 204 %> + +## List required status checks contexts of protected branch + + GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts + +<%= headers 200 %> +<%= json ["continuous-integration/travis-ci"] %> + +## Replace required status checks contexts of protected branch + + PUT /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts + +### Example + +<%= json ["continuous-integration/travis-ci"] %> + +### Response + +<%= headers 200 %> +<%= json ["continuous-integration/travis-ci"] %> + +## Add required status checks contexts of protected branch + + POST /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts + +### Example + +<%= json ["continuous-integration/jenkins"] %> + +### Response + +<%= headers 200 %> +<%= json ["continuous-integration/travis-ci", "continuous-integration/jenkins"] %> + +## Remove required status checks contexts of protected branch + + DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts + +### Example + +<%= json ["continuous-integration/jenkins"] %> + +### Response + +<%= headers 200 %> +<%= json ["continuous-integration/travis-ci"] %> + + +## Get restrictions of protected branch + +{{#tip}} + +Teams and users `restrictions` are only available for organization-owned repositories. + +{{/tip}} + + GET /repos/:owner/:repo/branches/:branch/protection/restrictions + +<%= headers 200 %> +<%= json(:repo_branch_protection_restrictions) %> + +## Remove restrictions of protected branch + + DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions + +<%= headers 204 %> + +## List team restrictions of protected branch + + GET /repos/:owner/:repo/branches/:branch/protection/restrictions/teams + +<%= headers 200 %> +<%= json(:team) { |h| [h] } %> + +## Replace team restrictions of protected branch + + PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/teams + +### Body parameters + +Pass the list of team `slug`s with push access. + +{{#tip}} + + The list of users and teams in total is limited to 100 items. + +{{/tip}} + +### Example + +<%= json ["justice-league"] %> + +### Response + +<%= headers 200 %> +<%= json(:team) { |h| [h] } %> + +## Add team restrictions of protected branch + + POST /repos/:owner/:repo/branches/:branch/protection/restrictions/teams + +### Body parameters + +Pass the list of team `slug`s with push access. + +{{#tip}} + +The list of users and teams in total is limited to 100 items. + +{{/tip}} + +### Example + +<%= json ["justice-league"] %> + +### Response + +<%= headers 200 %> +<%= json(:team) { |h| [h] } %> + +## Remove team restrictions of protected branch + + DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/teams + +### Example + +<%= json ["octocats"] %> + +### Response + +<%= headers 200 %> +<%= json(:team) { |h| [h] } %> + + +## List user restrictions of protected branch + + GET /repos/:owner/:repo/branches/:branch/protection/restrictions/users + +<%= headers 200 %> +<%= json(:user) { |h| [h] } %> + +## Replace user restrictions of protected branch + + PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/users + +### Body parameters + +Pass the list of user `login`s with push access. + +{{#tip}} + +The list of users and teams in total is limited to 100 items. + +{{/tip}} + +### Example + +<%= json ["octocat"] %> + +### Response + +<%= headers 200 %> +<%= json(:user) { |h| [h] } %> + +## Add user restrictions of protected branch + + POST /repos/:owner/:repo/branches/:branch/protection/restrictions/users + +### Body parameters + +Pass the list of user `login`s with push access. + +{{#tip}} + +The list of users and teams in total is limited to 100 items. + +{{/tip}} + +### Example + +<%= json ["octocat"] %> + +### Response + +<%= headers 200 %> +<%= json(:user) { |h| [h] } %> + +## Remove user restrictions of protected branch + + DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/users + +### Example + +<%= json ["defunkt"] %> + +### Response + +<%= headers 200 %> +<%= json(:user) { |h| [h] } %> + + +{% endif %} diff --git a/layouts/sidebar.html b/layouts/sidebar.html index bf98850e20..31ce45610c 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -98,6 +98,7 @@

    Repositories

      +
    • Branches
    • Collaborators
    • Comments
    • Commits
      • diff --git a/lib/redirect_generator.rb b/lib/redirect_generator.rb index 6d33ec5043..7472838137 100644 --- a/lib/redirect_generator.rb +++ b/lib/redirect_generator.rb @@ -2,7 +2,7 @@ module RedirectGenerator def generate_redirects(redirects) redirects.each do |pairs| pairs.each_pair do |old_url, new_url| - filename = old_url.to_s.sub(/\/$/, '') + filename = old_url.to_s.sub(%r{/$}, '') @items.create( "<%= renderp '/redirect.*', { :new_url => '#{new_url}' diff --git a/lib/responses/git.rb b/lib/responses/git.rb index ab4e20f637..a74100f679 100644 --- a/lib/responses/git.rb +++ b/lib/responses/git.rb @@ -20,25 +20,11 @@ module Responses "commit" => { "sha" => "6dcb09b5b57875f334f61aebed695e2e4193db5e", "url" => "https://api.github.com/repos/octocat/Hello-World/commits/c5b97d5ae6c19d5c5df71a34c7fbeeda2479ccbc" - }, - "protection" => { - "enabled" => false, - "required_status_checks" => { - "enforcement_level" => "off", - "contexts" => [] - } } } ] BRANCH ||= {"name"=>"master", - "protection" => { - "enabled" => false, - "required_status_checks" => { - "enforcement_level" => "off", - "contexts" => [] - } - }, "commit"=> {"sha"=>"7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "commit"=> diff --git a/lib/responses/repos.rb b/lib/responses/repos.rb index 843e942420..f2d1071867 100644 --- a/lib/responses/repos.rb +++ b/lib/responses/repos.rb @@ -146,6 +146,27 @@ module Responses "html_url" => "#{SIMPLE_REPO['html_url']}/invitations" } + REPO_BRANCH_PROTECTION_RESTRICTIONS ||= { + "url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions", + "users_url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/users", + "teams_url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/restrictions/teams", + "users" => [USER], + "teams" => [TEAM] + } + + REPO_BRANCH_PROTECTION_REQUIRED_STATUS_CHECKS ||= { + "url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks", + "include_admins" => true, + "strict" => true, + "contexts" => ["continuous-integration/travis-ci"], + "contexts_url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection/required_status_checks/contexts" + } + + REPO_BRANCH_PROTECTION ||= { + "url" => "https://api.github.com/repos/octocat/Hello-World/branches/master/protection", + "required_status_checks" => REPO_BRANCH_PROTECTION_REQUIRED_STATUS_CHECKS, + "restrictions" => REPO_BRANCH_PROTECTION_RESTRICTIONS + } end end end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 9902a40952..adc4095742 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -18,7 +18,7 @@ def posts return @posts if defined? @posts - diffable_files = `git diff -z --name-only --diff-filter=ACMRTUXB origin/master`.split("\0") + diffable_files = `git diff -z --name-only --diff-filter=ACRTUXB origin/master -- content/changes/`.split("\0") @posts = diffable_files.select do |filename| ext = File.extname(filename) From 4eb59b8ad21fac98ec105050ff05d0323779ac7f Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 29 Jun 2016 04:56:45 -0700 Subject: [PATCH 43/81] Sync changes from upstream repository --- content/v3/issues/assignees.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/issues/assignees.md b/content/v3/issues/assignees.md index e6e1f8927f..139a98f98c 100644 --- a/content/v3/issues/assignees.md +++ b/content/v3/issues/assignees.md @@ -64,7 +64,7 @@ This call adds the users passed in the `assignees` key (as their logins) to the ### Response <%= headers 201 %> -<%= json(:issue_with_assignees) { |h| [h] } %> +<%= json :issue_with_assignees %> ## Remove assignees from an Issue @@ -93,4 +93,4 @@ This call removes the users passed in the `assignees` key (as their logins) from ### Response <%= headers 200 %> -<%= json(:issue_with_assignees) { |h| [h] } %> +<%= json :issue_with_assignees %> From 1dc6b725fbde3b358769ac5fe22dff0a201ee2b6 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 29 Jun 2016 08:30:22 -0700 Subject: [PATCH 44/81] Sync changes from upstream repository --- content/webhooks/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/webhooks/index.md b/content/webhooks/index.md index a033ff3662..03fc42d1ca 100644 --- a/content/webhooks/index.md +++ b/content/webhooks/index.md @@ -50,7 +50,7 @@ Name | Description [`gollum`][event-types-gollum] | Any time a Wiki page is updated. [`issue_comment`][event-types-issue_comment] | {% if page.version == 'dotcom' or page.version > 2.6 %}Any time a [comment on an issue](/v3/issues/comments/) is created, edited, or deleted.{% else %}Any time an [issue is commented on](/v3/issues/comments).{% endif %} [`issues`][event-types-issues] | Any time an Issue is assigned, unassigned, labeled, unlabeled, opened, {% if page.version == 'dotcom' or page.version > 2.6 %}edited, {% endif %}closed, or reopened. -[`member`][event-types-member] | Any time a User is added as a collaborator to a non-Organization Repository. +[`member`][event-types-member] | Any time a User is added as a collaborator to a Repository. [`membership`][event-types-membership] | Any time a User is added or removed from a team. **Organization hooks only**. [`page_build`][event-types-page_build] | Any time a Pages site is built or results in a failed build. [`public`][event-types-public] | Any time a Repository changes from private to public. From cf9c9bd6317c9df9fe7cddde721ead2ca5e5bc54 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 30 Jun 2016 07:12:40 -0700 Subject: [PATCH 45/81] Sync changes from upstream repository --- content/v3/repos/commits.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md index 9c8e6e9a12..20c2ee69c3 100644 --- a/content/v3/repos/commits.md +++ b/content/v3/repos/commits.md @@ -25,9 +25,7 @@ Name | Type | Description ### Response -<%= - headers 200, :pagination => { :next => 'https://api.github.com/resource?page=2' } -%> +<%= headers 200, :pagination => default_pagination_rels %> <%= json(:commit) { |h| [h] } %> ## Get a single commit From 91cd7d654d462daa340dfd9741d02673fc8952da Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 30 Jun 2016 12:34:16 -0700 Subject: [PATCH 46/81] Sync changes from upstream repository --- lib/responses/license.rb | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/lib/responses/license.rb b/lib/responses/license.rb index c06ea97b5d..46d97c4176 100644 --- a/lib/responses/license.rb +++ b/lib/responses/license.rb @@ -26,12 +26,11 @@ module Responses "html_url"=>"http://choosealicense.com/licenses/mit/", "featured"=>true, "description"=>"A permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.", - "category"=>"MIT", "implementation"=> "Create a text file (typically named LICENSE or LICENSE.txt) in the root of your source code and copy the text of the license into the file. Replace [year] with the current year and [fullname] with the name (or names) of the copyright holders.", - "required"=>["include-copyright"], - "permitted"=>["commercial-use", "modifications", "distribution", "sublicense", "private-use"], - "forbidden"=>["no-liability"], + "permissions"=>["commercial-use", "modifications", "distribution", "sublicense", "private-use"], + "conditions"=>["include-copyright"], + "limitations"=>["no-liability"], "body"=> "\n\nThe MIT License (MIT)\n\nCopyright (c) [year] [fullname]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" } From dd38b89f7638fda685c6f7dfc8813147f158a884 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Thu, 30 Jun 2016 18:23:43 -0700 Subject: [PATCH 47/81] Use a more descriptive type for oauth.allow_signup If it's true or false, it's a boolean. --- content/v3/oauth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/oauth.md b/content/v3/oauth.md index 435cd815f8..1555d954d7 100644 --- a/content/v3/oauth.md +++ b/content/v3/oauth.md @@ -37,7 +37,7 @@ Name | Type | Description `redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). `scope`|`string` | A space delimited list of [scopes](#scopes). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope. `state`|`string` | An unguessable random string. It is used to protect against cross-site request forgery attacks. -`allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. +`allow_signup`|`boolean` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups. ### 2. GitHub redirects back to your site From 5dd1422bb03af0b773ea28d973b39a11751646f6 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 6 Jul 2016 12:17:31 -0700 Subject: [PATCH 48/81] Sync changes from upstream repository --- .../2016-07-06-github-pages-preiew-api.md | 43 +++++++++++++++ content/v3/repos/pages.md | 52 ++++++++++++++++++- lib/responses/pages.rb | 5 ++ 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 content/changes/2016-07-06-github-pages-preiew-api.md diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preiew-api.md new file mode 100644 index 0000000000..6bbff3007a --- /dev/null +++ b/content/changes/2016-07-06-github-pages-preiew-api.md @@ -0,0 +1,43 @@ +--- +title: Introducing the GitHub Pages preview API +author_name: benbalter +--- + +We're introducing additional preview functionality to the [GitHub Pages API](/v3/repos/pages/) to give developers better control over their GitHub Pages site. + +#### Requesting a page build + +You can now manually request a build of your GitHub Pages site without needing to push a new commit by making a `POST` request to the endpoint already available to see past builds. For example: + +``` command-line +curl "https://api.github.com/repositories/github/developer.github.com/pages/builds" \ + -X POST + -H 'Authorization: token TOKEN' \ + -H "Accept: application/vnd.github.mister-fantstic-preview" \ +``` + +#### Retrieving a site's URL + +With the introduction of [HTTPS support for GitHub Pages sites](https://github.com/blog/2186-https-for-github-pages), it's important to know not just a site's custom domain, if it has one, but also if it has HTTPS enforcement enabled. The GitHub Pages API will now return an additional `html_url` field, which will include the computed absolute URL to the site. + +The resulting URL can be `https://username.github.io` (or `http://username.github.io`) for user sites without a custom domain, `https://username.gituhb.io/project` for project sites, or `http://example.com` for sites with custom domains, saving third-party applications the trouble of having to construct complicated URL logic based on the username, owner, and CNAME, as was previously necessary. + +For example, to request the HTML URL: + +``` command-line +curl "https://api.github.com/repositories/github/developer.github.com/pages" \ + -H 'Authorization: token TOKEN' \ + -H "Accept: application/vnd.github.mister-fantstic-preview" \ +``` + +#### How can I try it? + +To access this functionality during the preview period, you’ll need to provide the following custom media type in the Accept header: + +``` +application/vnd.github.mister-fantastic-preview+json +``` + +During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice. + +For more information, take a look at [the docs here](/v3/repos/pages/), and if you have any questions, please [get in touch](https://github.com/contact?form%5Bsubject%5D=GitHub+Pages+API+Preview). diff --git a/content/v3/repos/pages.md b/content/v3/repos/pages.md index b088606a33..78f8c5ba94 100644 --- a/content/v3/repos/pages.md +++ b/content/v3/repos/pages.md @@ -6,13 +6,14 @@ title: Pages {:toc} -The Pages API retrieves information about your GitHub Pages configuration, and +The GitHub Pages API retrieves information about your GitHub Pages configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners, even though the websites are public. In JSON responses, `status` can be one of: * `null`, which means the site has yet to be built +* `queued`, which means the build has been requested but not yet begun * `building`, which means the build is in progress * `built`, which means the site has been built * `errored`, which indicates an error occurred during the build @@ -21,11 +22,60 @@ In JSON responses, `status` can be one of: GET /repos/:owner/:repo/pages +{% if page.version == 'dotcom' or page.version > 2.7 %} + +{{#tip}} + + + + Additional functionality of the GitHub Pages API is currently available for developers to preview. + During the preview period, the API may change without advance notice. + + To access the additional functionality during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.mister-fantastic-preview+json + + When the [preview flag](#preview-period) is passed, the response will contain an additional field, `html_url`, which will contain the absolute URL (with scheme) to the rendered site (e.g., `https://username.github.io`, or `http://example.com`). + +{{/tip}} + +{% endif %} + ### Response <%= headers 200 %> <%= json(:pages) %> +{% if page.version == 'dotcom' or page.version > 2.7 %} + +## Request a page build + + POST /repos/:owner/:repo/pages/builds + +{{#tip}} + + + + This endpoint is currently available for developers to preview. + During the preview period, the API may change without advance notice. + + To access this endpoint during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.mister-fantastic-preview+json + +{{/tip}} + +You can request that your site be built from the latest revision on the default branch. This has the same effect as pushing a commit to your default branch, but does not require an additional commit. Manually triggering page builds can be helpful when diagnosing build warnings and failures. + +Build requests are limited to one concurrent build per repository and one concurrent build per requester. If you request a build while another is still in progress, the second request will be queued until the first completes. + +### Response + +<%= headers 200 %> +<%= json(:pages_request_build) %> + +{% endif %} + ## List Pages builds GET /repos/:owner/:repo/pages/builds diff --git a/lib/responses/pages.rb b/lib/responses/pages.rb index 3854061833..d3d61ae3ab 100644 --- a/lib/responses/pages.rb +++ b/lib/responses/pages.rb @@ -22,6 +22,11 @@ module Responses "created_at" => "2014-02-10T19:00:49Z", "updated_at" => "2014-02-10T19:00:51Z" } + + PAGES_REQUEST_BUILD ||= { + "url" => "https://api.github.com/repos/github/developer.github.com/pages/builds/latest", + "status" => "queued" + } end end end From 0e76bd218b856b1df93b2d5c1a0aa2c9125400e7 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 7 Jul 2016 04:20:12 -0700 Subject: [PATCH 49/81] Sync changes from upstream repository --- content/changes/2016-06-14-repository-invitations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/changes/2016-06-14-repository-invitations.md b/content/changes/2016-06-14-repository-invitations.md index f02f5c1f11..00cddde89d 100644 --- a/content/changes/2016-06-14-repository-invitations.md +++ b/content/changes/2016-06-14-repository-invitations.md @@ -12,9 +12,9 @@ We have now have endpoints for managing repository invitations for both reposito For example: ``` command-line -curl "https://api.github.com/api/v3/repositories/1313/invitations" \ +curl "https://api.github.com/repos/github/hubot/invitations" \ -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.swamp-thing-preview" \ + -H "Accept: application/vnd.github.swamp-thing-preview" ``` You can learn more about the new endpoints in the updated [Collaborators][collaborators] and new [Repository Invitations][repo-invitations] documentation. From b9b3f5a0f6436aa9199a735b5d47a1420bd4a5de Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 7 Jul 2016 22:49:43 -0700 Subject: [PATCH 50/81] Sync changes from upstream repository --- content/changes/2016-07-06-github-pages-preiew-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preiew-api.md index 6bbff3007a..2c8374b29d 100644 --- a/content/changes/2016-07-06-github-pages-preiew-api.md +++ b/content/changes/2016-07-06-github-pages-preiew-api.md @@ -10,7 +10,7 @@ We're introducing additional preview functionality to the [GitHub Pages API](/v3 You can now manually request a build of your GitHub Pages site without needing to push a new commit by making a `POST` request to the endpoint already available to see past builds. For example: ``` command-line -curl "https://api.github.com/repositories/github/developer.github.com/pages/builds" \ +curl "https://api.github.com/repos/github/developer.github.com/pages/builds" \ -X POST -H 'Authorization: token TOKEN' \ -H "Accept: application/vnd.github.mister-fantstic-preview" \ @@ -25,7 +25,7 @@ The resulting URL can be `https://username.github.io` (or `http://username.githu For example, to request the HTML URL: ``` command-line -curl "https://api.github.com/repositories/github/developer.github.com/pages" \ +curl "https://api.github.com/repos/github/developer.github.com/pages" \ -H 'Authorization: token TOKEN' \ -H "Accept: application/vnd.github.mister-fantstic-preview" \ ``` From b30e47ca4d9d812394fc94bdfb24daf1192dd192 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 8 Jul 2016 03:30:15 -0700 Subject: [PATCH 51/81] Sync changes from upstream repository --- content/v3/orgs/members.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/v3/orgs/members.md b/content/v3/orgs/members.md index 3088bebe09..6f1b79abe4 100644 --- a/content/v3/orgs/members.md +++ b/content/v3/orgs/members.md @@ -144,7 +144,11 @@ The user can publicize their own membership. ## Get organization membership -{% if page.version == 'dotcom' or page.version >= 2.4 %} +{% if page.version == 'dotcom' or page.version >= 2.6 %} + +In order to get a user's membership with an organization, the authenticated user must be an organization member. + +{% elsif page.version >= 2.4 %} In order to get a user's membership with an organization, the authenticated user must be an organization owner. From 78f311a811ba0c6fcfd6a75a99a61c416dffc5ad Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 8 Jul 2016 09:27:13 -0700 Subject: [PATCH 52/81] Sync changes from upstream repository --- content/v3/repos/releases.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/v3/repos/releases.md b/content/v3/repos/releases.md index 7d792e19cc..73a2e10891 100644 --- a/content/v3/repos/releases.md +++ b/content/v3/repos/releases.md @@ -196,10 +196,9 @@ This may leave an empty asset with a state of `"new"`. It can be safely deleted {{#tip}} -If you want to download the asset's binary content, pass a media type of -`"application/octet-stream"`. The API will either redirect the client to the -location, or stream it directly if possible. API clients should handle both a -`200` or `302` response. +To download the asset's binary content, set the `Accept` header of the request to [`application/octet-stream`](https://developer.github.com/v3/media/#media-types). +The API will either redirect the client to the location, or stream it directly if possible. +API clients should handle both a `200` or `302` response. {{/tip}} From 81f6cd66a6750afdc172a0d91b8538f13d8892d8 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 8 Jul 2016 10:14:16 -0700 Subject: [PATCH 53/81] Sync changes from upstream repository --- content/changes/2016-06-22-issue-locking-api-is-now-official.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/changes/2016-06-22-issue-locking-api-is-now-official.md b/content/changes/2016-06-22-issue-locking-api-is-now-official.md index 432a14a0a5..81fb174003 100644 --- a/content/changes/2016-06-22-issue-locking-api-is-now-official.md +++ b/content/changes/2016-06-22-issue-locking-api-is-now-official.md @@ -5,7 +5,7 @@ author_name: davidcelis We're making the [Issue locking and unlocking APIs][issue-locking-blog-post] part of the official GitHub API. -During the preview period you needed to provide the `application/vnd.github.the-key-preview+sha` preview media type in the `Accept` header to opt-in to the new endpoints. Now that the preview period has ended, you no longer need to specify this custom [media type][custom-media-types]. +During the preview period you needed to provide the `application/vnd.github.the-key-preview+json` preview media type in the `Accept` header to opt-in to the new endpoints. Now that the preview period has ended, you no longer need to specify this custom [media type][custom-media-types]. If you have any questions or feedback, please [get in touch with us][contact]! From 2f6db25b21b85a70b69b3e4c3ef8b2dd7bc2796f Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 11 Jul 2016 18:33:26 -0700 Subject: [PATCH 54/81] Sync changes from upstream repository --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index b0842a92cb..49c438d8e5 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,18 @@ Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you s [nanoc]: http://nanoc.ws/ +### Enterprise + +To generate the `/enterprise/` versions, use `script/enterprise-backport`: + +``` sh +$ script/enterprise-backport 2.6 +$ mv -f enterprise output +$ script/server +``` + +The above will need to be repeated anytime changes are made to `/enterprise` versioned documentation. + ## Styleguide Not sure how to structure the docs? Here's what the structure of the From b565e2f444c54c00f34e4f257daaf22f4e3a9e47 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 14:22:12 -0700 Subject: [PATCH 55/81] Sync changes from upstream repository --- content/v3/misc.md | 4 ++++ content/v3/rate_limit.md | 4 ++++ content/v3/search.md | 4 ++++ layouts/sidebar.html | 2 ++ 4 files changed, 14 insertions(+) diff --git a/content/v3/misc.md b/content/v3/misc.md index 01a57d22a2..7fefcbb369 100644 --- a/content/v3/misc.md +++ b/content/v3/misc.md @@ -33,11 +33,15 @@ organization's [GitHub Enterprise](https://enterprise.github.com/) installation. {% endif %} +{% if page.version == 'dotcom' %} + ## [Rate Limit][] The [Rate Limit API][Rate Limit] lets you check your current rate limit status at any time. +{% endif %} + ## [Licenses][] The [Licenses API][Licenses] returns information about open source licenses or under what license, if any a given project is distributed. diff --git a/content/v3/rate_limit.md b/content/v3/rate_limit.md index b19c878ecb..cb27f21b3b 100644 --- a/content/v3/rate_limit.md +++ b/content/v3/rate_limit.md @@ -2,6 +2,8 @@ title: Rate Limit --- +{% if page.version == 'dotcom' %} + # Rate Limit The overview documentation describes the [rate limit rules](/v3/#rate-limiting). @@ -49,3 +51,5 @@ version of the API. If you're writing new API client code (or updating your existing code), you should use the `"core"` object instead of the `"rate"` object. The `"core"` object contains the same information that is present in the `"rate"` object. + +{% endif %} diff --git a/content/v3/search.md b/content/v3/search.md index 05ca2781c1..39df7d1f6e 100644 --- a/content/v3/search.md +++ b/content/v3/search.md @@ -25,6 +25,8 @@ is a computed value representing the relevance of an item relative to the other items in the result set. Multiple factors are combined to boost the most relevant item to the top of the result list. +{% if page.version == 'dotcom' %} + ### Rate limit The Search API has a custom rate limit. For requests using [Basic @@ -36,6 +38,8 @@ to make up to 10 requests per minute. See the [rate limit documentation](/v3/#rate-limiting) for details on determining your current rate limit status. +{% endif %} + ### Timeouts and incomplete results To keep the Search API fast for everyone, we limit how long any individual query diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 31ce45610c..fe51837c49 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -69,7 +69,9 @@

      Licenses
    • Markdown
    • Meta
      • + <% if @item[:version] == 'dotcom' %>
    • Rate Limit
      • + <% end %>

  • From 3ca3f26538087e4a976e040f81dae6f88dc7992d Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 14:53:22 -0700 Subject: [PATCH 56/81] Sync changes from upstream repository --- ...nding-multiple-assignees-preview-period.md | 13 ++++ content/v3/issues.md | 76 +------------------ content/v3/issues/assignees.md | 29 ------- content/v3/versions.md | 5 ++ 4 files changed, 22 insertions(+), 101 deletions(-) create mode 100644 content/changes/2016-7-1-ending-multiple-assignees-preview-period.md diff --git a/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md b/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md new file mode 100644 index 0000000000..13f6fc318b --- /dev/null +++ b/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md @@ -0,0 +1,13 @@ +--- +title: Multiple Assignees API is now official +author_name: nakajima +--- + +We're making [Multiple Assignees][blog-post] part of the official GitHub API. + +During the preview period you needed to provide the `application/vnd.github.cerberus-preview` preview media type in the `Accept` header to opt-in to the changes. Now that the preview period has ended, you no longer need to specify this custom media type. + +If you have any questions or feedback, please [get in touch with us][contact]! + +[blog-post]: /changes/2016-5-27-multiple-assignees/ +[contact]: https://github.com/contact?form[subject]=Multiple+Assignees+API diff --git a/content/v3/issues.md b/content/v3/issues.md index e2f9b9f5f4..59e7f99a29 100644 --- a/content/v3/issues.md +++ b/content/v3/issues.md @@ -159,33 +159,18 @@ Name | Type | Description -----|------|-------------- `title`|`string` | **Required**. The title of the issue. `body`|`string` | The contents of the issue. -`assignee`|`string` | Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise._ +`assignee`|`string` | Login for the user that this issue should be assigned to. _NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise. **This field is [deprecated](https://developer.github.com/v3/versions/#v3-deprecations).**_ `milestone`|`integer` | The `number` of the milestone to associate this issue with. _NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. _NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise._ `assignees`|`array` of `strings` | Logins for Users to assign to this issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ -{{#tip}} - - - -The `assignees` parameter is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -The `assignees` key will only be accepted in issue payloads if this header is passed. - -{{/tip}} - #### Example <%= json \ :title => "Found a bug", :body => "I'm having a problem with this.", :assignee => "octocat", + :assignees => [get_resource(:user)], :milestone => 1, :labels => %w(bug) %> @@ -195,25 +180,6 @@ The `assignees` key will only be accepted in issue payloads if this header is pa <%= headers 201, :Location => get_resource(:full_issue)['url'] %> <%= json :full_issue %> -{% if page.version == 'dotcom' %} -#### Multiple Assignees - -{{#tip}} - - - - An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. - Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview - - The `assignees` key will be an Array of Users who are assigned to the issue. - -{{/tip}} -{% endif %} - ## Edit an issue Issue owners and users with push access can edit an issue. @@ -226,34 +192,19 @@ Name | Type | Description -----|------|-------------- `title`|`string` | The title of the issue. `body`|`string` | The contents of the issue. -`assignee`|`string` | Login for the user that this issue should be assigned to. +`assignee`|`string` | Login for the user that this issue should be assigned to. **This field is [deprecated](https://developer.github.com/v3/versions/#v3-deprecations).** `state`|`string` | State of the issue. Either `open` or `closed`. `milestone`|`integer` | The `number` of the milestone to associate this issue with or `null` to remove current. _NOTE: Only users with push access can set the milestone for issues. The milestone is silently dropped otherwise._ `labels`|`array` of `strings` | Labels to associate with this issue. Pass one or more Labels to _replace_ the set of Labels on this Issue. Send an empty array (`[]`) to clear all Labels from the Issue. _NOTE: Only users with push access can set labels for issues. Labels are silently dropped otherwise._ `assignees`|`array` of `strings` | Logins for Users to assign to this issue. Pass one or more user logins to _replace_ the set of assignees on this Issue. .Send an empty array (`[]`) to clear all assignees from the Issue. _NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise._ -{{#tip}} - - - -The `assignees` parameter is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -The `assignees` key will only be present in issue payloads if this header is passed. - -{{/tip}} - #### Example <%= json \ :title => "Found a bug", :body => "I'm having a problem with this.", :assignee => "octocat", + :assignees => [get_resource(:user)], :milestone => 1, :state => "open", :labels => %w(bug) @@ -264,25 +215,6 @@ The `assignees` key will only be present in issue payloads if this header is pas <%= headers 200 %> <%= json :full_issue %> -{% if page.version == 'dotcom' %} -#### Multiple Assignees - -{{#tip}} - - - - An additional `assignees` object in the issue payload is currently available for developers to preview. During the preview period, the APIs may change without advance notice. - Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview - - The `assignees` key will be an Array of Users who are assigned to the issue. - -{{/tip}} -{% endif %} - {% if page.version == 'dotcom' or page.version >= 2.6 %} ## Lock an issue diff --git a/content/v3/issues/assignees.md b/content/v3/issues/assignees.md index 139a98f98c..4d0c1a59a0 100644 --- a/content/v3/issues/assignees.md +++ b/content/v3/issues/assignees.md @@ -38,21 +38,6 @@ Otherwise a `404` status code is returned. ## Add assignees to an Issue -{{#tip}} - - - -This endpoint is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -{{/tip}} - - This call adds the users passed in the `assignees` key (as their logins) to the issue. POST /repos/:owner/:repo/issues/:number/assignees @@ -68,20 +53,6 @@ This call adds the users passed in the `assignees` key (as their logins) to the ## Remove assignees from an Issue -{{#tip}} - - - -This endpoint is currently available for developers to preview. -During the preview period, the API may change without advance notice. -Please see the [blog post](/changes/2016-5-27-multiple-assignees) for full details. - -To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.cerberus-preview+json - -{{/tip}} - This call removes the users passed in the `assignees` key (as their logins) from the issue. DELETE /repos/:owner/:repo/issues/:number/assignees diff --git a/content/v3/versions.md b/content/v3/versions.md index e9112368d7..53c7cf6f33 100644 --- a/content/v3/versions.md +++ b/content/v3/versions.md @@ -145,6 +145,11 @@ The recommendations below will help you prepare your application for the next ma Recommendation: This attribute no longer dictates the permission a team has on its repositories; it only dictates the default permission that the [Add or update team repository](/v3/orgs/teams/#add-or-update-team-repository) API will use for requests where no `permission` attribute is specified. To change the permission level for every repository on a team, use the [List team repositories](/v3/orgs/teams/#list-team-repos) API to list all of the team's repositories, and then use the [Add or update team repository](/v3/orgs/teams/#add-or-update-team-repository) with a `permission` attribute to update each repository's permission separately. +1. Issue attribute: assignee + + Recommendation: Use the [`assignees`](https://developer.github.com/v3/issues/#create-an-issue) key instead, since issues can have more than one assignee. Alternatively, you can use the + [assignees](https://developer.github.com/v3/issues/assignees/) endpoints. + # beta (Deprecated) From 86a03bf66a38195703fabf3c9d7760ec49e25ece Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 12 Jul 2016 23:09:21 -0700 Subject: [PATCH 57/81] Sync changes from upstream repository --- ....md => 2016-07-12-ending-multiple-assignees-preview-period.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/changes/{2016-7-1-ending-multiple-assignees-preview-period.md => 2016-07-12-ending-multiple-assignees-preview-period.md} (100%) diff --git a/content/changes/2016-7-1-ending-multiple-assignees-preview-period.md b/content/changes/2016-07-12-ending-multiple-assignees-preview-period.md similarity index 100% rename from content/changes/2016-7-1-ending-multiple-assignees-preview-period.md rename to content/changes/2016-07-12-ending-multiple-assignees-preview-period.md From 53a38f9dbd20a99c90ebac1b05d332c3b0168fa8 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 14 Jul 2016 09:22:46 -0700 Subject: [PATCH 58/81] Sync changes from upstream repository --- README.md | 8 +++----- content/v3.md | 14 ++++++++++++-- content/v3/search.md | 8 ++++---- lib/resources.rb | 6 ++++-- script/server | 10 +++++++++- 5 files changed, 32 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 49c438d8e5..7a1e3bfcc9 100644 --- a/README.md +++ b/README.md @@ -48,15 +48,13 @@ Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you s ### Enterprise -To generate the `/enterprise/` versions, use `script/enterprise-backport`: +To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: ``` sh -$ script/enterprise-backport 2.6 -$ mv -f enterprise output -$ script/server +$ script/server 2.6 ``` -The above will need to be repeated anytime changes are made to `/enterprise` versioned documentation. +Note that live reloading is not available for Enterprise documentation. ## Styleguide diff --git a/content/v3.md b/content/v3.md index d73a059c18..a387737d67 100644 --- a/content/v3.md +++ b/content/v3.md @@ -32,9 +32,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/users/octocat/orgs > Status: 200 OK > ETag: "a00049ba79152d03380c34652f2cb612" > X-GitHub-Media-Type: github.v3 +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4987 > X-RateLimit-Reset: 1350085394 +{% endif %} > Content-Length: 5 > Cache-Control: max-age=0, private, must-revalidate > X-Content-Type-Options: nosniff @@ -504,9 +506,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 200 OK > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"' > HTTP/1.1 304 Not Modified @@ -515,9 +519,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 304 Not Modified > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT" > HTTP/1.1 304 Not Modified @@ -525,9 +531,11 @@ $ curl -i {{ site.data.variables.product.api_url_pre }}/user -H "If-Modified-Sin > Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT > Status: 304 Not Modified > Vary: Accept, Authorization, Cookie +{% if page.version == 'dotcom' %} > X-RateLimit-Limit: 5000 > X-RateLimit-Remaining: 4996 > X-RateLimit-Reset: 1372700873 +{% endif %} ``` ## Cross Origin Resource Sharing @@ -545,7 +553,7 @@ Here's a sample request sent from a browser hitting $ curl -i {{ site.data.variables.product.api_url_pre }} -H "Origin: http://example.com" HTTP/1.1 302 Found Access-Control-Allow-Origin: * -Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval +Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, {% if page.version == 'dotcom' %}X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,{% endif %} X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval Access-Control-Allow-Credentials: true ``` @@ -557,7 +565,7 @@ HTTP/1.1 204 No Content Access-Control-Allow-Origin: * Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE -Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval +Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, {% if page.version == 'dotcom' %}X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,{% endif %} X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval Access-Control-Max-Age: 86400 Access-Control-Allow-Credentials: true ``` @@ -576,9 +584,11 @@ $ curl https://api.github.com?callback=foo > /**/foo({ > "meta": { > "status": 200, +{% if page.version == 'dotcom' %} > "X-RateLimit-Limit": "5000", > "X-RateLimit-Remaining": "4966", > "X-RateLimit-Reset": "1372700873", +{% endif %} > "Link": [ // pagination headers and other links > ["https://api.github.com?page=2", {"rel": "next"}] > ] diff --git a/content/v3/search.md b/content/v3/search.md index 39df7d1f6e..bfdefdd175 100644 --- a/content/v3/search.md +++ b/content/v3/search.md @@ -97,7 +97,7 @@ repositories where the primary language is Assembly. We're sorting by stars in descending order, so that the most popular repositories appear first in the search results. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels{% if page.version == 'dotcom' %}, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:repo_search_v3_results) %> ### Highlighting Repository Search Results @@ -186,7 +186,7 @@ Here, we're searching for the keyword `addClass` within a file's contents. We're making sure that we're only looking in files where the language is JavaScript. And we're scoping the search to the `repo:jquery/jquery` repository. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:code_search_v3_results) %> ### Highlighting Code Search Results @@ -289,7 +289,7 @@ that's labeled as `bug`. The search runs across repositories whose primary language is Python. We’re sorting by creation date in ascending order, so that the oldest issues appear first in the search results. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:issue_search_v3_results) %> ### Highlighting Issue Search Results @@ -361,7 +361,7 @@ Imagine you're looking for a list of popular users. You might try out this query Here, we're looking at users with the name Tom. We're only interested in those with more than 42 repositories, and only if they have over 1,000 followers. -<%= headers 200, {:pagination => default_pagination_rels, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19} %> +<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:user_search_v3_results) %> ### Highlighting User Search Results diff --git a/lib/resources.rb b/lib/resources.rb index caa1276fee..8d3078aaec 100644 --- a/lib/resources.rb +++ b/lib/resources.rb @@ -67,8 +67,10 @@ def headers(status, head = {}) end end - lines << "X-RateLimit-Limit: 5000" unless head.has_key?('X-RateLimit-Limit') - lines << "X-RateLimit-Remaining: 4999" unless head.has_key?('X-RateLimit-Remaining') + unless @config[:version] != 'dotcom' + lines << "X-RateLimit-Limit: 5000" unless head.has_key?('X-RateLimit-Limit') + lines << "X-RateLimit-Remaining: 4999" unless head.has_key?('X-RateLimit-Remaining') + end %(``` headers\n#{lines.join("\n")}\n```\n) end diff --git a/script/server b/script/server index 33707763fe..d0365c2e66 100755 --- a/script/server +++ b/script/server @@ -3,4 +3,12 @@ ulimit -n 2048 script/bootstrap -DEV_MODE=true npm run gulp + +if [ -z "$1" ] + then + DEV_MODE=true npm run gulp + else + script/enterprise-backport $1 + mv -f enterprise output + npm run gulp server +fi From 9dd526708d48ea0f6d158339e11e359f985a67ba Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 19 Jul 2016 01:59:34 -0700 Subject: [PATCH 59/81] Sync changes from upstream repository --- content/changes/2016-07-06-github-pages-preiew-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preiew-api.md index 2c8374b29d..ab14cbee46 100644 --- a/content/changes/2016-07-06-github-pages-preiew-api.md +++ b/content/changes/2016-07-06-github-pages-preiew-api.md @@ -13,7 +13,7 @@ You can now manually request a build of your GitHub Pages site without needing t curl "https://api.github.com/repos/github/developer.github.com/pages/builds" \ -X POST -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.mister-fantstic-preview" \ + -H "Accept: application/vnd.github.mister-fantastic-preview" \ ``` #### Retrieving a site's URL @@ -27,7 +27,7 @@ For example, to request the HTML URL: ``` command-line curl "https://api.github.com/repos/github/developer.github.com/pages" \ -H 'Authorization: token TOKEN' \ - -H "Accept: application/vnd.github.mister-fantstic-preview" \ + -H "Accept: application/vnd.github.mister-fantastic-preview" \ ``` #### How can I try it? From 09675d035af2ec51ba44cf3be981f8eb40cdfbd9 Mon Sep 17 00:00:00 2001 From: Chao Date: Thu, 21 Jul 2016 15:16:36 -0400 Subject: [PATCH 60/81] fix date format. fix date format. --- lib/responses/admin.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/responses/admin.rb b/lib/responses/admin.rb index 6a8235cac3..340e6984f4 100644 --- a/lib/responses/admin.rb +++ b/lib/responses/admin.rb @@ -67,7 +67,7 @@ module Responses "seats_available" => 84, "kind" => "standard", "days_until_expiration" => 365, - "expire_at" => "2016/02/06 12:41:52 -0600" + "expire_at" => "2016-02-06T12:41:52-06:00" } INDEXING_SUCCESS ||= { From 95b05a946e09a259f59d6153c41d0cf4204d3a4c Mon Sep 17 00:00:00 2001 From: Hubot Date: Sun, 24 Jul 2016 04:39:07 -0700 Subject: [PATCH 61/81] Sync changes from upstream repository --- content/v3/gists.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/gists.md b/content/v3/gists.md index 1038a72acb..0f73102306 100644 --- a/content/v3/gists.md +++ b/content/v3/gists.md @@ -48,7 +48,7 @@ Name | Type | Description List all public gists sorted by most recently updated to least recently updated. -Note: With pagination, you can fetch up to 200 [pages](/v3/#pagination). +Note: With [pagination](/v3/#pagination), you can fetch up to 3000 gists. For example, you can fetch 100 pages with 30 gists per page or 30 pages with 100 gists per page. GET /gists/public From 22879a2512dca092867bdccc88a2af36d3e572db Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 29 Jul 2016 13:29:08 -0700 Subject: [PATCH 62/81] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ++++++++++++++++++ content/v3/enterprise/pre_receive_hooks.md | 110 ++++++++++ content/v3/orgs/pre_receive_hooks.md | 83 ++++++++ content/v3/repos/pre_receive_hooks.md | 88 ++++++++ layouts/sidebar.html | 10 + lib/responses/pre_receive.rb | 136 ++++++++++++ 6 files changed, 620 insertions(+) create mode 100644 content/v3/enterprise/pre_receive_environments.md create mode 100644 content/v3/enterprise/pre_receive_hooks.md create mode 100644 content/v3/orgs/pre_receive_hooks.md create mode 100644 content/v3/repos/pre_receive_hooks.md create mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md new file mode 100644 index 0000000000..ac12fe2409 --- /dev/null +++ b/content/v3/enterprise/pre_receive_environments.md @@ -0,0 +1,193 @@ +--- +title: Pre-receive Environments +--- + +# Pre-receive Environments + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +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. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Environment + +| Name | Type | Description | +|-----------------------|-----------|----------------------------------------------------------------------------| +| `name` | `string` | The name of the environment as displayed in the UI. | +| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | +| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | +| `download` | `object` | This environment's download status. | +| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | + +### Pre-receive Environment Download + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + + +## Get a single pre-receive environment + + GET /admin/pre-receive-environments/:id + +<%= headers 200 %> +<%= json :pre_receive_environment %> + +## List pre-receive environments + + GET /admin/pre_receive_environments + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_environments %> + +## Create a pre-receive environment + + POST /admin/pre_receive_environments + +### Parameters + +| Name | Type | Description | +|-------------|----------|-------------------------------------------------------------------------| +| `name` | `string` | **Required**. The new pre-receive environment's name. | +| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | + +<%= json \ + :name => 'DevTools Hook Env', + :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' +%> + +### Response + +<%= headers 201 %> +<%= json :pre_receive_environment_create %> + +## Edit a pre-receive environment + + PATCH /admin/pre_receive_environments/:id + +### Parameters + +| Name | Type | Description | +|-------------|----------|-----------------------------------------------------------| +| `name` | `string` | This pre-receive environment's new name. | +| `image_url` | `string` | URL from which to download a tarball of this environment. | + +### Response +<%= headers 200 %> +<%= json :pre_receive_environment %> + +#### Client Errors + +If you attempt to modify the default environment, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +## Delete a pre-receive environment + + DELETE /admin/pre_receive_environments/:id + +### Response + +<%= headers 204 %> + +#### Client Errors + +If you attempt to delete an environment that cannot be deleted, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Cannot delete environment that has hooks_ +- _Cannot delete environment when download is in progress_ + +## Get a pre-receive environment's download status + +In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. + + GET /admin/pre-receive-environments/:id/downloads/latest + +<%= headers 200 %> +<%= json :pre_receive_environment_download_2 %> + +### Object attributes + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + +## Trigger a pre-receive environment download + +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. + + POST /admin/pre_receive_environments/:id/downloads + +### Response + +<%= headers 202 %> +<%= json :pre_receive_environment_download %> + +#### Client Errors + +If a download cannot be triggered, you will get a reponse like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Can not start a new download when a download is in progress' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Can not start a new download when a download is in progress_ + diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md new file mode 100644 index 0000000000..876f242bbd --- /dev/null +++ b/content/v3/enterprise/pre_receive_hooks.md @@ -0,0 +1,110 @@ +--- +title: Pre-receive Hooks +--- + +# Pre-receive Hooks + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Hooks API allows you to create, list, update and delete +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. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Hook + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `script` | `string` | The script that the hook runs. | +| `script_repository` | `object` | The GitHub repository where the script is kept. | +| `environment` | `object` | The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +## Get a single pre-receive hook + + GET /admin/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook %> + +## List pre-receive hooks + + GET /admin/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks %> + +## Create a pre-receive hook + + POST /admin/pre-receive-hooks + +### Parameters + +| Name | Type | Description | +|----------------------------------|-----------|----------------------------------------------------------------------------------| +| `name` | `string` | **Required** The name of the hook. | +| `script` | `string` | **Required** The script that the hook runs. | +| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | +| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | + +<%= json \ + :name => "Check Commits", + :script => "scripts/commit_check.sh", + :enforcement => "disabled", + :allow_downstream_configuration => false, + :script_repository => { :full_name => "DevIT/hooks" }, + :environment => { :id => 2 } +%> + +### Response +<%= headers 201 %> +<%= json :pre_receive_hook %> + +## Edit a pre-receive hook + + PATCH /admin/pre_receive_hooks/:id + +<%= json \ + :name => "Check Commits", + :environment => { :id => 1 }, + :allow_downstream_configuration => true +%> + +### Response +<%= headers 200 %> +<%= json :pre_receive_hook_update %> + +## Delete a pre-receive hook + + DELETE /admin/pre_receive_hooks/:id + +### Response + +<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md new file mode 100644 index 0000000000..7d3afc0bd4 --- /dev/null +++ b/content/v3/orgs/pre_receive_hooks.md @@ -0,0 +1,83 @@ +--- +title: Organization Pre-receive Hooks +--- + +# Organization Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Organization Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to an organization. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this endpoint or this hook's global +configuration. Only site admins are able to access the global configuration. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +organization as well as any disabled hooks that can be configured at the +organization level. Globally disabled pre-receive hooks that do not allow +downstream configuration are not listed. + + GET /orgs/:org/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_org %> + +## Get a single pre-receive hook + + GET /orgs/:org:pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the org level, you can set +`enforcement` and `allow_downstream_configuration` + + PATCH /orgs/:org/pre-receive-hooks/:id + +<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_org_update %> + +## Remove enforcment overrides for a pre-receive hook + +Removes any overrides for this hook at the org level for this org. + + DELETE /orgs/:org/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md new file mode 100644 index 0000000000..2eef1d9459 --- /dev/null +++ b/content/v3/repos/pre_receive_hooks.md @@ -0,0 +1,88 @@ +--- +title: Repository Pre-receive Hooks +--- + +# Repository Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + + +{:toc} + +The Repository Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to a repository. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|---------------------|----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this repository, it's organization +owner or global configuration. Authorization to access the endpoint at +`configuration_url` is determined at the owner or site admin level. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +repository as well as any disabled hooks that are allowed to be enabled +at the repository level. Pre-receive hooks that are disabled at a higher +level and are not configurable will not be listed. + + GET /repos/:owner/:repo/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_repo %> + +## Get a single pre-receive hook + + GET /repos/:owner/:repo/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` + + PATCH /repos/:owner/:repo/pre-receive-hooks/:id + +<%= json :enforcement => "enabled" %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_repo_update %> + +## Remove enforcement overrides for a pre-receive hook + +Deletes any overridden enforcement on this repository for the specified +hook. + + DELETE /repos/:owner/:repo/pre-receive-hooks/:id + +### Response + +Responds with effective values inherited from owner and/or global level. + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index fe51837c49..b36458f202 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,6 +80,9 @@

    Members

  • Teams
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -116,6 +119,9 @@

    Statistics

  • Statuses
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -147,6 +153,10 @@

    LDAP

  • License
  • Management Console
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Environments
    • +
  • Pre-receive Hooks
    • + <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb new file mode 100644 index 0000000000..6ccf0a4ab9 --- /dev/null +++ b/lib/responses/pre_receive.rb @@ -0,0 +1,136 @@ +module GitHub + module Resources + module Responses + URL_OPTIONS = { + :base_api_url => "https://github.example.com/api/v3", + :base_url => "https://github.example.com" + } + + def self.options_to_output(options, keys_to_use) + keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } + end + + def self.pre_receive_environment_download(options = {}) + options = URL_OPTIONS.merge( + :id => 3, + :downloaded_at => '2016-05-26T07:42:53-05:00', + :state => 'success', + :message => nil + ).merge options + options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" + options_to_output options, %w(url state downloaded_at message) + end + + def self.pre_receive_environment(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Default', + :image_url => 'githubenterprise://internal', + :created_at => '2016-05-20T11:35:45-05:00', + :hooks_count => 1, + :download_options => {}, + :default_environment => true + ).merge options + options.update( + :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", + :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", + :download => pre_receive_environment_download(options.merge options[:download_options]) + ) + options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) + end + + def self.pre_receive_script_repository(options = {}) + options = URL_OPTIONS.merge( + :id => 595, + :full_name => "ExampleOrg/hooks", + ).merge options + options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" + options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output options, %w(id full_name url html_url) + end + + def self.pre_receive_hook(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Check Commits', + :script => 'scripts/commmit_check.sh', + :script_repository => { + :id => 595, + :full_name => "DevIT/hooks" + }, + :environment => PRE_RECEIVE_ENVIRONMENT, + :enforcement => "disabled", + :allow_downstream_configuration => false + ).merge options + options[:script_repository][:url] ||= + "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" + options[:script_repository][:html_url] ||= + "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) + end + + def self.pre_receive_hook_repo(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42" + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url)) + end + + def self.pre_receive_hook_org(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/admin/pre-receive-hooks/42", + :allow_downstream_configuration => true + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) + end + + PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ + :id => 2, + :name => "DevTools Hook Env", + :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", + :default_environment => false + }) + + PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ + "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) + }) + + PRE_RECEIVE_ENVIRONMENTS ||= [ + pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), + PRE_RECEIVE_ENVIRONMENT + ] + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= + pre_receive_environment_download :state => 'not_started', + :downloaded_at => nil + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download + + PRE_RECEIVE_HOOK ||= pre_receive_hook + PRE_RECEIVE_HOOKS ||= [pre_receive_hook] + PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment + + PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo + + PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] + + PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", + :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" + + PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org + PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] + PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42", + :allow_downstream_configuration => false + + end + end +end From 00da7b85ebeb4313551b7affa0e1f51b80f47a38 Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 1 Aug 2016 12:58:31 -0700 Subject: [PATCH 63/81] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ------------------ content/v3/enterprise/pre_receive_hooks.md | 110 ---------- content/v3/orgs/pre_receive_hooks.md | 83 -------- content/v3/repos/pre_receive_hooks.md | 88 -------- layouts/sidebar.html | 10 - lib/responses/pre_receive.rb | 136 ------------ 6 files changed, 620 deletions(-) delete mode 100644 content/v3/enterprise/pre_receive_environments.md delete mode 100644 content/v3/enterprise/pre_receive_hooks.md delete mode 100644 content/v3/orgs/pre_receive_hooks.md delete mode 100644 content/v3/repos/pre_receive_hooks.md delete mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md deleted file mode 100644 index ac12fe2409..0000000000 --- a/content/v3/enterprise/pre_receive_environments.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Pre-receive Environments ---- - -# Pre-receive Environments - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -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. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -### Pre-receive Environment - -| Name | Type | Description | -|-----------------------|-----------|----------------------------------------------------------------------------| -| `name` | `string` | The name of the environment as displayed in the UI. | -| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | -| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | -| `download` | `object` | This environment's download status. | -| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | - -### Pre-receive Environment Download - -| Name | Type | Description | -|-----------------|----------|---------------------------------------------------------| -| `state` | `string` | The state of the most recent download. | -| `downloaded_at` | `string` | The time when the most recent download started. | -| `message` | `string` | On failure, this will have any error messages produced. | - -Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. - - -## Get a single pre-receive environment - - GET /admin/pre-receive-environments/:id - -<%= headers 200 %> -<%= json :pre_receive_environment %> - -## List pre-receive environments - - GET /admin/pre_receive_environments - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_environments %> - -## Create a pre-receive environment - - POST /admin/pre_receive_environments - -### Parameters - -| Name | Type | Description | -|-------------|----------|-------------------------------------------------------------------------| -| `name` | `string` | **Required**. The new pre-receive environment's name. | -| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | - -<%= json \ - :name => 'DevTools Hook Env', - :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' -%> - -### Response - -<%= headers 201 %> -<%= json :pre_receive_environment_create %> - -## Edit a pre-receive environment - - PATCH /admin/pre_receive_environments/:id - -### Parameters - -| Name | Type | Description | -|-------------|----------|-----------------------------------------------------------| -| `name` | `string` | This pre-receive environment's new name. | -| `image_url` | `string` | URL from which to download a tarball of this environment. | - -### Response -<%= headers 200 %> -<%= json :pre_receive_environment %> - -#### Client Errors - -If you attempt to modify the default environment, you will get a response like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Cannot modify or delete the default environment' - }] -%> - -## Delete a pre-receive environment - - DELETE /admin/pre_receive_environments/:id - -### Response - -<%= headers 204 %> - -#### Client Errors - -If you attempt to delete an environment that cannot be deleted, you will get a response like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Cannot modify or delete the default environment' - }] -%> - -The possible error messages are: - -- _Cannot modify or delete the default environment_ -- _Cannot delete environment that has hooks_ -- _Cannot delete environment when download is in progress_ - -## Get a pre-receive environment's download status - -In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. - - GET /admin/pre-receive-environments/:id/downloads/latest - -<%= headers 200 %> -<%= json :pre_receive_environment_download_2 %> - -### Object attributes - -| Name | Type | Description | -|-----------------|----------|---------------------------------------------------------| -| `state` | `string` | The state of the most recent download. | -| `downloaded_at` | `string` | The time when the most recent download started. | -| `message` | `string` | On failure, this will have any error messages produced. | - -Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. - -## Trigger a pre-receive environment download - -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. - - POST /admin/pre_receive_environments/:id/downloads - -### Response - -<%= headers 202 %> -<%= json :pre_receive_environment_download %> - -#### Client Errors - -If a download cannot be triggered, you will get a reponse like this: - -<%= headers 422 %> -<%= - json :message => "Validation Failed", - :errors => [{ - :resource => :PreReceiveEnvironment, - :code => :custom, - :message => 'Can not start a new download when a download is in progress' - }] -%> - -The possible error messages are: - -- _Cannot modify or delete the default environment_ -- _Can not start a new download when a download is in progress_ - diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md deleted file mode 100644 index 876f242bbd..0000000000 --- a/content/v3/enterprise/pre_receive_hooks.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Pre-receive Hooks ---- - -# Pre-receive Hooks - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -The Pre-receive Hooks API allows you to create, list, update and delete -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. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -### Pre-receive Hook - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `script` | `string` | The script that the hook runs. | -| `script_repository` | `object` | The GitHub repository where the script is kept. | -| `environment` | `object` | The pre-receive environment where the script is executed. | -| `enforcement` | `string` | The state of enforcement for this hook. | -| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | - -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 -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -## Get a single pre-receive hook - - GET /admin/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook %> - -## List pre-receive hooks - - GET /admin/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks %> - -## Create a pre-receive hook - - POST /admin/pre-receive-hooks - -### Parameters - -| Name | Type | Description | -|----------------------------------|-----------|----------------------------------------------------------------------------------| -| `name` | `string` | **Required** The name of the hook. | -| `script` | `string` | **Required** The script that the hook runs. | -| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | -| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | -| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | -| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | - -<%= json \ - :name => "Check Commits", - :script => "scripts/commit_check.sh", - :enforcement => "disabled", - :allow_downstream_configuration => false, - :script_repository => { :full_name => "DevIT/hooks" }, - :environment => { :id => 2 } -%> - -### Response -<%= headers 201 %> -<%= json :pre_receive_hook %> - -## Edit a pre-receive hook - - PATCH /admin/pre_receive_hooks/:id - -<%= json \ - :name => "Check Commits", - :environment => { :id => 1 }, - :allow_downstream_configuration => true -%> - -### Response -<%= headers 200 %> -<%= json :pre_receive_hook_update %> - -## Delete a pre-receive hook - - DELETE /admin/pre_receive_hooks/:id - -### Response - -<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md deleted file mode 100644 index 7d3afc0bd4..0000000000 --- a/content/v3/orgs/pre_receive_hooks.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Organization Pre-receive Hooks ---- - -# Organization Pre-receive Hooks (Enterprise) - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - -{:toc} - -The Organization Pre-receive Hooks API allows you to view and modify -enforcement of the pre-receive hooks that are available to an organization. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -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 -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this endpoint or this hook's global -configuration. Only site admins are able to access the global configuration. - -## List pre-receive hooks - -List all pre-receive hooks that are enabled or testing for this -organization as well as any disabled hooks that can be configured at the -organization level. Globally disabled pre-receive hooks that do not allow -downstream configuration are not listed. - - GET /orgs/:org/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks_org %> - -## Get a single pre-receive hook - - GET /orgs/:org:pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_org %> - -## Update pre-receive hook enforcement - -For pre-receive hooks which are allowed to be configured at the org level, you can set -`enforcement` and `allow_downstream_configuration` - - PATCH /orgs/:org/pre-receive-hooks/:id - -<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> - -### Response - -<%= headers 200 %><%= json :pre_receive_hook_org_update %> - -## Remove enforcment overrides for a pre-receive hook - -Removes any overrides for this hook at the org level for this org. - - DELETE /orgs/:org/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md deleted file mode 100644 index 2eef1d9459..0000000000 --- a/content/v3/repos/pre_receive_hooks.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Repository Pre-receive Hooks ---- - -# Repository Pre-receive Hooks (Enterprise) - -{{#tip}} - - - - APIs for managing pre-receive hooks are currently available for developers to preview. - During the preview period, the APIs may change without advance notice. - - To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: - - application/vnd.github.eye-scream-preview - -{{/tip}} - - -{:toc} - -The Repository Pre-receive Hooks API allows you to view and modify -enforcement of the pre-receive hooks that are available to a repository. - -Prefix all the endpoints for this API with the following URL: - -``` command-line -http(s)://hostname/api/v3 -``` - -## Object attributes - -| Name | Type | Description | -|---------------------|----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -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 -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this repository, it's organization -owner or global configuration. Authorization to access the endpoint at -`configuration_url` is determined at the owner or site admin level. - -## List pre-receive hooks - -List all pre-receive hooks that are enabled or testing for this -repository as well as any disabled hooks that are allowed to be enabled -at the repository level. Pre-receive hooks that are disabled at a higher -level and are not configurable will not be listed. - - GET /repos/:owner/:repo/pre-receive-hooks - -<%= headers 200, :pagination => default_pagination_rels %> -<%= json :pre_receive_hooks_repo %> - -## Get a single pre-receive hook - - GET /repos/:owner/:repo/pre-receive-hooks/:id - -<%= headers 200 %> <%= json :pre_receive_hook_repo %> - -## Update pre-receive hook enforcement - -For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` - - PATCH /repos/:owner/:repo/pre-receive-hooks/:id - -<%= json :enforcement => "enabled" %> - -### Response - -<%= headers 200 %><%= json :pre_receive_hook_repo_update %> - -## Remove enforcement overrides for a pre-receive hook - -Deletes any overridden enforcement on this repository for the specified -hook. - - DELETE /repos/:owner/:repo/pre-receive-hooks/:id - -### Response - -Responds with effective values inherited from owner and/or global level. - -<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index b36458f202..fe51837c49 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,9 +80,6 @@

    Members
  • Teams
  • Webhooks
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Hooks (Enterprise)
    • - <% end %>
  • @@ -119,9 +116,6 @@

    Statistics

  • Statuses
  • Webhooks
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Hooks (Enterprise)
    • - <% end %>
  • @@ -153,10 +147,6 @@

    LDAP

  • License
  • Management Console
    • - <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> -
  • Pre-receive Environments
    • -
  • Pre-receive Hooks
    • - <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb deleted file mode 100644 index 6ccf0a4ab9..0000000000 --- a/lib/responses/pre_receive.rb +++ /dev/null @@ -1,136 +0,0 @@ -module GitHub - module Resources - module Responses - URL_OPTIONS = { - :base_api_url => "https://github.example.com/api/v3", - :base_url => "https://github.example.com" - } - - def self.options_to_output(options, keys_to_use) - keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } - end - - def self.pre_receive_environment_download(options = {}) - options = URL_OPTIONS.merge( - :id => 3, - :downloaded_at => '2016-05-26T07:42:53-05:00', - :state => 'success', - :message => nil - ).merge options - options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" - options_to_output options, %w(url state downloaded_at message) - end - - def self.pre_receive_environment(options = {}) - options = URL_OPTIONS.merge( - :id => 1, - :name => 'Default', - :image_url => 'githubenterprise://internal', - :created_at => '2016-05-20T11:35:45-05:00', - :hooks_count => 1, - :download_options => {}, - :default_environment => true - ).merge options - options.update( - :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", - :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", - :download => pre_receive_environment_download(options.merge options[:download_options]) - ) - options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) - end - - def self.pre_receive_script_repository(options = {}) - options = URL_OPTIONS.merge( - :id => 595, - :full_name => "ExampleOrg/hooks", - ).merge options - options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" - options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" - options_to_output options, %w(id full_name url html_url) - end - - def self.pre_receive_hook(options = {}) - options = URL_OPTIONS.merge( - :id => 1, - :name => 'Check Commits', - :script => 'scripts/commmit_check.sh', - :script_repository => { - :id => 595, - :full_name => "DevIT/hooks" - }, - :environment => PRE_RECEIVE_ENVIRONMENT, - :enforcement => "disabled", - :allow_downstream_configuration => false - ).merge options - options[:script_repository][:url] ||= - "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" - options[:script_repository][:html_url] ||= - "#{options[:base_url]}/#{options[:script_repository][:full_name]}" - options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) - end - - def self.pre_receive_hook_repo(options = {}) - options = URL_OPTIONS.merge( - :id => 42, - :name => "Check Commits", - :enforcement => "disabled", - :configuration_url => "/orgs/octocat/pre-receive-hooks/42" - ).merge options - options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" - options_to_output(options, %w(id name enforcement configuration_url)) - end - - def self.pre_receive_hook_org(options = {}) - options = URL_OPTIONS.merge( - :id => 42, - :name => "Check Commits", - :enforcement => "disabled", - :configuration_url => "/admin/pre-receive-hooks/42", - :allow_downstream_configuration => true - ).merge options - options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" - options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) - end - - PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ - :id => 2, - :name => "DevTools Hook Env", - :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", - :default_environment => false - }) - - PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ - "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) - }) - - PRE_RECEIVE_ENVIRONMENTS ||= [ - pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), - PRE_RECEIVE_ENVIRONMENT - ] - - PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= - pre_receive_environment_download :state => 'not_started', - :downloaded_at => nil - - PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download - - PRE_RECEIVE_HOOK ||= pre_receive_hook - PRE_RECEIVE_HOOKS ||= [pre_receive_hook] - PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment - - PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo - - PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] - - PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", - :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" - - PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org - PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] - PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", - :configuration_url => "/orgs/octocat/pre-receive-hooks/42", - :allow_downstream_configuration => false - - end - end -end From c0f824227f093ff2436bd41f074e638a22614854 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 2 Aug 2016 13:17:09 -0700 Subject: [PATCH 64/81] Sync changes from upstream repository --- .gitignore | 2 ++ Rakefile | 7 +++++++ script/enterprise-backport | 2 +- tasks/utils.rake | 2 +- tasks/versioning.rake | 4 ++++ 5 files changed, 15 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 482b02b2a9..cb3b5339eb 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ !/assets/vendor/lunr.js/lunr.js !/assets/vendor/lunr.js/lunr.min.js +_site/ +enterprise/ output tmp .DS_Store diff --git a/Rakefile b/Rakefile index 066f1ab736..b733333cb9 100644 --- a/Rakefile +++ b/Rakefile @@ -20,6 +20,10 @@ task :build do end end +task :build_latest_ent do + puts sh "script/enterprise-backport #{config[:versions].first} --keep" +end + desc "Test the output" task :test => [:remove_tmp_dir, :remove_output_dir, :build] do Rake::Task['spec'].invoke @@ -80,6 +84,9 @@ end namespace :assets do task :precompile => [:build] do sh 'mv output _site/' + Rake::Task['build_latest_ent'].invoke + sh "mkdir -p _site/enterprise/#{config[:versions].first}" + sh "mv output/* _site/enterprise/#{config[:versions].first}" end end diff --git a/script/enterprise-backport b/script/enterprise-backport index 8e8857ce87..8fa7c93ac1 100755 --- a/script/enterprise-backport +++ b/script/enterprise-backport @@ -52,7 +52,7 @@ data_variables: Nanoc::Int::SiteLoader.new.new_with_config(versioned_config).compile puts `node_modules/gulp/bin/gulp.js assets` - fail unless $CHILD_STATUS.to_i == 0 + raise unless $CHILD_STATUS.to_i == 0 versioned_config end diff --git a/tasks/utils.rake b/tasks/utils.rake index de2bc3aa0b..715373183d 100644 --- a/tasks/utils.rake +++ b/tasks/utils.rake @@ -1,3 +1,4 @@ +require 'yaml' require 'json' require 'active_support/core_ext/hash' @@ -8,4 +9,3 @@ end def symbolize_hash(hash) hash.deep_symbolize_keys end - diff --git a/tasks/versioning.rake b/tasks/versioning.rake index ad161de5d7..20baf25473 100644 --- a/tasks/versioning.rake +++ b/tasks/versioning.rake @@ -131,3 +131,7 @@ def cleanup FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/vendor" FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/images" end + +def keep? + ARGV.include?('--keep') +end From c07350e4198e0da96e143e24bd13bfcdefd6a212 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 10:13:50 -0700 Subject: [PATCH 65/81] Sync changes from upstream repository --- .../v3/enterprise/pre_receive_environments.md | 193 ++++++++++++++++++ content/v3/enterprise/pre_receive_hooks.md | 110 ++++++++++ content/v3/orgs/pre_receive_hooks.md | 83 ++++++++ content/v3/repos/pre_receive_hooks.md | 88 ++++++++ layouts/sidebar.html | 10 + lib/responses/pre_receive.rb | 136 ++++++++++++ nanoc.yaml | 3 +- 7 files changed, 622 insertions(+), 1 deletion(-) create mode 100644 content/v3/enterprise/pre_receive_environments.md create mode 100644 content/v3/enterprise/pre_receive_hooks.md create mode 100644 content/v3/orgs/pre_receive_hooks.md create mode 100644 content/v3/repos/pre_receive_hooks.md create mode 100644 lib/responses/pre_receive.rb diff --git a/content/v3/enterprise/pre_receive_environments.md b/content/v3/enterprise/pre_receive_environments.md new file mode 100644 index 0000000000..ac12fe2409 --- /dev/null +++ b/content/v3/enterprise/pre_receive_environments.md @@ -0,0 +1,193 @@ +--- +title: Pre-receive Environments +--- + +# Pre-receive Environments + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +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. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Environment + +| Name | Type | Description | +|-----------------------|-----------|----------------------------------------------------------------------------| +| `name` | `string` | The name of the environment as displayed in the UI. | +| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | +| `default_environment` | `boolean` | Whether this is the default environment that ships with GitHub Enterprise. | +| `download` | `object` | This environment's download status. | +| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | + +### Pre-receive Environment Download + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + + +## Get a single pre-receive environment + + GET /admin/pre-receive-environments/:id + +<%= headers 200 %> +<%= json :pre_receive_environment %> + +## List pre-receive environments + + GET /admin/pre_receive_environments + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_environments %> + +## Create a pre-receive environment + + POST /admin/pre_receive_environments + +### Parameters + +| Name | Type | Description | +|-------------|----------|-------------------------------------------------------------------------| +| `name` | `string` | **Required**. The new pre-receive environment's name. | +| `image_url` | `string` | **Required**. URL from which to download a tarball of this environment. | + +<%= json \ + :name => 'DevTools Hook Env', + :image_url => 'https://my_file_server/path/to/devtools_env.tar.gz' +%> + +### Response + +<%= headers 201 %> +<%= json :pre_receive_environment_create %> + +## Edit a pre-receive environment + + PATCH /admin/pre_receive_environments/:id + +### Parameters + +| Name | Type | Description | +|-------------|----------|-----------------------------------------------------------| +| `name` | `string` | This pre-receive environment's new name. | +| `image_url` | `string` | URL from which to download a tarball of this environment. | + +### Response +<%= headers 200 %> +<%= json :pre_receive_environment %> + +#### Client Errors + +If you attempt to modify the default environment, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +## Delete a pre-receive environment + + DELETE /admin/pre_receive_environments/:id + +### Response + +<%= headers 204 %> + +#### Client Errors + +If you attempt to delete an environment that cannot be deleted, you will get a response like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Cannot modify or delete the default environment' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Cannot delete environment that has hooks_ +- _Cannot delete environment when download is in progress_ + +## Get a pre-receive environment's download status + +In addition to seeing the download status at the `/admin/pre-receive-environments/:id`, there is also a separate endpoint for just the status. + + GET /admin/pre-receive-environments/:id/downloads/latest + +<%= headers 200 %> +<%= json :pre_receive_environment_download_2 %> + +### Object attributes + +| Name | Type | Description | +|-----------------|----------|---------------------------------------------------------| +| `state` | `string` | The state of the most recent download. | +| `downloaded_at` | `string` | The time when the most recent download started. | +| `message` | `string` | On failure, this will have any error messages produced. | + +Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. + +## Trigger a pre-receive environment download + +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. + + POST /admin/pre_receive_environments/:id/downloads + +### Response + +<%= headers 202 %> +<%= json :pre_receive_environment_download %> + +#### Client Errors + +If a download cannot be triggered, you will get a reponse like this: + +<%= headers 422 %> +<%= + json :message => "Validation Failed", + :errors => [{ + :resource => :PreReceiveEnvironment, + :code => :custom, + :message => 'Can not start a new download when a download is in progress' + }] +%> + +The possible error messages are: + +- _Cannot modify or delete the default environment_ +- _Can not start a new download when a download is in progress_ + diff --git a/content/v3/enterprise/pre_receive_hooks.md b/content/v3/enterprise/pre_receive_hooks.md new file mode 100644 index 0000000000..876f242bbd --- /dev/null +++ b/content/v3/enterprise/pre_receive_hooks.md @@ -0,0 +1,110 @@ +--- +title: Pre-receive Hooks +--- + +# Pre-receive Hooks + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Pre-receive Hooks API allows you to create, list, update and delete +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. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +### Pre-receive Hook + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `script` | `string` | The script that the hook runs. | +| `script_repository` | `object` | The GitHub repository where the script is kept. | +| `environment` | `object` | The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +## Get a single pre-receive hook + + GET /admin/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook %> + +## List pre-receive hooks + + GET /admin/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks %> + +## Create a pre-receive hook + + POST /admin/pre-receive-hooks + +### Parameters + +| Name | Type | Description | +|----------------------------------|-----------|----------------------------------------------------------------------------------| +| `name` | `string` | **Required** The name of the hook. | +| `script` | `string` | **Required** The script that the hook runs. | +| `script_repository` | `object` | **Required** The GitHub repository where the script is kept. | +| `environment` | `object` | **Required** The pre-receive environment where the script is executed. | +| `enforcement` | `string` | The state of enforcement for this hook. default: `disabled` | +| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. default: `false` | + +<%= json \ + :name => "Check Commits", + :script => "scripts/commit_check.sh", + :enforcement => "disabled", + :allow_downstream_configuration => false, + :script_repository => { :full_name => "DevIT/hooks" }, + :environment => { :id => 2 } +%> + +### Response +<%= headers 201 %> +<%= json :pre_receive_hook %> + +## Edit a pre-receive hook + + PATCH /admin/pre_receive_hooks/:id + +<%= json \ + :name => "Check Commits", + :environment => { :id => 1 }, + :allow_downstream_configuration => true +%> + +### Response +<%= headers 200 %> +<%= json :pre_receive_hook_update %> + +## Delete a pre-receive hook + + DELETE /admin/pre_receive_hooks/:id + +### Response + +<%= headers 204 %> diff --git a/content/v3/orgs/pre_receive_hooks.md b/content/v3/orgs/pre_receive_hooks.md new file mode 100644 index 0000000000..7d3afc0bd4 --- /dev/null +++ b/content/v3/orgs/pre_receive_hooks.md @@ -0,0 +1,83 @@ +--- +title: Organization Pre-receive Hooks +--- + +# Organization Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + +{:toc} + +The Organization Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to an organization. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|----------------------------------|-----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this endpoint or this hook's global +configuration. Only site admins are able to access the global configuration. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +organization as well as any disabled hooks that can be configured at the +organization level. Globally disabled pre-receive hooks that do not allow +downstream configuration are not listed. + + GET /orgs/:org/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_org %> + +## Get a single pre-receive hook + + GET /orgs/:org:pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the org level, you can set +`enforcement` and `allow_downstream_configuration` + + PATCH /orgs/:org/pre-receive-hooks/:id + +<%= json :enforcement => "enabled", :allow_downstream_configuration => false %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_org_update %> + +## Remove enforcment overrides for a pre-receive hook + +Removes any overrides for this hook at the org level for this org. + + DELETE /orgs/:org/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_org %> diff --git a/content/v3/repos/pre_receive_hooks.md b/content/v3/repos/pre_receive_hooks.md new file mode 100644 index 0000000000..2eef1d9459 --- /dev/null +++ b/content/v3/repos/pre_receive_hooks.md @@ -0,0 +1,88 @@ +--- +title: Repository Pre-receive Hooks +--- + +# Repository Pre-receive Hooks (Enterprise) + +{{#tip}} + + + + APIs for managing pre-receive hooks are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.eye-scream-preview + +{{/tip}} + + +{:toc} + +The Repository Pre-receive Hooks API allows you to view and modify +enforcement of the pre-receive hooks that are available to a repository. + +Prefix all the endpoints for this API with the following URL: + +``` command-line +http(s)://hostname/api/v3 +``` + +## Object attributes + +| Name | Type | Description | +|---------------------|----------|-----------------------------------------------------------| +| `name` | `string` | The name of the hook. | +| `enforcement` | `string` | The state of enforcement for the hook on this repository. | +| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | + +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 +any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. + +`configuration_url` may be a link to this repository, it's organization +owner or global configuration. Authorization to access the endpoint at +`configuration_url` is determined at the owner or site admin level. + +## List pre-receive hooks + +List all pre-receive hooks that are enabled or testing for this +repository as well as any disabled hooks that are allowed to be enabled +at the repository level. Pre-receive hooks that are disabled at a higher +level and are not configurable will not be listed. + + GET /repos/:owner/:repo/pre-receive-hooks + +<%= headers 200, :pagination => default_pagination_rels %> +<%= json :pre_receive_hooks_repo %> + +## Get a single pre-receive hook + + GET /repos/:owner/:repo/pre-receive-hooks/:id + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> + +## Update pre-receive hook enforcement + +For pre-receive hooks which are allowed to be configured at the repo level, you can set `enforcement` + + PATCH /repos/:owner/:repo/pre-receive-hooks/:id + +<%= json :enforcement => "enabled" %> + +### Response + +<%= headers 200 %><%= json :pre_receive_hook_repo_update %> + +## Remove enforcement overrides for a pre-receive hook + +Deletes any overridden enforcement on this repository for the specified +hook. + + DELETE /repos/:owner/:repo/pre-receive-hooks/:id + +### Response + +Responds with effective values inherited from owner and/or global level. + +<%= headers 200 %> <%= json :pre_receive_hook_repo %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index fe51837c49..35dd666473 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -80,6 +80,9 @@

    Members
  • Teams
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -116,6 +119,9 @@

    Statistics

  • Statuses
  • Webhooks
    • + <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %> +
  • Pre-receive Hooks (Enterprise)
    • + <% end %>
  • @@ -147,6 +153,10 @@

    LDAP

  • License
  • Management Console
    • + <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.7) %> +
  • Pre-receive Environments
    • +
  • Pre-receive Hooks
    • + <% end %>
  • Search Indexing
    • <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] >= 2.3) %>
  • Organization Administration
    • diff --git a/lib/responses/pre_receive.rb b/lib/responses/pre_receive.rb new file mode 100644 index 0000000000..6ccf0a4ab9 --- /dev/null +++ b/lib/responses/pre_receive.rb @@ -0,0 +1,136 @@ +module GitHub + module Resources + module Responses + URL_OPTIONS = { + :base_api_url => "https://github.example.com/api/v3", + :base_url => "https://github.example.com" + } + + def self.options_to_output(options, keys_to_use) + keys_to_use.map { |k| k.to_sym }.each_with_object(Hash.new) { |k, output| output[k] = options[k] } + end + + def self.pre_receive_environment_download(options = {}) + options = URL_OPTIONS.merge( + :id => 3, + :downloaded_at => '2016-05-26T07:42:53-05:00', + :state => 'success', + :message => nil + ).merge options + options[:url] = "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}/downloads/latest" + options_to_output options, %w(url state downloaded_at message) + end + + def self.pre_receive_environment(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Default', + :image_url => 'githubenterprise://internal', + :created_at => '2016-05-20T11:35:45-05:00', + :hooks_count => 1, + :download_options => {}, + :default_environment => true + ).merge options + options.update( + :url => "#{options[:base_api_url]}/admin/pre-receive-environments/#{options[:id]}", + :html_url => "#{options[:base_url]}/admin/pre_receive_environments/#{options[:id]}", + :download => pre_receive_environment_download(options.merge options[:download_options]) + ) + options_to_output options, %w(id name image_url url html_url default_environment created_at hooks_count download) + end + + def self.pre_receive_script_repository(options = {}) + options = URL_OPTIONS.merge( + :id => 595, + :full_name => "ExampleOrg/hooks", + ).merge options + options[:url] ||= "#{options[:base_api_url]}/repos/#{options[:full_name]}" + options[:html_url] ||= "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output options, %w(id full_name url html_url) + end + + def self.pre_receive_hook(options = {}) + options = URL_OPTIONS.merge( + :id => 1, + :name => 'Check Commits', + :script => 'scripts/commmit_check.sh', + :script_repository => { + :id => 595, + :full_name => "DevIT/hooks" + }, + :environment => PRE_RECEIVE_ENVIRONMENT, + :enforcement => "disabled", + :allow_downstream_configuration => false + ).merge options + options[:script_repository][:url] ||= + "#{options[:base_api_url]}/repos/#{options[:script_repository][:full_name]}" + options[:script_repository][:html_url] ||= + "#{options[:base_url]}/#{options[:script_repository][:full_name]}" + options_to_output(options, %w(id name enforcement script script_repository environment allow_downstream_configuration)) + end + + def self.pre_receive_hook_repo(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42" + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url)) + end + + def self.pre_receive_hook_org(options = {}) + options = URL_OPTIONS.merge( + :id => 42, + :name => "Check Commits", + :enforcement => "disabled", + :configuration_url => "/admin/pre-receive-hooks/42", + :allow_downstream_configuration => true + ).merge options + options[:configuration_url] = "#{options[:base_api_url]}#{options[:configuration_url]}" + options_to_output(options, %w(id name enforcement configuration_url allow_downstream_configuration)) + end + + PRE_RECEIVE_ENVIRONMENT ||= pre_receive_environment ({ + :id => 2, + :name => "DevTools Hook Env", + :image_url => "https://my_file_server/path/to/devtools_env.tar.gz", + :default_environment => false + }) + + PRE_RECEIVE_ENVIRONMENT_CREATE ||= PRE_RECEIVE_ENVIRONMENT.merge ({ + "download": pre_receive_environment_download(:id => 2, :state => 'not_started', :downloaded_at => nil) + }) + + PRE_RECEIVE_ENVIRONMENTS ||= [ + pre_receive_environment(:download_options => {:state => 'not_started'}, :hooks_count => 14), + PRE_RECEIVE_ENVIRONMENT + ] + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD ||= + pre_receive_environment_download :state => 'not_started', + :downloaded_at => nil + + PRE_RECEIVE_ENVIRONMENT_DOWNLOAD_2 ||= pre_receive_environment_download + + PRE_RECEIVE_HOOK ||= pre_receive_hook + PRE_RECEIVE_HOOKS ||= [pre_receive_hook] + PRE_RECEIVE_HOOK_UPDATE ||= pre_receive_hook :allow_downstream_configuration => true, :environment => pre_receive_environment + + PRE_RECEIVE_HOOK_REPO ||= pre_receive_hook_repo + + PRE_RECEIVE_HOOKS_REPO ||= [pre_receive_hook_repo] + + PRE_RECEIVE_HOOK_REPO_UPDATE ||= pre_receive_hook_repo :enforcement => "enabled", + :configuration_url => "/repos/octocat/hello-world/pre-receive-hooks/42" + + PRE_RECEIVE_HOOK_ORG ||= pre_receive_hook_org + PRE_RECEIVE_HOOKS_ORG ||= [pre_receive_hook_org] + PRE_RECEIVE_HOOK_ORG_UPDATE ||= pre_receive_hook_org :enforcement => "enabled", + :configuration_url => "/orgs/octocat/pre-receive-hooks/42", + :allow_downstream_configuration => false + + end + end +end diff --git a/nanoc.yaml b/nanoc.yaml index 5dc691517e..1f22d618df 100644 --- a/nanoc.yaml +++ b/nanoc.yaml @@ -12,7 +12,8 @@ pipeline_config: asset_root: https://a248.e.akamai.net/assets.github.com/images/icons versions: - - &latest_enterprise_version 2.6 + - &latest_enterprise_version 2.7 + - 2.6 - 2.5 - 2.4 - 2.3 From 26e8ca5c900f4e244ef7514e0f1f365822060628 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 10:59:40 -0700 Subject: [PATCH 66/81] Sync changes from upstream repository --- repository-sync | 1 + 1 file changed, 1 insertion(+) create mode 100644 repository-sync diff --git a/repository-sync b/repository-sync new file mode 100644 index 0000000000..d00491fd7e --- /dev/null +++ b/repository-sync @@ -0,0 +1 @@ +1 From 30ec6f73d02dfcfe55a7fdc41f0d1c4225be5323 Mon Sep 17 00:00:00 2001 From: Dirkjan Bussink Date: Wed, 3 Aug 2016 20:02:50 +0200 Subject: [PATCH 67/81] Revert "Sync changes from upstream repository" This reverts commit c0f824227f093ff2436bd41f074e638a22614854. --- .gitignore | 2 -- Rakefile | 7 ------- script/enterprise-backport | 2 +- tasks/utils.rake | 2 +- tasks/versioning.rake | 4 ---- 5 files changed, 2 insertions(+), 15 deletions(-) diff --git a/.gitignore b/.gitignore index cb3b5339eb..482b02b2a9 100644 --- a/.gitignore +++ b/.gitignore @@ -12,8 +12,6 @@ !/assets/vendor/lunr.js/lunr.js !/assets/vendor/lunr.js/lunr.min.js -_site/ -enterprise/ output tmp .DS_Store diff --git a/Rakefile b/Rakefile index b733333cb9..066f1ab736 100644 --- a/Rakefile +++ b/Rakefile @@ -20,10 +20,6 @@ task :build do end end -task :build_latest_ent do - puts sh "script/enterprise-backport #{config[:versions].first} --keep" -end - desc "Test the output" task :test => [:remove_tmp_dir, :remove_output_dir, :build] do Rake::Task['spec'].invoke @@ -84,9 +80,6 @@ end namespace :assets do task :precompile => [:build] do sh 'mv output _site/' - Rake::Task['build_latest_ent'].invoke - sh "mkdir -p _site/enterprise/#{config[:versions].first}" - sh "mv output/* _site/enterprise/#{config[:versions].first}" end end diff --git a/script/enterprise-backport b/script/enterprise-backport index 8fa7c93ac1..8e8857ce87 100755 --- a/script/enterprise-backport +++ b/script/enterprise-backport @@ -52,7 +52,7 @@ data_variables: Nanoc::Int::SiteLoader.new.new_with_config(versioned_config).compile puts `node_modules/gulp/bin/gulp.js assets` - raise unless $CHILD_STATUS.to_i == 0 + fail unless $CHILD_STATUS.to_i == 0 versioned_config end diff --git a/tasks/utils.rake b/tasks/utils.rake index 715373183d..de2bc3aa0b 100644 --- a/tasks/utils.rake +++ b/tasks/utils.rake @@ -1,4 +1,3 @@ -require 'yaml' require 'json' require 'active_support/core_ext/hash' @@ -9,3 +8,4 @@ end def symbolize_hash(hash) hash.deep_symbolize_keys end + diff --git a/tasks/versioning.rake b/tasks/versioning.rake index 20baf25473..ad161de5d7 100644 --- a/tasks/versioning.rake +++ b/tasks/versioning.rake @@ -131,7 +131,3 @@ def cleanup FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/vendor" FileUtils.rm_rf "#{VERSIONED_ENT_PATH}/assets/images" end - -def keep? - ARGV.include?('--keep') -end From daa9070241b47862deaf7109da5d7c1e3808d792 Mon Sep 17 00:00:00 2001 From: Hubot Date: Wed, 3 Aug 2016 11:37:23 -0700 Subject: [PATCH 68/81] Sync changes from upstream repository --- content/v3/reactions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/reactions.md b/content/v3/reactions.md index a492093f4c..d8effc8a38 100644 --- a/content/v3/reactions.md +++ b/content/v3/reactions.md @@ -2,7 +2,7 @@ title: Reactions --- -{% if page.version == 'dotcom' %} +{% if page.version == 'dotcom' or page.version >= 2.7 %} # Reactions @@ -24,7 +24,7 @@ title: Reactions ## Reaction types - + When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): content | emoji From 685b58c584cd2bfe48de0add28924ee6adacdd22 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 4 Aug 2016 09:47:49 -0700 Subject: [PATCH 69/81] Sync changes from upstream repository --- content/v3/repos/collaborators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md index 5bd3ad05b4..5e22e210d7 100644 --- a/content/v3/repos/collaborators.md +++ b/content/v3/repos/collaborators.md @@ -19,11 +19,11 @@ collaborators list. ### Response +{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} + <%= headers 200, :pagination => default_pagination_rels %> <%= json(:user) { |h| [h] } %> -{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %} - ### Alternative response with extra repository information {{#tip}} From 3643cbc394ce96be53382d27e7c134b814758b82 Mon Sep 17 00:00:00 2001 From: Hubot Date: Fri, 5 Aug 2016 09:44:59 -0700 Subject: [PATCH 70/81] Sync changes from upstream repository --- content/integrations-directory/getting-listed.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/content/integrations-directory/getting-listed.md b/content/integrations-directory/getting-listed.md index 907a9088c0..7a96f11057 100644 --- a/content/integrations-directory/getting-listed.md +++ b/content/integrations-directory/getting-listed.md @@ -37,11 +37,7 @@ marketing site. As your product changes, keep your Integration Directory listing ### Provide categories for your listing -Help GitHub users find your integration faster with the appropriate categories. Please send us your suggested categories for the listing. We reserve the right to remove categories from a listing, but we won't add any categories without your approval. Currently, the following categories are available: - -* Code -* Collaborate -* Ship +Help GitHub users find your integration faster with the appropriate categories. Please send us your suggested categories for the listing from those available in the [Integrations Directory](https://github.com/integrations). If you don't see a category that fits quite right, just let us know. We reserve the right to change categories associated with the listing. If we do so, we'll do our best to keep you informed. If your integration supports both GitHub.com and GitHub Enterprise, please let us know. From 420621464ee2a0b96a9c3b089cd085421e3ccab3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 8 Aug 2016 03:11:46 -0700 Subject: [PATCH 71/81] Sync changes from upstream repository --- ...pages-preiew-api.md => 2016-07-06-github-pages-preview-api.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/changes/{2016-07-06-github-pages-preiew-api.md => 2016-07-06-github-pages-preview-api.md} (100%) diff --git a/content/changes/2016-07-06-github-pages-preiew-api.md b/content/changes/2016-07-06-github-pages-preview-api.md similarity index 100% rename from content/changes/2016-07-06-github-pages-preiew-api.md rename to content/changes/2016-07-06-github-pages-preview-api.md From 6d983225b476e7cbaf5152001bc89fc5261363a3 Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 9 Aug 2016 11:45:20 -0700 Subject: [PATCH 72/81] Sync changes from upstream repository --- ...om-organization-api-responses-for-owner.md | 22 +++++++++++++++++++ content/v3/orgs.md | 6 +++++ 2 files changed, 28 insertions(+) create mode 100644 content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md diff --git a/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md b/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md new file mode 100644 index 0000000000..22f0e9cd3c --- /dev/null +++ b/content/changes/2016-08-09-breaking-change-removed-sensitive-fields-from-organization-api-responses-for-owner.md @@ -0,0 +1,22 @@ +--- +title: "Breaking change: Removed sensitive fields from Organization API responses for non-owners" +author_name: kdaigle +--- + +We're removing some values from [Organization API](https://developer.github.com/v3/orgs/) responses to help protect our +users' privacy. Previously, these fields were returned to all members of the organization. +As of today, you must be an Organization owner to +receive values for the following fields in Organization responses: + +* `private_gists` +* `disk_usage` +* `collaborators` +* `billing_email` + +If you're not an organization owner, the above keys will now return `null`. +We will continue to send these fields without their values to minimize the impact +of this change. + +If you have any questions or feedback, please [drop us a line][contact]. + +[contact]: https://github.com/contact?form[subject]=Removed+sensitive+fields+from+org+api diff --git a/content/v3/orgs.md b/content/v3/orgs.md index 3ba152583b..aa7419a031 100644 --- a/content/v3/orgs.md +++ b/content/v3/orgs.md @@ -61,6 +61,12 @@ This method only lists *public* memberships, regardless of authentication. If yo ## Get an organization +{% if page.version == 'dotcom' or page.version >= 2.8 %} +Note: To receive values for `private_gists`, `disk_usage`, `collaborators`, and +`billing_email` in the Organization response, the authenticated user must be an +organization owner and have authorized the `admin:org` scope. +{% endif %} + GET /orgs/:org ### Response From 084e21e2c4a5ed8cbc88f34f5b4f26b16dd4d5ea Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 15 Aug 2016 00:43:54 -0700 Subject: [PATCH 73/81] Sync changes from upstream repository --- content/v3/repos/branches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/repos/branches.md b/content/v3/repos/branches.md index 1c11628394..e620efd95c 100644 --- a/content/v3/repos/branches.md +++ b/content/v3/repos/branches.md @@ -228,7 +228,7 @@ Protecting a branch requires admin access. ### Parameters -You can pass two objects: `required_status_checks` and `restrictions`. Both can have the value `null` for disabled. +You must pass two objects: `required_status_checks` and `restrictions`. Both can have the value `null` for disabled. The `required_status_checks` object must have the following keys: From e0389e571a7f18fdccdebdd06dc67245c8357a5e Mon Sep 17 00:00:00 2001 From: Hubot Date: Mon, 15 Aug 2016 06:46:21 -0700 Subject: [PATCH 74/81] Sync changes from upstream repository --- .../changes/2016-08-15-traffic-api-preview.md | 18 ++++ content/v3/repos/traffic.md | 79 ++++++++++++++++ layouts/sidebar.html | 3 + lib/responses/traffic.rb | 94 +++++++++++++++++++ 4 files changed, 194 insertions(+) create mode 100644 content/changes/2016-08-15-traffic-api-preview.md create mode 100644 content/v3/repos/traffic.md create mode 100644 lib/responses/traffic.rb diff --git a/content/changes/2016-08-15-traffic-api-preview.md b/content/changes/2016-08-15-traffic-api-preview.md new file mode 100644 index 0000000000..60b089e380 --- /dev/null +++ b/content/changes/2016-08-15-traffic-api-preview.md @@ -0,0 +1,18 @@ +--- +title: Preview the Repository Traffic API +author_name: shreyasjoshis +--- + + We've added an API for repository traffic, which will let you fetch details about traffic for repositories you have push access to. This data is already available in graphical form in the [Graphs section](https://help.github.com/articles/about-repository-graphs/#traffic) on GitHub.com. + +To access [the Traffic API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header: + + application/vnd.github.spiderman-preview + +During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice. + +If you have any questions or feedback, please [let us know][contact]! + +[media-type]: /v3/media +[docs]: /v3/repos/traffic/ +[contact]: https://github.com/contact?form%5Bsubject%5D=Traffic+API diff --git a/content/v3/repos/traffic.md b/content/v3/repos/traffic.md new file mode 100644 index 0000000000..483197db77 --- /dev/null +++ b/content/v3/repos/traffic.md @@ -0,0 +1,79 @@ +--- +title: Traffic +--- + +# Traffic +{{#tip}} + + + + APIs for repository traffic are currently available for developers to preview. + During the preview period, the APIs may change without advance notice. + Please see the [blog post](/changes/2016-08-15-traffic-api-preview) for full details. + + To access the API you must provide a custom [media type](/v3/media) in the `Accept` header: + + application/vnd.github.spiderman-preview + +{{/tip}} + +{:toc} + +For repositories that you have push access to, the traffic API provides access +to the information provided in the [graphs section](https://help.github.com/articles/about-repository-graphs/#traffic). + + + +## List referrers + +Get the top 10 referrers over the last 14 days. + + GET /repos/:owner/:repo/traffic/popular/referrers + +### Response + +<%= headers 200 %> +<%= json(:traffic_referrers) %> + +## List paths + +Get the top 10 popular contents over the last 14 days. + + GET /repos/:owner/:repo/traffic/popular/paths + +### Response + +<%= headers 200%> +<%= json(:traffic_contents) %> + +## Views + +Get the total number of views and breakdown per day or week for the last 14 days. + + GET /repos/:owner/:repo/traffic/views + +### Parameters +Name | Type | Description +-----|------|-------------- +`per`|string|Must be one of: `day`, `week`. Default: `day` + + +### Response +<%= headers 200 %> +<%= json(:traffic_views) %> + +## Clones + +Get the total number of clones and breakdown per day or week for the last 14 days. + + GET /repos/:owner/:repo/traffic/clones + +### Parameters +Name | Type | Description +-----|------|-------------- +`per`|string|Must be one of: `day`, `week`. Default: `day` + +### Response + +<%= headers 200 %> +<%= json(:traffic_clones) %> diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 35dd666473..46f010e310 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -118,6 +118,9 @@

    Releases
  • Statistics
  • Statuses
    • + <% if @item[:version] == 'dotcom' %> +
  • Traffic
    • + <% end %>
  • Webhooks
    • <% if @item[:version].is_a?(Numeric) && @item[:version] >= 2.7 %>
  • Pre-receive Hooks (Enterprise)
    • diff --git a/lib/responses/traffic.rb b/lib/responses/traffic.rb new file mode 100644 index 0000000000..ff8e8cb0ba --- /dev/null +++ b/lib/responses/traffic.rb @@ -0,0 +1,94 @@ +module GitHub + module Resources + module Responses + + TRAFFIC_REFERRERS ||= [ + {"referrer" => "Google", "count" => 4, "uniques" => 3}, + {"referrer" => "stackoverflow.com", "count" => 2, "uniques" => 2}, + {"referrer" => "eggsonbread.com", "count" => 1, "uniques" => 1}, + {"referrer" => "yandex.ru", "count" => 1, "uniques" => 1}] + + TRAFFIC_CONTENTS ||= [ + { + "path" => "/github/hubot", + "title" => "github/hubot: A customizable life embetterment robot.", + "count" => 3542, + "uniques" => 2225 + }, + { + "path" => "/github/hubot/blob/master/docs/scripting.md", + "title" => "hubot/scripting.md at master · github/hubot · GitHub", + "count" => 1707, + "uniques" => 804 + }, + { + "path" => "/github/hubot/tree/master/docs", + "title" => "hubot/docs at master · github/hubot · GitHub", + "count" => 685, + "uniques" => 435 + }, + { + "path" => "/github/hubot/tree/master/src", + "title" => "hubot/src at master · github/hubot · GitHub", + "count" => 577, + "uniques" => 347 + }, + { + "path" => "/github/hubot/blob/master/docs/index.md", + "title" => "hubot/index.md at master · github/hubot · GitHub", + "count" => 379, + "uniques" => 259 + }, + { + "path" => "/github/hubot/blob/master/docs/adapters.md", + "title" => "hubot/adapters.md at master · github/hubot · GitHub", + "count" => 354, + "uniques" => 201 + }, + { + "path" => "/github/hubot/tree/master/examples", + "title" => "hubot/examples at master · github/hubot · GitHub", + "count" => 340, + "uniques" => 260 + }, + { + "path" => "/github/hubot/blob/master/docs/deploying/heroku.md", + "title" => "hubot/heroku.md at master · github/hubot · GitHub", + "count" => 324, + "uniques" => 217 + }, + { + "path" => "/github/hubot/blob/master/src/robot.coffee", + "title" => "hubot/robot.coffee at master · github/hubot · GitHub", + "count" => 293, + "uniques" => 191 + }, + { + "path" => "/github/hubot/blob/master/LICENSE.md", + "title" => "hubot/LICENSE.md at master · github/hubot · GitHub", + "count" => 281, + "uniques" => 222 + }] + + TRAFFIC_VIEWS ||= { + "count" => 7, + "uniques" => 6, + "views" => [ + {"timestamp" => 1464710400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1464732000000, "count" => 2, "uniques" => 1}, + {"timestamp" => 1465214400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465218000000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465300800000, "count" => 2, "uniques" => 2}]} + + TRAFFIC_CLONES ||= { + "count" => 7, + "uniques" => 6, + "clones" => [ + {"timestamp" => 1464710400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1464732000000, "count" => 2, "uniques" => 1}, + {"timestamp" => 1465214400000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465218000000, "count" => 1, "uniques" => 1}, + {"timestamp" => 1465300800000, "count" => 2, "uniques" => 2}]} + end + end +end From 3f411bda1309466a7fd1da5092801e52b0ef103f Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 16 Aug 2016 04:50:19 -0700 Subject: [PATCH 75/81] Sync changes from upstream repository --- content/v3/users.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v3/users.md b/content/v3/users.md index d8caa605d1..11e5479a4c 100644 --- a/content/v3/users.md +++ b/content/v3/users.md @@ -68,7 +68,7 @@ Name | Type | Description ## Get all users -Lists all users, in the order that they signed up on {{ site.data.variables.product.product_name }}. +Lists all users, in the order that they signed up on {{ site.data.variables.product.product_name }}. This list includes personal user accounts and organization accounts. Note: Pagination is powered exclusively by the `since` parameter. Use the [Link header](/v3/#link-header) to get the URL for the next page of From 9190dd5a0719f666bdcfe52e808d0ce0624cdedb Mon Sep 17 00:00:00 2001 From: Jeff Schering Date: Wed, 17 Aug 2016 10:42:15 -0700 Subject: [PATCH 76/81] Update basics-of-authentication.md Deleted an extra in the views/index.erb sample, line 68 --- content/guides/basics-of-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/basics-of-authentication.md b/content/guides/basics-of-authentication.md index 180f1a3ccd..f67f9e8f0e 100644 --- a/content/guides/basics-of-authentication.md +++ b/content/guides/basics-of-authentication.md @@ -65,7 +65,7 @@ Next, in _views/index.erb_, paste this content:

    We're going to now talk to the GitHub API. Ready? - Click here to begin! + Click here to begin!

    If that link doesn't work, remember to provide your own Client ID! From cb063a6aa0b6918b230934c6017160eb4c01cf2f Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 23 Aug 2016 14:51:30 -0700 Subject: [PATCH 77/81] Sync changes from upstream repository --- content/changes/2016-08-23-change-base.md | 25 +++++++++++++++++++++++ content/v3/pulls.md | 10 ++++++--- 2 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 content/changes/2016-08-23-change-base.md diff --git a/content/changes/2016-08-23-change-base.md b/content/changes/2016-08-23-change-base.md new file mode 100644 index 0000000000..a83f67b8e3 --- /dev/null +++ b/content/changes/2016-08-23-change-base.md @@ -0,0 +1,25 @@ +--- +title: API changes for changing the base branch on Pull Requests +author_name: scottjg +--- +GitHub recently added the ability to [change the base branch][blog post] on a Pull Request after it's created. Now we're updating the Pull Request API to enable the new functionality. + +For example: + +``` command-line +curl "https://api.github.com/repos/github/hubot/pulls/123" \ + -H 'Authorization: token TOKEN' \ + -d '{ "base": "master" }' +``` + +The Pull Request base will be updated to point to the master branch. + +You can learn more about the new responses and endpoints in the updated [Pull Request][pulls] documentation. + +If you have any questions or feedback, please [let us know][contact]! + + +[pulls]: /v3/pulls +[blog post]: https://github.com/blog/2224-change-the-base-branch-of-a-pull-request +[contact]: https://github.com/contact?form%5Bsubject%5D=Change+base+on+Pull+Requests + diff --git a/content/v3/pulls.md b/content/v3/pulls.md index 7d73679708..332c98ff3d 100644 --- a/content/v3/pulls.md +++ b/content/v3/pulls.md @@ -87,7 +87,7 @@ Name | Type | Description -----|------|------------- `title`|`string` | **Required**. The title of the pull request. `head`|`string` | **Required**. The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace `head` with a user like this: `username:branch`. -`base`|`string` | **Required**. The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository. +`base`|`string` | **Required**. The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository. `body`|`string` | The contents of the pull request. @@ -132,14 +132,18 @@ Name | Type | Description -----|------|-------------- `title`|`string` | The title of the pull request. `body`|`string` | The contents of the pull request. -`state`|`string` | State of this Pull Request. Either `open` or `closed`. +`state`|`string` | State of this Pull Request. Either `open` or `closed`.{% if page.version == 'dotcom' or page.version >= 2.8 %} +`base`|`string` | The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository. +{% endif %} #### Example <%= json \ :title => "new title", :body => "updated body", - :state => "open" + :state => "open"{% if page.version == 'dotcom' or page.version >= 2.8 %}, + :base => "master" +{% endif %} %> ### Response From 0e5a5b8fc39140d9688a2bbb0b999057adfecb1f Mon Sep 17 00:00:00 2001 From: Morton Fox Date: Wed, 31 Aug 2016 00:16:45 -0400 Subject: [PATCH 78/81] Update the pull request help link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a1e3bfcc9..fd73c1d298 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ This is a GitHub API resource built with [Nanoc][nanoc]. -All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](http://help.github.com/send-pull-requests/). +All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](https://help.github.com/articles/creating-a-pull-request/). ## Development From 6e3b1dac0fa8654fdd6503d17f9a6a4337ab69fd Mon Sep 17 00:00:00 2001 From: Garen Torikian Date: Fri, 2 Sep 2016 23:12:03 -0700 Subject: [PATCH 79/81] No longer necessary. --- CNAME | 1 - 1 file changed, 1 deletion(-) delete mode 100644 CNAME diff --git a/CNAME b/CNAME deleted file mode 100644 index 82c2e93c12..0000000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -developer.github.com From 64f712176ee30c47ea7a20231c38d72e61529e40 Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 8 Sep 2016 18:26:53 -0500 Subject: [PATCH 80/81] Update README --- README.md | 302 ++++++++++++++++++++++++------------------------------ 1 file changed, 136 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index fd73c1d298..620e7a2091 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,136 @@ -# developer.github.com [![Build Status](https://travis-ci.org/github/developer.github.com.svg?branch=master)](https://travis-ci.org/github/developer.github.com) - - -This is a GitHub API resource built with [Nanoc][nanoc]. - -All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](https://help.github.com/articles/creating-a-pull-request/). - -## Development - -You can fetch the latest dependencies by opening the command line and running `script/bootstrap`: - -``` sh -$ script/bootstrap -==> Installing gem dependencies… -==> Installing npm dependencies… -``` - -You'll need Ruby and Node installed on your system. The required versions for each of these languages can be found in the *.ruby-version* and *package.json* files, respectively. - -You can run `bundle exec rake build` to generate the site, but it's often more useful -to simply build the server *and* start the site at the same time. - -Nanoc compiles the site into static files living in `output`. It's -smart enough not to try to compile unchanged files. - -You can start the site with `script/server`: - -``` sh -$ script/server -Loading site data... -Compiling site... - create [0.28s] output/index.html - create [1.31s] output/v3/gists/comments/index.html - identical [1.92s] output/v3/gists/index.html - identical [0.25s] output/v3/issues/comments/index.html - update [0.99s] output/v3/issues/labels/index.html - update [0.05s] output/v3/index.html - … - -Site compiled in 5.81s. -``` - -The site is hosted at `http://localhost:4000`. - -Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about Nanoc. - -[nanoc]: http://nanoc.ws/ - -### Enterprise - -To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: - -``` sh -$ script/server 2.6 -``` - -Note that live reloading is not available for Enterprise documentation. - -## Styleguide - -Not sure how to structure the docs? Here's what the structure of the -API docs should look like: - - # API title - - {:toc} - - ## API endpoint title - - [VERB] /path/to/endpoint - - ### Parameters - - Name | Type | Description - -----|------|-------------- - `name`|`type` | Description. - - ### Input (request JSON body) - - Name | Type | Description - -----|------|-------------- - `name`|`type` | Description. - - ### Response - - <%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %> - <%= json :resource_name %> - -**Note**: We're using [Kramdown Markdown extensions](http://kramdown.gettalong.org/syntax.html), such as definition lists. - -### JSON Responses - -We specify the JSON responses in Ruby so that we don't have to write -them by hand all over the docs. You can render the JSON for a resource -like this: - -```erb -<%= json :issue %> -``` - -This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`. - -Some actions return arrays. You can modify the JSON by passing a block: - -```erb -<%= json(:issue) { |hash| [hash] } %> -``` - -There is also a rake task for generating JSON files from the sample responses in the documentation: - -``` sh -$ rake generate_json_from_responses -``` - -The generated files will end up in *json-dump/*. - -### Terminal blocks - -You can specify terminal blocks by using the `command-line` syntax highlighting. - - ``` command-line - $ curl foobar - ``` - -You can use certain characters, like `$` and `#`, to emphasize different parts -of commands. - - ``` command-line - # call foobar - $ curl foobar - .... - ``` - -For more information, see [the reference documentation](https://github.com/gjtorikian/extended-markdown-filter#command-line-highlighting). - -## Deploy - -Deployments happen automatically once a PR is merged into `master`. A tool called [Publisher](https://github.com/gjtorikian/publisher) takes the `master` branch, builds it using Nanoc, and publishes the content to `gh-pages`. Thus, any commit to `master` is automatically sent over to `gh-pages`, where it's picked up and served by GitHub Pages. - -## Licenses - -The code to generate the site (everything excluding the assets, content, -and layouts directories) as well as the code samples on the site are -licensed under -[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode). -CC0 waives all copyright restrictions but does not grant you any trademark -permissions. - -Site content (everything in the assets, content, and layouts directories, -excluding files under open source licenses individually marked) is licensed -under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). CC-BY-4.0 -gives you permission to use content for almost any purpose but does not grant -you any trademark permissions, so long as you note the license and give credit, -such as follows: - -> Content based on -> developer.github.com -> used under the -> CC-BY-4.0 -> license. - -This means you can use the code and content in this repository except for -GitHub trademarks in your own projects. - -When you contribute to this repository you are doing so under the above -licenses. +IyBkZXZlbG9wZXIuZ2l0aHViLmNvbQoKKipOT1RFOiBUaGUgZGV2ZWxvcGVy +LmdpdGh1Yi5jb20gd2Vic2l0ZSBpcyBubyBsb25nZXIgb3Blbi1zb3VyY2Uu +KioKCldlIGhhdmUgbW92ZWQgdGhpcyByZXBvc2l0b3J5IGludG8gW291ciBn +aXRodWItYXJjaGl2ZSBvcmdhbml6YXRpb25dKGh0dHBzOi8vZ2l0aHViLmNv +bS9naXRodWItYXJjaGl2ZSkgdG8gc2lnbmlmeSB0aGF0IHdlIGFyZSBubyBs +b25nZXIgYWNjZXB0aW5nIG9wZW4tc291cmNlIGNvbnRyaWJ1dGlvbnMgdG8g +dGhpcyByZXBvc2l0b3J5LiBXZSB3YW50IHRvIHRoYW5rIHRoZSBodW5kcmVk +cyBvZiBjb250cmlidXRvcnMgZm9yIHRoZWlyIGFzc2lzdGFuY2Ugb3ZlciB0 +aGUgeWVhcnMuCgpUaGUgZGVjaXNpb24gdG8gY2xvc2Utc291cmNlIHRoZSBz +aXRlIHN0ZW1zIGZyb20gYSB2YXJpZXR5IG9mIHJlYXNvbnM6CgoxLiBXZSBh +Y3R1YWxseSBhbHJlYWR5IF9oYXZlXyBhIGNsb3NlLXNvdXJjZWQgc2l0ZSwg +d2hpY2ggaXMgd2hlcmUgd2Ugd3JvdGUgZG9jdW1lbnRhdGlvbiBmb3IgdW5y +ZWxlYXNlZCBmZWF0dXJlcy4gV2UgZGVzaWduZWQgYWRkaXRpb25hbCB0b29s +aW5nIHRvIHN1cHBvcnQgdGhpcyB3b3JrZmxvdywgYnV0IHVwZGF0aW5nIHRo +ZSBkb2N1bWVudGF0aW9uIGlzIGEgcHJvY2VzcyB3ZSdkIGxpa2UgdG8gc2lt +cGxpZnkuCjIuIFdlIGJlbGlldmUgdGhhdCBhbnkgb3Blbi1zb3VyY2UgcHJv +amVjdOKAlGJlIGl0IGRvY3VtZW50YXRpb24gb3Igc29mdHdhcmXigJRvdWdo +dCB0byBoYXZlIGRlZGljYXRlZCBtYWludGFpbmVycy4gSXQgYmVjYW1lIGRp +ZmZpY3VsdCB0byBrZWVwIHRoaXMgcmVwb3NpdG9yeSBvcGVuLXNvdXJjZSBi +ZWNhdXNlIGl0IHdhcyBtYWludGFpbmVkIGJ5IHRoZSBiZXN0IGVmZm9ydHMg +b2YgYSBzbWFsbCBncm91cCBvZiBwZW9wbGUuIENsb3NpbmcgdGhlIHNpdGUg +YWxsb3dzIHVzIHRvIGZvY3VzIG9uIHdoYXQncyBpbXBvcnRhbnQsIHdpdGhv +dXQgZmVlbGluZyBndWlsdHkgYXQgbWlzc2luZyByZXZpZXdzIGZyb20gb3Bl +bi1zb3VyY2UgY29udHJpYnV0b3JzLgoKV2UgdGhpbmsgdGhhdCB0aGUgdG9v +bGluZyB3ZSB1c2VkIHRvIGJ1aWxkIHRoaXMgc2l0ZSBpcyBwcmV0dHkgaW50 +ZXJlc3RpbmcsIHNvIHdlJ3JlIG5vdCBnZXR0aW5nIHJpZCBvZiBldmVyeXRo +aW5nLiBXZSBob3BlIHRoYXQgd2hhdCByZW1haW5zIGNhbiBiZSB1c2VkIGFz +IGEgc291cmNlIG9mIGluc3BpcmF0aW9uIGZvciB5b3VyIG93biBzdGF0aWMg +c2l0ZS4KCklmIHlvdSBmaW5kIHNvbWV0aGluZyB0aGF0IG5lZWRzIHRvIGJl +IGZpeGVkLCB5b3UgY2FuIGFsd2F5cyBbY29udGFjdCBvdXIgdGVycmlmaWMg +U3VwcG9ydCB0ZWFtXShodHRwczovL2dpdGh1Yi5jb20vY29udGFjdD9mb3Jt +JTVCc3ViamVjdCU1RD1Nb3ZpbmcrZGV2ZWxvcGVyLmdpdGh1Yi5jb20rdG8r +Z2l0aHViLWFyY2hpdmUpLgoKVGhhbmsgeW91IQoKKiAqICoKClRoaXMgd2Fz +IHRoZSBHaXRIdWIgQVBJIGRvY3VtZW50YXRpb24sIGJ1aWx0IHdpdGggW05h +bm9jXVtuYW5vY10uCgojIyBEZXZlbG9wbWVudAoKWW91IGNhbiBmZXRjaCB0 +aGUgbGF0ZXN0IGRlcGVuZGVuY2llcyBieSBvcGVuaW5nIHRoZSBjb21tYW5k +IGxpbmUgYW5kIHJ1bm5pbmcgYHNjcmlwdC9ib290c3RyYXBgOgoKYGBgIHNo +CiQgc2NyaXB0L2Jvb3RzdHJhcAo9PT4gSW5zdGFsbGluZyBnZW0gZGVwZW5k +ZW5jaWVz4oCmCj09PiBJbnN0YWxsaW5nIG5wbSBkZXBlbmRlbmNpZXPigKYK +YGBgCgpZb3UnbGwgbmVlZCBSdWJ5IGFuZCBOb2RlIGluc3RhbGxlZCBvbiB5 +b3VyIHN5c3RlbS4gVGhlIHJlcXVpcmVkIHZlcnNpb25zIGZvciBlYWNoIG9m +IHRoZXNlIGxhbmd1YWdlcyBjYW4gYmUgZm91bmQgaW4gdGhlICoucnVieS12 +ZXJzaW9uKiBhbmQgKnBhY2thZ2UuanNvbiogZmlsZXMsIHJlc3BlY3RpdmVs +eS4KCllvdSBjYW4gcnVuIGBidW5kbGUgZXhlYyByYWtlIGJ1aWxkYCB0byBn +ZW5lcmF0ZSB0aGUgc2l0ZSwgYnV0IGl0J3Mgb2Z0ZW4gbW9yZSB1c2VmdWwK +dG8gc2ltcGx5IGJ1aWxkIHRoZSBzZXJ2ZXIgKmFuZCogc3RhcnQgdGhlIHNp +dGUgYXQgdGhlIHNhbWUgdGltZS4KCk5hbm9jIGNvbXBpbGVzIHRoZSBzaXRl +IGludG8gc3RhdGljIGZpbGVzIGxpdmluZyBpbiBgb3V0cHV0YC4gIEl0J3MK +c21hcnQgZW5vdWdoIG5vdCB0byB0cnkgdG8gY29tcGlsZSB1bmNoYW5nZWQg +ZmlsZXMuCgpZb3UgY2FuIHN0YXJ0IHRoZSBzaXRlIHdpdGggYHNjcmlwdC9z +ZXJ2ZXJgOgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlcgpMb2FkaW5nIHNpdGUg +ZGF0YS4uLgpDb21waWxpbmcgc2l0ZS4uLgogICBjcmVhdGUgICAgIFswLjI4 +c10gIG91dHB1dC9pbmRleC5odG1sCiAgIGNyZWF0ZSAgICAgWzEuMzFzXSAg +b3V0cHV0L3YzL2dpc3RzL2NvbW1lbnRzL2luZGV4Lmh0bWwKICAgaWRlbnRp +Y2FsICBbMS45MnNdICBvdXRwdXQvdjMvZ2lzdHMvaW5kZXguaHRtbAogICBp +ZGVudGljYWwgIFswLjI1c10gIG91dHB1dC92My9pc3N1ZXMvY29tbWVudHMv +aW5kZXguaHRtbAogICB1cGRhdGUgICAgIFswLjk5c10gIG91dHB1dC92My9p +c3N1ZXMvbGFiZWxzL2luZGV4Lmh0bWwKICAgdXBkYXRlICAgICBbMC4wNXNd +ICBvdXRwdXQvdjMvaW5kZXguaHRtbAogICDigKYKClNpdGUgY29tcGlsZWQg +aW4gNS44MXMuCmBgYAoKVGhlIHNpdGUgaXMgaG9zdGVkIGF0IGBodHRwOi8v +bG9jYWxob3N0OjQwMDBgLgoKTmFub2MgaGFzIFtzb21lIG5pY2UgZG9jdW1l +bnRhdGlvbl0oaHR0cDovL25hbm9jLndzL2RvY3MvdHV0b3JpYWwvKSB0byBn +ZXQgeW91IHN0YXJ0ZWQuICBUaG91Z2ggaWYgeW91J3JlIG1haW5seSBjb25j +ZXJuZWQgd2l0aCBlZGl0aW5nIG9yIGFkZGluZyBjb250ZW50LCB5b3Ugd29u +J3QgbmVlZCB0byBrbm93IG11Y2ggYWJvdXQgTmFub2MuCgpbbmFub2NdOiBo +dHRwOi8vbmFub2Mud3MvCgojIyMgRW50ZXJwcmlzZQoKVG8gZ2VuZXJhdGUg +dGhlIGAvZW50ZXJwcmlzZWAgdmVyc2lvbnMsIHBhc3MgaW4gdGhlIEVudGVy +cHJpc2UgdmVyc2lvbiB0byBgc2NyaXB0L3NlcnZlcmAuIEZvciBleGFtcGxl +OgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlciAyLjYKYGBgCgpOb3RlIHRoYXQg +bGl2ZSByZWxvYWRpbmcgaXMgbm90IGF2YWlsYWJsZSBmb3IgRW50ZXJwcmlz +ZSBkb2N1bWVudGF0aW9uLgoKIyMgU3R5bGVndWlkZQoKTm90IHN1cmUgaG93 +IHRvIHN0cnVjdHVyZSB0aGUgZG9jcz8gIEhlcmUncyB3aGF0IHRoZSBzdHJ1 +Y3R1cmUgb2YgdGhlCkFQSSBkb2NzIHNob3VsZCBsb29rIGxpa2U6CgogICAg +IyBBUEkgdGl0bGUKCiAgICB7OnRvY30KCiAgICAjIyBBUEkgZW5kcG9pbnQg +dGl0bGUKCiAgICAgICAgW1ZFUkJdIC9wYXRoL3RvL2VuZHBvaW50CgogICAg +IyMjIFBhcmFtZXRlcnMKCiAgICBOYW1lIHwgVHlwZSB8IERlc2NyaXB0aW9u +CiAgICAtLS0tLXwtLS0tLS18LS0tLS0tLS0tLS0tLS0KICAgIGBuYW1lYHxg +dHlwZWAgfCBEZXNjcmlwdGlvbi4KCiAgICAjIyMgSW5wdXQgKHJlcXVlc3Qg +SlNPTiBib2R5KQoKICAgIE5hbWUgfCBUeXBlIHwgRGVzY3JpcHRpb24KICAg +IC0tLS0tfC0tLS0tLXwtLS0tLS0tLS0tLS0tLQogICAgYG5hbWVgfGB0eXBl +YCB8IERlc2NyaXB0aW9uLgoKICAgICMjIyBSZXNwb25zZQoKICAgIDwlPSBo +ZWFkZXJzIDIwMCwgOnBhZ2luYXRpb24gPT4gZGVmYXVsdF9wYWdpbmF0aW9u +X3JlbHMsICdYLUN1c3RvbS1IZWFkZXInID0+ICJ2YWx1ZSIgJT4KICAgIDwl +PSBqc29uIDpyZXNvdXJjZV9uYW1lICU+CgoqKk5vdGUqKjogV2UncmUgdXNp +bmcgW0tyYW1kb3duIE1hcmtkb3duIGV4dGVuc2lvbnNdKGh0dHA6Ly9rcmFt +ZG93bi5nZXR0YWxvbmcub3JnL3N5bnRheC5odG1sKSwgc3VjaCBhcyBkZWZp +bml0aW9uIGxpc3RzLgoKIyMjIEpTT04gUmVzcG9uc2VzCgpXZSBzcGVjaWZ5 +IHRoZSBKU09OIHJlc3BvbnNlcyBpbiBSdWJ5IHNvIHRoYXQgd2UgZG9uJ3Qg +aGF2ZSB0byB3cml0ZQp0aGVtIGJ5IGhhbmQgYWxsIG92ZXIgdGhlIGRvY3Mu +ICBZb3UgY2FuIHJlbmRlciB0aGUgSlNPTiBmb3IgYSByZXNvdXJjZQpsaWtl +IHRoaXM6CgpgYGBlcmIKPCU9IGpzb24gOmlzc3VlICU+CmBgYAoKVGhpcyBs +b29rcyB1cCBgR2l0SHViOjpSZXNvdXJjZXM6OklTU1VFYCBpbiBgbGliL3Jl +c291cmNlcy5yYmAuCgpTb21lIGFjdGlvbnMgcmV0dXJuIGFycmF5cy4gIFlv +dSBjYW4gbW9kaWZ5IHRoZSBKU09OIGJ5IHBhc3NpbmcgYSBibG9jazoKCmBg +YGVyYgo8JT0ganNvbig6aXNzdWUpIHsgfGhhc2h8IFtoYXNoXSB9ICU+CmBg +YAoKVGhlcmUgaXMgYWxzbyBhIHJha2UgdGFzayBmb3IgZ2VuZXJhdGluZyBK +U09OIGZpbGVzIGZyb20gdGhlIHNhbXBsZSByZXNwb25zZXMgaW4gdGhlIGRv +Y3VtZW50YXRpb246CgpgYGAgc2gKJCByYWtlIGdlbmVyYXRlX2pzb25fZnJv +bV9yZXNwb25zZXMKYGBgCgpUaGUgZ2VuZXJhdGVkIGZpbGVzIHdpbGwgZW5k +IHVwIGluICpqc29uLWR1bXAvKi4KCiMjIyBUZXJtaW5hbCBibG9ja3MKCllv +dSBjYW4gc3BlY2lmeSB0ZXJtaW5hbCBibG9ja3MgYnkgdXNpbmcgdGhlIGBj +b21tYW5kLWxpbmVgIHN5bnRheCBoaWdobGlnaHRpbmcuCgogICAgYGBgIGNv +bW1hbmQtbGluZQogICAgJCBjdXJsIGZvb2JhcgogICAgYGBgCgpZb3UgY2Fu +IHVzZSBjZXJ0YWluIGNoYXJhY3RlcnMsIGxpa2UgYCRgIGFuZCBgI2AsIHRv +IGVtcGhhc2l6ZSBkaWZmZXJlbnQgcGFydHMKb2YgY29tbWFuZHMuCgogICAg +YGBgIGNvbW1hbmQtbGluZQogICAgIyBjYWxsIGZvb2JhcgogICAgJCBjdXJs +IDxlbT5mb29iYXI8ZW0+CiAgICAuLi4uCiAgICBgYGAKCkZvciBtb3JlIGlu +Zm9ybWF0aW9uLCBzZWUgW3RoZSByZWZlcmVuY2UgZG9jdW1lbnRhdGlvbl0o +aHR0cHM6Ly9naXRodWIuY29tL2dqdG9yaWtpYW4vZXh0ZW5kZWQtbWFya2Rv +d24tZmlsdGVyI2NvbW1hbmQtbGluZS1oaWdobGlnaHRpbmcpLgoKIyMgTGlj +ZW5zZXMKClRoZSBjb2RlIHRvIGdlbmVyYXRlIHRoZSBzaXRlIChldmVyeXRo +aW5nIGV4Y2x1ZGluZyB0aGUgYXNzZXRzLCBjb250ZW50LAphbmQgbGF5b3V0 +cyBkaXJlY3RvcmllcykgYXMgd2VsbCBhcyB0aGUgY29kZSBzYW1wbGVzIG9u +IHRoZSBzaXRlIGFyZQpsaWNlbnNlZCB1bmRlcgpbQ0MwLTEuMF0oaHR0cHM6 +Ly9jcmVhdGl2ZWNvbW1vbnMub3JnL3B1YmxpY2RvbWFpbi96ZXJvLzEuMC9s +ZWdhbGNvZGUpLgpDQzAgd2FpdmVzIGFsbCBjb3B5cmlnaHQgcmVzdHJpY3Rp +b25zIGJ1dCBkb2VzIG5vdCBncmFudCB5b3UgYW55IHRyYWRlbWFyawpwZXJt +aXNzaW9ucy4KClNpdGUgY29udGVudCAoZXZlcnl0aGluZyBpbiB0aGUgYXNz +ZXRzLCBjb250ZW50LCBhbmQgbGF5b3V0cyBkaXJlY3RvcmllcywKZXhjbHVk +aW5nIGZpbGVzIHVuZGVyIG9wZW4gc291cmNlIGxpY2Vuc2VzIGluZGl2aWR1 +YWxseSBtYXJrZWQpIGlzIGxpY2Vuc2VkCnVuZGVyIFtDQy1CWS00LjBdKGh0 +dHBzOi8vY3JlYXRpdmVjb21tb25zLm9yZy9saWNlbnNlcy9ieS80LjAvKS4g +Q0MtQlktNC4wCmdpdmVzIHlvdSBwZXJtaXNzaW9uIHRvIHVzZSBjb250ZW50 +IGZvciBhbG1vc3QgYW55IHB1cnBvc2UgYnV0IGRvZXMgbm90IGdyYW50Cnlv +dSBhbnkgdHJhZGVtYXJrIHBlcm1pc3Npb25zLCBzbyBsb25nIGFzIHlvdSBu +b3RlIHRoZSBsaWNlbnNlIGFuZCBnaXZlIGNyZWRpdCwKc3VjaCBhcyBmb2xs +b3dzOgoKPiBDb250ZW50IGJhc2VkIG9uCj4gPGEgaHJlZj0iaHR0cHM6Ly9n +aXRodWIuY29tL2dpdGh1Yi9kZXZlbG9wZXIuZ2l0aHViLmNvbSI+ZGV2ZWxv +cGVyLmdpdGh1Yi5jb208L2E+Cj4gdXNlZCB1bmRlciB0aGUKPiA8YSBocmVm +PSJodHRwczovL2NyZWF0aXZlY29tbW9ucy5vcmcvbGljZW5zZXMvYnkvNC4w +LyI+Q0MtQlktNC4wPC9hPgo+IGxpY2Vuc2UuPC9hPgoKVGhpcyBtZWFucyB5 +b3UgY2FuIHVzZSB0aGUgY29kZSBhbmQgY29udGVudCBpbiB0aGlzIHJlcG9z +aXRvcnkgZXhjZXB0IGZvcgpHaXRIdWIgdHJhZGVtYXJrcyBpbiB5b3VyIG93 +biBwcm9qZWN0cy4KCldoZW4geW91IGNvbnRyaWJ1dGUgdG8gdGhpcyByZXBv +c2l0b3J5IHlvdSBhcmUgZG9pbmcgc28gdW5kZXIgdGhlIGFib3ZlCmxpY2Vu +c2VzLgo= From a03030dea7be744a3feff20ea29f51783f37a47f Mon Sep 17 00:00:00 2001 From: Hubot Date: Thu, 8 Sep 2016 18:27:26 -0500 Subject: [PATCH 81/81] Update README --- README.md | 312 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 176 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index 620e7a2091..d73feafde0 100644 --- a/README.md +++ b/README.md @@ -1,136 +1,176 @@ -IyBkZXZlbG9wZXIuZ2l0aHViLmNvbQoKKipOT1RFOiBUaGUgZGV2ZWxvcGVy -LmdpdGh1Yi5jb20gd2Vic2l0ZSBpcyBubyBsb25nZXIgb3Blbi1zb3VyY2Uu -KioKCldlIGhhdmUgbW92ZWQgdGhpcyByZXBvc2l0b3J5IGludG8gW291ciBn -aXRodWItYXJjaGl2ZSBvcmdhbml6YXRpb25dKGh0dHBzOi8vZ2l0aHViLmNv -bS9naXRodWItYXJjaGl2ZSkgdG8gc2lnbmlmeSB0aGF0IHdlIGFyZSBubyBs -b25nZXIgYWNjZXB0aW5nIG9wZW4tc291cmNlIGNvbnRyaWJ1dGlvbnMgdG8g -dGhpcyByZXBvc2l0b3J5LiBXZSB3YW50IHRvIHRoYW5rIHRoZSBodW5kcmVk -cyBvZiBjb250cmlidXRvcnMgZm9yIHRoZWlyIGFzc2lzdGFuY2Ugb3ZlciB0 -aGUgeWVhcnMuCgpUaGUgZGVjaXNpb24gdG8gY2xvc2Utc291cmNlIHRoZSBz -aXRlIHN0ZW1zIGZyb20gYSB2YXJpZXR5IG9mIHJlYXNvbnM6CgoxLiBXZSBh -Y3R1YWxseSBhbHJlYWR5IF9oYXZlXyBhIGNsb3NlLXNvdXJjZWQgc2l0ZSwg -d2hpY2ggaXMgd2hlcmUgd2Ugd3JvdGUgZG9jdW1lbnRhdGlvbiBmb3IgdW5y -ZWxlYXNlZCBmZWF0dXJlcy4gV2UgZGVzaWduZWQgYWRkaXRpb25hbCB0b29s -aW5nIHRvIHN1cHBvcnQgdGhpcyB3b3JrZmxvdywgYnV0IHVwZGF0aW5nIHRo -ZSBkb2N1bWVudGF0aW9uIGlzIGEgcHJvY2VzcyB3ZSdkIGxpa2UgdG8gc2lt -cGxpZnkuCjIuIFdlIGJlbGlldmUgdGhhdCBhbnkgb3Blbi1zb3VyY2UgcHJv -amVjdOKAlGJlIGl0IGRvY3VtZW50YXRpb24gb3Igc29mdHdhcmXigJRvdWdo -dCB0byBoYXZlIGRlZGljYXRlZCBtYWludGFpbmVycy4gSXQgYmVjYW1lIGRp -ZmZpY3VsdCB0byBrZWVwIHRoaXMgcmVwb3NpdG9yeSBvcGVuLXNvdXJjZSBi -ZWNhdXNlIGl0IHdhcyBtYWludGFpbmVkIGJ5IHRoZSBiZXN0IGVmZm9ydHMg -b2YgYSBzbWFsbCBncm91cCBvZiBwZW9wbGUuIENsb3NpbmcgdGhlIHNpdGUg -YWxsb3dzIHVzIHRvIGZvY3VzIG9uIHdoYXQncyBpbXBvcnRhbnQsIHdpdGhv -dXQgZmVlbGluZyBndWlsdHkgYXQgbWlzc2luZyByZXZpZXdzIGZyb20gb3Bl -bi1zb3VyY2UgY29udHJpYnV0b3JzLgoKV2UgdGhpbmsgdGhhdCB0aGUgdG9v -bGluZyB3ZSB1c2VkIHRvIGJ1aWxkIHRoaXMgc2l0ZSBpcyBwcmV0dHkgaW50 -ZXJlc3RpbmcsIHNvIHdlJ3JlIG5vdCBnZXR0aW5nIHJpZCBvZiBldmVyeXRo -aW5nLiBXZSBob3BlIHRoYXQgd2hhdCByZW1haW5zIGNhbiBiZSB1c2VkIGFz -IGEgc291cmNlIG9mIGluc3BpcmF0aW9uIGZvciB5b3VyIG93biBzdGF0aWMg -c2l0ZS4KCklmIHlvdSBmaW5kIHNvbWV0aGluZyB0aGF0IG5lZWRzIHRvIGJl -IGZpeGVkLCB5b3UgY2FuIGFsd2F5cyBbY29udGFjdCBvdXIgdGVycmlmaWMg -U3VwcG9ydCB0ZWFtXShodHRwczovL2dpdGh1Yi5jb20vY29udGFjdD9mb3Jt -JTVCc3ViamVjdCU1RD1Nb3ZpbmcrZGV2ZWxvcGVyLmdpdGh1Yi5jb20rdG8r -Z2l0aHViLWFyY2hpdmUpLgoKVGhhbmsgeW91IQoKKiAqICoKClRoaXMgd2Fz -IHRoZSBHaXRIdWIgQVBJIGRvY3VtZW50YXRpb24sIGJ1aWx0IHdpdGggW05h -bm9jXVtuYW5vY10uCgojIyBEZXZlbG9wbWVudAoKWW91IGNhbiBmZXRjaCB0 -aGUgbGF0ZXN0IGRlcGVuZGVuY2llcyBieSBvcGVuaW5nIHRoZSBjb21tYW5k -IGxpbmUgYW5kIHJ1bm5pbmcgYHNjcmlwdC9ib290c3RyYXBgOgoKYGBgIHNo -CiQgc2NyaXB0L2Jvb3RzdHJhcAo9PT4gSW5zdGFsbGluZyBnZW0gZGVwZW5k -ZW5jaWVz4oCmCj09PiBJbnN0YWxsaW5nIG5wbSBkZXBlbmRlbmNpZXPigKYK -YGBgCgpZb3UnbGwgbmVlZCBSdWJ5IGFuZCBOb2RlIGluc3RhbGxlZCBvbiB5 -b3VyIHN5c3RlbS4gVGhlIHJlcXVpcmVkIHZlcnNpb25zIGZvciBlYWNoIG9m -IHRoZXNlIGxhbmd1YWdlcyBjYW4gYmUgZm91bmQgaW4gdGhlICoucnVieS12 -ZXJzaW9uKiBhbmQgKnBhY2thZ2UuanNvbiogZmlsZXMsIHJlc3BlY3RpdmVs -eS4KCllvdSBjYW4gcnVuIGBidW5kbGUgZXhlYyByYWtlIGJ1aWxkYCB0byBn -ZW5lcmF0ZSB0aGUgc2l0ZSwgYnV0IGl0J3Mgb2Z0ZW4gbW9yZSB1c2VmdWwK -dG8gc2ltcGx5IGJ1aWxkIHRoZSBzZXJ2ZXIgKmFuZCogc3RhcnQgdGhlIHNp -dGUgYXQgdGhlIHNhbWUgdGltZS4KCk5hbm9jIGNvbXBpbGVzIHRoZSBzaXRl -IGludG8gc3RhdGljIGZpbGVzIGxpdmluZyBpbiBgb3V0cHV0YC4gIEl0J3MK -c21hcnQgZW5vdWdoIG5vdCB0byB0cnkgdG8gY29tcGlsZSB1bmNoYW5nZWQg -ZmlsZXMuCgpZb3UgY2FuIHN0YXJ0IHRoZSBzaXRlIHdpdGggYHNjcmlwdC9z -ZXJ2ZXJgOgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlcgpMb2FkaW5nIHNpdGUg -ZGF0YS4uLgpDb21waWxpbmcgc2l0ZS4uLgogICBjcmVhdGUgICAgIFswLjI4 -c10gIG91dHB1dC9pbmRleC5odG1sCiAgIGNyZWF0ZSAgICAgWzEuMzFzXSAg -b3V0cHV0L3YzL2dpc3RzL2NvbW1lbnRzL2luZGV4Lmh0bWwKICAgaWRlbnRp -Y2FsICBbMS45MnNdICBvdXRwdXQvdjMvZ2lzdHMvaW5kZXguaHRtbAogICBp -ZGVudGljYWwgIFswLjI1c10gIG91dHB1dC92My9pc3N1ZXMvY29tbWVudHMv -aW5kZXguaHRtbAogICB1cGRhdGUgICAgIFswLjk5c10gIG91dHB1dC92My9p -c3N1ZXMvbGFiZWxzL2luZGV4Lmh0bWwKICAgdXBkYXRlICAgICBbMC4wNXNd -ICBvdXRwdXQvdjMvaW5kZXguaHRtbAogICDigKYKClNpdGUgY29tcGlsZWQg -aW4gNS44MXMuCmBgYAoKVGhlIHNpdGUgaXMgaG9zdGVkIGF0IGBodHRwOi8v -bG9jYWxob3N0OjQwMDBgLgoKTmFub2MgaGFzIFtzb21lIG5pY2UgZG9jdW1l -bnRhdGlvbl0oaHR0cDovL25hbm9jLndzL2RvY3MvdHV0b3JpYWwvKSB0byBn -ZXQgeW91IHN0YXJ0ZWQuICBUaG91Z2ggaWYgeW91J3JlIG1haW5seSBjb25j -ZXJuZWQgd2l0aCBlZGl0aW5nIG9yIGFkZGluZyBjb250ZW50LCB5b3Ugd29u -J3QgbmVlZCB0byBrbm93IG11Y2ggYWJvdXQgTmFub2MuCgpbbmFub2NdOiBo -dHRwOi8vbmFub2Mud3MvCgojIyMgRW50ZXJwcmlzZQoKVG8gZ2VuZXJhdGUg -dGhlIGAvZW50ZXJwcmlzZWAgdmVyc2lvbnMsIHBhc3MgaW4gdGhlIEVudGVy -cHJpc2UgdmVyc2lvbiB0byBgc2NyaXB0L3NlcnZlcmAuIEZvciBleGFtcGxl -OgoKYGBgIHNoCiQgc2NyaXB0L3NlcnZlciAyLjYKYGBgCgpOb3RlIHRoYXQg -bGl2ZSByZWxvYWRpbmcgaXMgbm90IGF2YWlsYWJsZSBmb3IgRW50ZXJwcmlz -ZSBkb2N1bWVudGF0aW9uLgoKIyMgU3R5bGVndWlkZQoKTm90IHN1cmUgaG93 -IHRvIHN0cnVjdHVyZSB0aGUgZG9jcz8gIEhlcmUncyB3aGF0IHRoZSBzdHJ1 -Y3R1cmUgb2YgdGhlCkFQSSBkb2NzIHNob3VsZCBsb29rIGxpa2U6CgogICAg -IyBBUEkgdGl0bGUKCiAgICB7OnRvY30KCiAgICAjIyBBUEkgZW5kcG9pbnQg -dGl0bGUKCiAgICAgICAgW1ZFUkJdIC9wYXRoL3RvL2VuZHBvaW50CgogICAg -IyMjIFBhcmFtZXRlcnMKCiAgICBOYW1lIHwgVHlwZSB8IERlc2NyaXB0aW9u -CiAgICAtLS0tLXwtLS0tLS18LS0tLS0tLS0tLS0tLS0KICAgIGBuYW1lYHxg -dHlwZWAgfCBEZXNjcmlwdGlvbi4KCiAgICAjIyMgSW5wdXQgKHJlcXVlc3Qg -SlNPTiBib2R5KQoKICAgIE5hbWUgfCBUeXBlIHwgRGVzY3JpcHRpb24KICAg -IC0tLS0tfC0tLS0tLXwtLS0tLS0tLS0tLS0tLQogICAgYG5hbWVgfGB0eXBl -YCB8IERlc2NyaXB0aW9uLgoKICAgICMjIyBSZXNwb25zZQoKICAgIDwlPSBo -ZWFkZXJzIDIwMCwgOnBhZ2luYXRpb24gPT4gZGVmYXVsdF9wYWdpbmF0aW9u -X3JlbHMsICdYLUN1c3RvbS1IZWFkZXInID0+ICJ2YWx1ZSIgJT4KICAgIDwl -PSBqc29uIDpyZXNvdXJjZV9uYW1lICU+CgoqKk5vdGUqKjogV2UncmUgdXNp -bmcgW0tyYW1kb3duIE1hcmtkb3duIGV4dGVuc2lvbnNdKGh0dHA6Ly9rcmFt -ZG93bi5nZXR0YWxvbmcub3JnL3N5bnRheC5odG1sKSwgc3VjaCBhcyBkZWZp -bml0aW9uIGxpc3RzLgoKIyMjIEpTT04gUmVzcG9uc2VzCgpXZSBzcGVjaWZ5 -IHRoZSBKU09OIHJlc3BvbnNlcyBpbiBSdWJ5IHNvIHRoYXQgd2UgZG9uJ3Qg -aGF2ZSB0byB3cml0ZQp0aGVtIGJ5IGhhbmQgYWxsIG92ZXIgdGhlIGRvY3Mu -ICBZb3UgY2FuIHJlbmRlciB0aGUgSlNPTiBmb3IgYSByZXNvdXJjZQpsaWtl -IHRoaXM6CgpgYGBlcmIKPCU9IGpzb24gOmlzc3VlICU+CmBgYAoKVGhpcyBs -b29rcyB1cCBgR2l0SHViOjpSZXNvdXJjZXM6OklTU1VFYCBpbiBgbGliL3Jl -c291cmNlcy5yYmAuCgpTb21lIGFjdGlvbnMgcmV0dXJuIGFycmF5cy4gIFlv -dSBjYW4gbW9kaWZ5IHRoZSBKU09OIGJ5IHBhc3NpbmcgYSBibG9jazoKCmBg -YGVyYgo8JT0ganNvbig6aXNzdWUpIHsgfGhhc2h8IFtoYXNoXSB9ICU+CmBg -YAoKVGhlcmUgaXMgYWxzbyBhIHJha2UgdGFzayBmb3IgZ2VuZXJhdGluZyBK -U09OIGZpbGVzIGZyb20gdGhlIHNhbXBsZSByZXNwb25zZXMgaW4gdGhlIGRv -Y3VtZW50YXRpb246CgpgYGAgc2gKJCByYWtlIGdlbmVyYXRlX2pzb25fZnJv -bV9yZXNwb25zZXMKYGBgCgpUaGUgZ2VuZXJhdGVkIGZpbGVzIHdpbGwgZW5k -IHVwIGluICpqc29uLWR1bXAvKi4KCiMjIyBUZXJtaW5hbCBibG9ja3MKCllv -dSBjYW4gc3BlY2lmeSB0ZXJtaW5hbCBibG9ja3MgYnkgdXNpbmcgdGhlIGBj -b21tYW5kLWxpbmVgIHN5bnRheCBoaWdobGlnaHRpbmcuCgogICAgYGBgIGNv -bW1hbmQtbGluZQogICAgJCBjdXJsIGZvb2JhcgogICAgYGBgCgpZb3UgY2Fu -IHVzZSBjZXJ0YWluIGNoYXJhY3RlcnMsIGxpa2UgYCRgIGFuZCBgI2AsIHRv -IGVtcGhhc2l6ZSBkaWZmZXJlbnQgcGFydHMKb2YgY29tbWFuZHMuCgogICAg -YGBgIGNvbW1hbmQtbGluZQogICAgIyBjYWxsIGZvb2JhcgogICAgJCBjdXJs -IDxlbT5mb29iYXI8ZW0+CiAgICAuLi4uCiAgICBgYGAKCkZvciBtb3JlIGlu -Zm9ybWF0aW9uLCBzZWUgW3RoZSByZWZlcmVuY2UgZG9jdW1lbnRhdGlvbl0o -aHR0cHM6Ly9naXRodWIuY29tL2dqdG9yaWtpYW4vZXh0ZW5kZWQtbWFya2Rv -d24tZmlsdGVyI2NvbW1hbmQtbGluZS1oaWdobGlnaHRpbmcpLgoKIyMgTGlj -ZW5zZXMKClRoZSBjb2RlIHRvIGdlbmVyYXRlIHRoZSBzaXRlIChldmVyeXRo -aW5nIGV4Y2x1ZGluZyB0aGUgYXNzZXRzLCBjb250ZW50LAphbmQgbGF5b3V0 -cyBkaXJlY3RvcmllcykgYXMgd2VsbCBhcyB0aGUgY29kZSBzYW1wbGVzIG9u -IHRoZSBzaXRlIGFyZQpsaWNlbnNlZCB1bmRlcgpbQ0MwLTEuMF0oaHR0cHM6 -Ly9jcmVhdGl2ZWNvbW1vbnMub3JnL3B1YmxpY2RvbWFpbi96ZXJvLzEuMC9s -ZWdhbGNvZGUpLgpDQzAgd2FpdmVzIGFsbCBjb3B5cmlnaHQgcmVzdHJpY3Rp -b25zIGJ1dCBkb2VzIG5vdCBncmFudCB5b3UgYW55IHRyYWRlbWFyawpwZXJt -aXNzaW9ucy4KClNpdGUgY29udGVudCAoZXZlcnl0aGluZyBpbiB0aGUgYXNz -ZXRzLCBjb250ZW50LCBhbmQgbGF5b3V0cyBkaXJlY3RvcmllcywKZXhjbHVk -aW5nIGZpbGVzIHVuZGVyIG9wZW4gc291cmNlIGxpY2Vuc2VzIGluZGl2aWR1 -YWxseSBtYXJrZWQpIGlzIGxpY2Vuc2VkCnVuZGVyIFtDQy1CWS00LjBdKGh0 -dHBzOi8vY3JlYXRpdmVjb21tb25zLm9yZy9saWNlbnNlcy9ieS80LjAvKS4g -Q0MtQlktNC4wCmdpdmVzIHlvdSBwZXJtaXNzaW9uIHRvIHVzZSBjb250ZW50 -IGZvciBhbG1vc3QgYW55IHB1cnBvc2UgYnV0IGRvZXMgbm90IGdyYW50Cnlv -dSBhbnkgdHJhZGVtYXJrIHBlcm1pc3Npb25zLCBzbyBsb25nIGFzIHlvdSBu -b3RlIHRoZSBsaWNlbnNlIGFuZCBnaXZlIGNyZWRpdCwKc3VjaCBhcyBmb2xs -b3dzOgoKPiBDb250ZW50IGJhc2VkIG9uCj4gPGEgaHJlZj0iaHR0cHM6Ly9n -aXRodWIuY29tL2dpdGh1Yi9kZXZlbG9wZXIuZ2l0aHViLmNvbSI+ZGV2ZWxv -cGVyLmdpdGh1Yi5jb208L2E+Cj4gdXNlZCB1bmRlciB0aGUKPiA8YSBocmVm -PSJodHRwczovL2NyZWF0aXZlY29tbW9ucy5vcmcvbGljZW5zZXMvYnkvNC4w -LyI+Q0MtQlktNC4wPC9hPgo+IGxpY2Vuc2UuPC9hPgoKVGhpcyBtZWFucyB5 -b3UgY2FuIHVzZSB0aGUgY29kZSBhbmQgY29udGVudCBpbiB0aGlzIHJlcG9z -aXRvcnkgZXhjZXB0IGZvcgpHaXRIdWIgdHJhZGVtYXJrcyBpbiB5b3VyIG93 -biBwcm9qZWN0cy4KCldoZW4geW91IGNvbnRyaWJ1dGUgdG8gdGhpcyByZXBv -c2l0b3J5IHlvdSBhcmUgZG9pbmcgc28gdW5kZXIgdGhlIGFib3ZlCmxpY2Vu -c2VzLgo= +# developer.github.com + +**NOTE: The developer.github.com website is no longer open-source.** + +We have moved this repository into [our github-archive organization](https://github.com/github-archive) to signify that we are no longer accepting open-source contributions to this repository. We want to thank the hundreds of contributors for their assistance over the years. + +The decision to close-source the site stems from a variety of reasons: + +1. We actually already _have_ a close-sourced site, which is where we wrote documentation for unreleased features. We designed additional tooling to support this workflow, but updating the documentation is a process we'd like to simplify. +2. We believe that any open-source project—be it documentation or software—ought to have dedicated maintainers. It became difficult to keep this repository open-source because it was maintained by the best efforts of a small group of people. Closing the site allows us to focus on what's important, without feeling guilty at missing reviews from open-source contributors. + +We think that the tooling we used to build this site is pretty interesting, so we're not getting rid of everything. We hope that what remains can be used as a source of inspiration for your own static site. + +If you find something that needs to be fixed, you can always [contact our terrific Support team](https://github.com/contact?form%5Bsubject%5D=Moving+developer.github.com+to+github-archive). + +Thank you! + +* * * + +This was the GitHub API documentation, built with [Nanoc][nanoc]. + +## Development + +You can fetch the latest dependencies by opening the command line and running `script/bootstrap`: + +``` sh +$ script/bootstrap +==> Installing gem dependencies… +==> Installing npm dependencies… +``` + +You'll need Ruby and Node installed on your system. The required versions for each of these languages can be found in the *.ruby-version* and *package.json* files, respectively. + +You can run `bundle exec rake build` to generate the site, but it's often more useful +to simply build the server *and* start the site at the same time. + +Nanoc compiles the site into static files living in `output`. It's +smart enough not to try to compile unchanged files. + +You can start the site with `script/server`: + +``` sh +$ script/server +Loading site data... +Compiling site... + create [0.28s] output/index.html + create [1.31s] output/v3/gists/comments/index.html + identical [1.92s] output/v3/gists/index.html + identical [0.25s] output/v3/issues/comments/index.html + update [0.99s] output/v3/issues/labels/index.html + update [0.05s] output/v3/index.html + … + +Site compiled in 5.81s. +``` + +The site is hosted at `http://localhost:4000`. + +Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about Nanoc. + +[nanoc]: http://nanoc.ws/ + +### Enterprise + +To generate the `/enterprise` versions, pass in the Enterprise version to `script/server`. For example: + +``` sh +$ script/server 2.6 +``` + +Note that live reloading is not available for Enterprise documentation. + +## Styleguide + +Not sure how to structure the docs? Here's what the structure of the +API docs should look like: + + # API title + + {:toc} + + ## API endpoint title + + [VERB] /path/to/endpoint + + ### Parameters + + Name | Type | Description + -----|------|-------------- + `name`|`type` | Description. + + ### Input (request JSON body) + + Name | Type | Description + -----|------|-------------- + `name`|`type` | Description. + + ### Response + + <%= headers 200, :pagination => default_pagination_rels, 'X-Custom-Header' => "value" %> + <%= json :resource_name %> + +**Note**: We're using [Kramdown Markdown extensions](http://kramdown.gettalong.org/syntax.html), such as definition lists. + +### JSON Responses + +We specify the JSON responses in Ruby so that we don't have to write +them by hand all over the docs. You can render the JSON for a resource +like this: + +```erb +<%= json :issue %> +``` + +This looks up `GitHub::Resources::ISSUE` in `lib/resources.rb`. + +Some actions return arrays. You can modify the JSON by passing a block: + +```erb +<%= json(:issue) { |hash| [hash] } %> +``` + +There is also a rake task for generating JSON files from the sample responses in the documentation: + +``` sh +$ rake generate_json_from_responses +``` + +The generated files will end up in *json-dump/*. + +### Terminal blocks + +You can specify terminal blocks by using the `command-line` syntax highlighting. + + ``` command-line + $ curl foobar + ``` + +You can use certain characters, like `$` and `#`, to emphasize different parts +of commands. + + ``` command-line + # call foobar + $ curl foobar + .... + ``` + +For more information, see [the reference documentation](https://github.com/gjtorikian/extended-markdown-filter#command-line-highlighting). + +## Licenses + +The code to generate the site (everything excluding the assets, content, +and layouts directories) as well as the code samples on the site are +licensed under +[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode). +CC0 waives all copyright restrictions but does not grant you any trademark +permissions. + +Site content (everything in the assets, content, and layouts directories, +excluding files under open source licenses individually marked) is licensed +under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). CC-BY-4.0 +gives you permission to use content for almost any purpose but does not grant +you any trademark permissions, so long as you note the license and give credit, +such as follows: + +> Content based on +> developer.github.com +> used under the +> CC-BY-4.0 +> license. + +This means you can use the code and content in this repository except for +GitHub trademarks in your own projects. + +When you contribute to this repository you are doing so under the above +licenses.