.
+
+## 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 %}
+```
diff --git a/Gemfile b/Gemfile
index e8661f1ad2..82dfa0c806 100644
--- a/Gemfile
+++ b/Gemfile
@@ -27,7 +27,7 @@ end
group :test do
gem 'capybara', '2.4.4'
- gem 'html-proofer', '~> 2.6'
+ gem 'html-proofer', '~> 3.0'
gem 'rspec', '3.1'
gem 'selenium-webdriver', '2.45.0'
gem 'jsonlint', '0.1.0'
diff --git a/Gemfile.lock b/Gemfile.lock
index 8b660a6a7c..03314fa408 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
GEM
remote: http://rubygems.org/
specs:
- activesupport (4.2.5)
+ activesupport (4.2.5.2)
i18n (~> 0.7)
json (~> 1.7, >= 1.7.7)
minitest (~> 5.1)
@@ -24,7 +24,7 @@ GEM
colored (~> 1.2)
diff-lcs (1.2.5)
dotenv (2.0.2)
- ethon (0.8.0)
+ ethon (0.8.1)
ffi (>= 1.3.0)
extended-markdown-filter (0.4.6)
html-pipeline (~> 2.0)
@@ -41,7 +41,7 @@ GEM
activesupport
html-pipeline (>= 1.11)
rouge (~> 1.8)
- html-proofer (2.6.4)
+ html-proofer (3.0.3)
activesupport (~> 4.2)
addressable (~> 2.3)
colored (~> 1.2)
@@ -88,7 +88,7 @@ GEM
mime-types-data (~> 3.2015)
mime-types-data (3.2015.1120)
mini_portile2 (2.0.0)
- minitest (5.8.3)
+ minitest (5.8.4)
multi_json (1.11.2)
multipart-post (2.0.0)
nanoc (4.1.2)
@@ -100,7 +100,7 @@ GEM
nanoc-html-pipeline (0.3.3)
html-pipeline (~> 2.0)
nanoc (>= 3.1, < 5.0)
- nokogiri (1.6.7.1)
+ nokogiri (1.6.7.2)
mini_portile2 (~> 2.0.0.rc2)
octokit (4.2.0)
sawyer (~> 0.6.0, >= 0.5.3)
@@ -108,7 +108,7 @@ GEM
page-toc-filter (0.0.1)
html-pipeline (~> 2.0)
nokogiri (~> 1.6.4)
- parallel (1.6.1)
+ parallel (1.6.2)
rack (1.6.4)
rack-protection (1.5.3)
rack
@@ -180,7 +180,7 @@ DEPENDENCIES
gemoji (= 2.1.0)
github-markdown (= 0.6.9)
html-pipeline-rouge_filter (~> 1.0)
- html-proofer (~> 2.6)
+ html-proofer (~> 3.0)
jekyll-auth (~> 2.0)
jsonlint (= 0.1.0)
nanoc (~> 4.0)
@@ -193,4 +193,4 @@ DEPENDENCIES
selenium-webdriver (= 2.45.0)
BUNDLED WITH
- 1.10.6
+ 1.11.2
diff --git a/README.md b/README.md
index 3a24fb85d7..d73feafde0 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,23 @@
# developer.github.com
-This is a GitHub API resource built with [Nanoc][nanoc].
+**NOTE: The developer.github.com website is no longer open-source.**
-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/).
+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
@@ -45,6 +60,16 @@ Nanoc has [some nice documentation](http://nanoc.ws/docs/tutorial/) to get you s
[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
@@ -95,6 +120,14 @@ Some actions return arrays. You can modify the JSON by passing a block:
<%= 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.
@@ -114,10 +147,6 @@ of commands.
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,
diff --git a/Rakefile b/Rakefile
index 63a72ff19d..066f1ab736 100644
--- a/Rakefile
+++ b/Rakefile
@@ -35,18 +35,19 @@ end
desc "Run the HTML-Proofer"
task :run_proofer do
- require 'html/proofer'
- ignored_links = [%r{www.w3.org}]
- latest_ent_version = GitHub::Resources::Helpers::CONTENT['LATEST_ENTERPRISE_VERSION']
+ require 'html-proofer'
+ ignored_links = [%r{www.w3.org}, /api\.github\.com/, /import\.github\.com/]
# swap versionless Enterprise articles with versioned paths
- href_swap = {
- %r{help\.github\.com/enterprise/admin/} => "help.github.com/enterprise/#{config[:versions][0]}/admin/",
- %r{help\.github\.com/enterprise/user/} => "help.github.com/enterprise/#{config[:versions][0]}/user/"
+ url_swap = {
+ %r{help.github.com/enterprise/admin/} => "help.github.com/enterprise/#{config[:versions][0]}/admin/",
+ %r{help.github.com/enterprise/user/} => "help.github.com/enterprise/#{config[:versions][0]}/user/"
}
- HTML::Proofer.new("./output", \
- :href_ignore => ignored_links, \
- :href_swap => href_swap, \
- :parallel => { :in_processes => 5 }).run
+ proofer_opts = {
+ :url_ignore => ignored_links,
+ :url_swap => url_swap,
+ :parallel => { :in_processes => 5 }
+ }
+ HTMLProofer.check_directory("./output", proofer_opts).run
end
desc "Remove the tmp dir"
@@ -97,3 +98,14 @@ task :publish, [:no_commit_msg] => [:remove_tmp_dir, :remove_output_dir, :build]
system 'git checkout master'
end
end
+
+desc "Generate JSON from the sample responses"
+task :generate_json_from_responses do
+ Dir[File.join(File.dirname(__FILE__), 'lib', 'responses', '*.rb')].each { |file| load file }
+ FileUtils.mkdir_p(File.join(File.dirname(__FILE__), 'json-dump'))
+ GitHub::Resources::Responses.constants.each { |constant|
+ File.open('json-dump/' + constant.to_s + '.json', 'w') { |file|
+ file.write(JSON.pretty_generate(GitHub::Resources::Helpers.get_resource(constant)))
+ }
+ }
+end
diff --git a/Rules b/Rules
index 49bd23fd48..c04b63886d 100755
--- a/Rules
+++ b/Rules
@@ -6,6 +6,8 @@
# rule is applied.
preprocess do
+ add_created_at_attribute
+ add_kind_attribute
create_individual_blog_pages
generate_redirects(config[:redirects])
@items.each do |item|
diff --git a/assets/javascripts/documentation.js b/assets/javascripts/documentation.js
index 0753d62b14..d006cd551e 100644
--- a/assets/javascripts/documentation.js
+++ b/assets/javascripts/documentation.js
@@ -4,7 +4,7 @@ $(function() {
helpList = $('#js-sidebar .js-topic'),
firstOccurance = true,
styleTOC = function() {
- var pathRegEx = /\/\/[^\/]+([A-Za-z0-9-_/]+)/g,
+ var pathRegEx = /\/\/[^\/]+([A-Za-z0-9-_./]+)/g,
docUrl = pathRegEx.exec(window.location.toString())
if (docUrl){
$('#js-sidebar .js-topic a').each(function(){
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/2012-09-05-watcher-api.html b/content/changes/2012-09-05-watcher-api.html
index 87e0a7b456..fd151bdc3c 100644
--- a/content/changes/2012-09-05-watcher-api.html
+++ b/content/changes/2012-09-05-watcher-api.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Upcoming Changes to Watcher and Star APIs
-created_at: 2012-09-05
author_name: technoweenie
---
diff --git a/content/changes/2012-09-28-auto-init-for-repositories.html b/content/changes/2012-09-28-auto-init-for-repositories.html
index 5dc6beb46e..cf650e9291 100644
--- a/content/changes/2012-09-28-auto-init-for-repositories.html
+++ b/content/changes/2012-09-28-auto-init-for-repositories.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Initialize a repository when creating
-created_at: 2012-09-28
author_name: pengwynn
---
diff --git a/content/changes/2012-10-14-rate-limit-changes.html b/content/changes/2012-10-14-rate-limit-changes.html
index 5833343491..60aa94f4fa 100644
--- a/content/changes/2012-10-14-rate-limit-changes.html
+++ b/content/changes/2012-10-14-rate-limit-changes.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Rate limit changes for unauthenticated requests
-created_at: 2012-10-14
author_name: pengwynn
---
diff --git a/content/changes/2012-10-17-org-members-redirection.md b/content/changes/2012-10-17-org-members-redirection.md
index 6b8a3f54da..ace24c0173 100644
--- a/content/changes/2012-10-17-org-members-redirection.md
+++ b/content/changes/2012-10-17-org-members-redirection.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Organization Members Resource Changes
-created_at: 2012-10-17
author_name: pezra
---
diff --git a/content/changes/2012-10-24-set-default-branch.html b/content/changes/2012-10-24-set-default-branch.html
index 867875fe0b..ac9800b41b 100644
--- a/content/changes/2012-10-24-set-default-branch.html
+++ b/content/changes/2012-10-24-set-default-branch.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Set the default branch for a repository
-created_at: 2012-10-24
author_name: pengwynn
---
diff --git a/content/changes/2012-10-26-notifications-api.md b/content/changes/2012-10-26-notifications-api.md
index 9507a6e542..db08698377 100644
--- a/content/changes/2012-10-26-notifications-api.md
+++ b/content/changes/2012-10-26-notifications-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Notifications API
-created_at: 2012-10-26
author_name: technoweenie
---
diff --git a/content/changes/2012-10-31-gist-comment-uris.md b/content/changes/2012-10-31-gist-comment-uris.md
index 09c112586c..a6f3d9e4f4 100644
--- a/content/changes/2012-10-31-gist-comment-uris.md
+++ b/content/changes/2012-10-31-gist-comment-uris.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Gist comment URIs
-created_at: 2012-10-31
author_name: pezra
---
diff --git a/content/changes/2012-11-27-forking-to-organizations.html b/content/changes/2012-11-27-forking-to-organizations.html
index 5298df67b7..90282f045a 100644
--- a/content/changes/2012-11-27-forking-to-organizations.html
+++ b/content/changes/2012-11-27-forking-to-organizations.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Forking to Organizations
-created_at: 2012-11-27
author_name: technoweenie
---
diff --git a/content/changes/2012-11-29-gitignore-templates.html b/content/changes/2012-11-29-gitignore-templates.html
index e7e351862c..d88d39b88f 100644
--- a/content/changes/2012-11-29-gitignore-templates.html
+++ b/content/changes/2012-11-29-gitignore-templates.html
@@ -1,14 +1,12 @@
---
-kind: change
title: Gitignore Templates API
-created_at: 2012-11-29
author_name: pengwynn
---
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/2012-12-04-List-comments-for-repo.html b/content/changes/2012-12-04-List-comments-for-repo.html
index b3435bd5ca..7511737cdc 100644
--- a/content/changes/2012-12-04-List-comments-for-repo.html
+++ b/content/changes/2012-12-04-List-comments-for-repo.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Per-repository Review and Issue Comment listing
-created_at: 2012-12-04
author_name: pengwynn
---
diff --git a/content/changes/2012-12-06-create-authorization-for-app.html b/content/changes/2012-12-06-create-authorization-for-app.html
index 2c9fe08a40..a1de9eb1b0 100644
--- a/content/changes/2012-12-06-create-authorization-for-app.html
+++ b/content/changes/2012-12-06-create-authorization-for-app.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Create an OAuth authorization for an app
-created_at: 2012-12-06
author_name: pengwynn
---
diff --git a/content/changes/2012-12-08-finding-source-and-fork-repos-for-organizations.html b/content/changes/2012-12-08-finding-source-and-fork-repos-for-organizations.html
index e79ad65538..bd9f91bedf 100644
--- a/content/changes/2012-12-08-finding-source-and-fork-repos-for-organizations.html
+++ b/content/changes/2012-12-08-finding-source-and-fork-repos-for-organizations.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Finding sources and fork repositories for organizations
-created_at: 2012-12-08
author_name: rick
---
diff --git a/content/changes/2012-12-09-organization-repositories-results-now-paginate.html b/content/changes/2012-12-09-organization-repositories-results-now-paginate.html
index d58a557520..530d13e2ef 100644
--- a/content/changes/2012-12-09-organization-repositories-results-now-paginate.html
+++ b/content/changes/2012-12-09-organization-repositories-results-now-paginate.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Pagination for Organization Repository lists now paginates properly
-created_at: 2012-12-09
author_name: rick
---
diff --git a/content/changes/2012-12-10-Diff-and-patch-media-types.html b/content/changes/2012-12-10-Diff-and-patch-media-types.html
index 05ba0c0ea1..96eb82a02a 100644
--- a/content/changes/2012-12-10-Diff-and-patch-media-types.html
+++ b/content/changes/2012-12-10-Diff-and-patch-media-types.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Diff and patch media types
-created_at: 2012-12-10
author_name: pengwynn
---
diff --git a/content/changes/2013-01-08-new-user-scopes.html b/content/changes/2013-01-08-new-user-scopes.html
index c0e3aeae7f..ecd48a14db 100644
--- a/content/changes/2013-01-08-new-user-scopes.html
+++ b/content/changes/2013-01-08-new-user-scopes.html
@@ -1,7 +1,5 @@
---
-kind: change
title: New User scopes
-created_at: 2013-01-08
author_name: technoweenie
---
diff --git a/content/changes/2013-01-31-user-agent-will-soon-be-mandatory.html b/content/changes/2013-01-31-user-agent-will-soon-be-mandatory.html
index 2407d3a97d..3c06f81381 100644
--- a/content/changes/2013-01-31-user-agent-will-soon-be-mandatory.html
+++ b/content/changes/2013-01-31-user-agent-will-soon-be-mandatory.html
@@ -1,13 +1,11 @@
---
-kind: change
title: User Agent mandatory from March 4th 2013
-created_at: 2013-01-31
author_name: agh
---
Following on from our [previous post](http://developer.github.com/changes/2012-10-14-rate-limit-changes/)
about requiring requests to include a valid [User Agent header](http://en.wikipedia.org/wiki/User_agent)
-we will soon be changing our API servers to return HTTP 403
+we will soon be changing our API servers to return HTTP 403
to any clients not providing a valid User Agent header.
We will be making this change on Monday, March 4th 2013.
diff --git a/content/changes/2013-02-05-changes-to-services.html b/content/changes/2013-02-05-changes-to-services.html
index c97c95a7df..4ff6d6e8cd 100644
--- a/content/changes/2013-02-05-changes-to-services.html
+++ b/content/changes/2013-02-05-changes-to-services.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Upcoming Changes to GitHub Services
-created_at: 2013-02-05
author_name: technoweenie
---
@@ -30,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/changes/2013-02-13-hookshot-issues.html b/content/changes/2013-02-13-hookshot-issues.html
index fc6161a3c8..7e69bc2ada 100644
--- a/content/changes/2013-02-13-hookshot-issues.html
+++ b/content/changes/2013-02-13-hookshot-issues.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Some Hookshot Issues
-created_at: 2013-02-13T11:00:00
author_name: technoweenie
---
diff --git a/content/changes/2013-02-13-hookshot-load-balancer.html b/content/changes/2013-02-13-hookshot-load-balancer.html
index 5f4733e61e..fd6b3114cd 100644
--- a/content/changes/2013-02-13-hookshot-load-balancer.html
+++ b/content/changes/2013-02-13-hookshot-load-balancer.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Hookshot Load balancer
-created_at: 2013-02-13T12:00:00
author_name: technoweenie
---
diff --git a/content/changes/2013-02-14-sortable-stars.html b/content/changes/2013-02-14-sortable-stars.html
index 61020976ec..d7b253b919 100644
--- a/content/changes/2013-02-14-sortable-stars.html
+++ b/content/changes/2013-02-14-sortable-stars.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Sortable Stars in Repository Starring API
-created_at: 2013-02-14
author_name: pengwynn
---
diff --git a/content/changes/2013-03-01-new-hookshot-coming.html b/content/changes/2013-03-01-new-hookshot-coming.html
index 729a799183..c109a40653 100644
--- a/content/changes/2013-03-01-new-hookshot-coming.html
+++ b/content/changes/2013-03-01-new-hookshot-coming.html
@@ -1,7 +1,5 @@
---
-kind: change
title: New Hookshot Changes
-created_at: 2013-03-01
author_name: technoweenie
---
diff --git a/content/changes/2013-04-24-user-agent-required.html b/content/changes/2013-04-24-user-agent-required.html
index 292d14c5a1..b1fae21ff0 100644
--- a/content/changes/2013-04-24-user-agent-required.html
+++ b/content/changes/2013-04-24-user-agent-required.html
@@ -1,7 +1,5 @@
---
-kind: change
title: User Agent now mandatory
-created_at: 2013-04-24
author_name: pengwynn
---
diff --git a/content/changes/2013-04-25-deprecating-merge-commit-sha.html b/content/changes/2013-04-25-deprecating-merge-commit-sha.html
index 8598c62e33..8bff84e414 100644
--- a/content/changes/2013-04-25-deprecating-merge-commit-sha.html
+++ b/content/changes/2013-04-25-deprecating-merge-commit-sha.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Deprecating a Confusing Attribute in the Pull Request API
-created_at: 2013-04-25
author_name: jasonrudolph
---
diff --git a/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md b/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md
index 43185e923c..8b7598e783 100644
--- a/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md
+++ b/content/changes/2013-04-30-improved-submodule-support-in-repository-contents-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Improved Support for Submodules in the Repository Contents API
-created_at: 2013-04-30
author_name: jasonrudolph
---
diff --git a/content/changes/2013-04-30-statuses-for-branches-and-tags.md b/content/changes/2013-04-30-statuses-for-branches-and-tags.md
index 0e3b404e91..b42aafdb81 100644
--- a/content/changes/2013-04-30-statuses-for-branches-and-tags.md
+++ b/content/changes/2013-04-30-statuses-for-branches-and-tags.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Commit Statuses Now Available for Branches and Tags
-created_at: 2013-04-30
author_name: foca
---
diff --git a/content/changes/2013-05-06-create-update-delete-individual-files.md b/content/changes/2013-05-06-create-update-delete-individual-files.md
index bd30049ca0..f9baff52ca 100644
--- a/content/changes/2013-05-06-create-update-delete-individual-files.md
+++ b/content/changes/2013-05-06-create-update-delete-individual-files.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Create, update, and delete individual files
-created_at: 2013-05-06
author_name: ymendel
---
diff --git a/content/changes/2013-05-06-repository-stats.md b/content/changes/2013-05-06-repository-stats.md
index 08569d9347..3ff4b37d97 100644
--- a/content/changes/2013-05-06-repository-stats.md
+++ b/content/changes/2013-05-06-repository-stats.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Repository Statistics
-created_at: 2013-05-06
author_name: Caged
---
diff --git a/content/changes/2013-07-01-feeds-api.md b/content/changes/2013-07-01-feeds-api.md
index 67ea75d972..e15115c5bf 100644
--- a/content/changes/2013-07-01-feeds-api.md
+++ b/content/changes/2013-07-01-feeds-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Feeds API
-created_at: 2013-7-01
author_name: pengwynn
---
diff --git a/content/changes/2013-07-02-rate-limit-reset.md b/content/changes/2013-07-02-rate-limit-reset.md
index 0b0ba5be61..5106f7412b 100644
--- a/content/changes/2013-07-02-rate-limit-reset.md
+++ b/content/changes/2013-07-02-rate-limit-reset.md
@@ -1,7 +1,5 @@
---
-kind: change
title: When Does My Rate Limit Reset?
-created_at: 2013-07-02
author_name: jasonrudolph
---
diff --git a/content/changes/2013-07-19-preview-the-new-search-api.md b/content/changes/2013-07-19-preview-the-new-search-api.md
index 736b4a28b6..370a1440c2 100644
--- a/content/changes/2013-07-19-preview-the-new-search-api.md
+++ b/content/changes/2013-07-19-preview-the-new-search-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview the New Search API
-created_at: 2013-07-19
author_name: jasonrudolph
---
diff --git a/content/changes/2013-08-20-search-api-improvements.md b/content/changes/2013-08-20-search-api-improvements.md
index 6715d4bbdd..1ab04d2b9e 100644
--- a/content/changes/2013-08-20-search-api-improvements.md
+++ b/content/changes/2013-08-20-search-api-improvements.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Improvements to the Search API
-created_at: 2013-08-20
author_name: jasonrudolph
---
diff --git a/content/changes/2013-09-03-two-factor-authentication.md b/content/changes/2013-09-03-two-factor-authentication.md
index af55f08d82..0b999da9a9 100644
--- a/content/changes/2013-09-03-two-factor-authentication.md
+++ b/content/changes/2013-09-03-two-factor-authentication.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Two-Factor Authentication and the API
-created_at: 2013-09-03
author_name: mastahyeti
---
diff --git a/content/changes/2013-09-25-releases-api.md b/content/changes/2013-09-25-releases-api.md
index 6539d299ee..7185d32cb5 100644
--- a/content/changes/2013-09-25-releases-api.md
+++ b/content/changes/2013-09-25-releases-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Releases API
-created_at: 2013-09-25
author_name: technoweenie
---
diff --git a/content/changes/2013-09-28-an-update-on-the-new-search-api.md b/content/changes/2013-09-28-an-update-on-the-new-search-api.md
index 2212fdff16..fbdf1623d8 100644
--- a/content/changes/2013-09-28-an-update-on-the-new-search-api.md
+++ b/content/changes/2013-09-28-an-update-on-the-new-search-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: An Update on the New Search API
-created_at: 2013-09-28
author_name: jasonrudolph
---
diff --git a/content/changes/2013-10-04-oauth-changes-coming.html b/content/changes/2013-10-04-oauth-changes-coming.html
index eac304a82a..a81fbc7c99 100644
--- a/content/changes/2013-10-04-oauth-changes-coming.html
+++ b/content/changes/2013-10-04-oauth-changes-coming.html
@@ -1,7 +1,5 @@
---
-kind: change
title: OAuth changes coming
-created_at: 2013-10-04
author_name: tclem
---
diff --git a/content/changes/2013-10-08-list-all-user-teams.html b/content/changes/2013-10-08-list-all-user-teams.html
index 822a13301d..1989d9ea81 100644
--- a/content/changes/2013-10-08-list-all-user-teams.html
+++ b/content/changes/2013-10-08-list-all-user-teams.html
@@ -1,7 +1,5 @@
---
-kind: change
title: List all teams for the authenticated user
-created_at: 2013-10-08
author_name: pengwynn
---
diff --git a/content/changes/2013-10-18-new-code-search-requirements.md b/content/changes/2013-10-18-new-code-search-requirements.md
index bef8684509..746f3f61df 100644
--- a/content/changes/2013-10-18-new-code-search-requirements.md
+++ b/content/changes/2013-10-18-new-code-search-requirements.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New Validation Rule for Beta Code Search API
-created_at: 2013-10-18
author_name: jasonrudolph
---
diff --git a/content/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3.md b/content/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3.md
index e9fb466d7f..5ca31f1042 100644
--- a/content/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3.md
+++ b/content/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Search API Becomes an Official Part of API v3
-created_at: 2013-10-29
author_name: jasonrudolph
---
diff --git a/content/changes/2013-11-04-releases-api-is-official.md b/content/changes/2013-11-04-releases-api-is-official.md
index 9691006777..4bb7dd971a 100644
--- a/content/changes/2013-11-04-releases-api-is-official.md
+++ b/content/changes/2013-11-04-releases-api-is-official.md
@@ -1,13 +1,11 @@
---
-kind: change
title: Releases API is Official
-created_at: 2013-11-04
author_name: technoweenie
---
Hot on the heels of the [Search API][search-api], the [Releases API][releases-api]
is now officially part of GitHub API v3. We now consider it stable for
-production use.
+production use.
### Preview Media Type No Longer Needed
diff --git a/content/changes/2013-12-13-paginating-org-members.md b/content/changes/2013-12-13-paginating-org-members.md
index a6f89987ad..80c3432fdf 100644
--- a/content/changes/2013-12-13-paginating-org-members.md
+++ b/content/changes/2013-12-13-paginating-org-members.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Paginated results for organization members
-created_at: 2013-12-13
author_name: pengwynn
---
diff --git a/content/changes/2014-01-07-upcoming-change-to-default-media-type.md b/content/changes/2014-01-07-upcoming-change-to-default-media-type.md
index 838b2b1dcb..fad283d768 100644
--- a/content/changes/2014-01-07-upcoming-change-to-default-media-type.md
+++ b/content/changes/2014-01-07-upcoming-change-to-default-media-type.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Upcoming Change to Default Media Type
-created_at: 2014-01-07
author_name: jasonrudolph
---
diff --git a/content/changes/2014-01-09-preview-the-new-deployments-api.md b/content/changes/2014-01-09-preview-the-new-deployments-api.md
index 003a99be33..fd2a28d148 100644
--- a/content/changes/2014-01-09-preview-the-new-deployments-api.md
+++ b/content/changes/2014-01-09-preview-the-new-deployments-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview the New Deployments API
-created_at: 2014-01-09
author_name: atmos
---
diff --git a/content/changes/2014-01-29-audit-org-members-for-2fa.md b/content/changes/2014-01-29-audit-org-members-for-2fa.md
index af59363011..5e7239801a 100644
--- a/content/changes/2014-01-29-audit-org-members-for-2fa.md
+++ b/content/changes/2014-01-29-audit-org-members-for-2fa.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Audit organization members for two-factor authentication
-created_at: 2014-01-29
author_name: pengwynn
---
diff --git a/content/changes/2014-02-10-ping-event-for-webhooks.html b/content/changes/2014-02-10-ping-event-for-webhooks.html
index cfd9c38eec..386ba8cf75 100644
--- a/content/changes/2014-02-10-ping-event-for-webhooks.html
+++ b/content/changes/2014-02-10-ping-event-for-webhooks.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Ping Event for Webhooks
-created_at: 2014-2-10
author_name: kdaigle
---
diff --git a/content/changes/2014-02-10-repo-hook-scopes.md b/content/changes/2014-02-10-repo-hook-scopes.md
index 71c91bc8f7..56f8372627 100644
--- a/content/changes/2014-02-10-repo-hook-scopes.md
+++ b/content/changes/2014-02-10-repo-hook-scopes.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New scopes for managing repository hooks
-created_at: 2014-02-10
author_name: pengwynn
---
diff --git a/content/changes/2014-02-13-exposing-the-page-api.html b/content/changes/2014-02-13-exposing-the-page-api.html
index 314aed7336..72167855c0 100644
--- a/content/changes/2014-02-13-exposing-the-page-api.html
+++ b/content/changes/2014-02-13-exposing-the-page-api.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Introducing the Pages API
-created_at: 2014-02-13
author_name: gjtorikian
---
diff --git a/content/changes/2014-02-19-repo-contributors-for-empty-repos.md b/content/changes/2014-02-19-repo-contributors-for-empty-repos.md
index 67f10dde2f..9fe6911aa1 100644
--- a/content/changes/2014-02-19-repo-contributors-for-empty-repos.md
+++ b/content/changes/2014-02-19-repo-contributors-for-empty-repos.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Repository Contributors and Empty Repositories
-created_at: 2014-02-20
author_name: izuzak
---
diff --git a/content/changes/2014-02-21-gist-raw-file-url-change.md b/content/changes/2014-02-21-gist-raw-file-url-change.md
index 8d98f7097f..7117f55411 100644
--- a/content/changes/2014-02-21-gist-raw-file-url-change.md
+++ b/content/changes/2014-02-21-gist-raw-file-url-change.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Gist raw file URI change
-created_at: 2014-02-21
author_name: spicycode
---
diff --git a/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md b/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md
index c84ec89abb..833b4f4e6c 100644
--- a/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md
+++ b/content/changes/2014-02-24-finer-grained-scopes-for-ssh-keys.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Finer-grained OAuth scopes for SSH keys
-created_at: 2014-02-24
author_name: pengwynn
---
As [we announced][blog], we've made some important changes to the way that API consumers manage SSH keys.
diff --git a/content/changes/2014-02-24-wildcard-event-for-webhooks.md b/content/changes/2014-02-24-wildcard-event-for-webhooks.md
index 5e9a29a7b7..ecad8cead1 100644
--- a/content/changes/2014-02-24-wildcard-event-for-webhooks.md
+++ b/content/changes/2014-02-24-wildcard-event-for-webhooks.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Wildcard Event for Webhooks
-created_at: 2014-2-24
author_name: kdaigle
---
diff --git a/content/changes/2014-02-25-organization-oauth-scopes.md b/content/changes/2014-02-25-organization-oauth-scopes.md
index 40911b2b3e..e28320c694 100644
--- a/content/changes/2014-02-25-organization-oauth-scopes.md
+++ b/content/changes/2014-02-25-organization-oauth-scopes.md
@@ -1,7 +1,5 @@
---
-kind: change
title: OAuth scopes for organization and team resources
-created_at: 2014-02-25
author_name: pengwynn
---
As a follow up to [the new scopes][yesterday] we announced yesterday, we've
diff --git a/content/changes/2014-02-28-issue-and-pull-query-enhancements.md b/content/changes/2014-02-28-issue-and-pull-query-enhancements.md
index 70969a677d..5b113f0480 100644
--- a/content/changes/2014-02-28-issue-and-pull-query-enhancements.md
+++ b/content/changes/2014-02-28-issue-and-pull-query-enhancements.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Query enhancements for listing issues and pull requests
-created_at: 2014-02-28
author_name: pengwynn
---
We've made it even easier to list all [issues][] and [pull requests][] via the API.
diff --git a/content/changes/2014-03-03-deployments-api-updates.md b/content/changes/2014-03-03-deployments-api-updates.md
index b4354c8dee..bf6198beb4 100644
--- a/content/changes/2014-03-03-deployments-api-updates.md
+++ b/content/changes/2014-03-03-deployments-api-updates.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New Payload Format for Deployments
-created_at: 2014-03-03
author_name: atmos
---
diff --git a/content/changes/2014-03-04-timezone-handling-changes.html b/content/changes/2014-03-04-timezone-handling-changes.html
index 5ef7aa18e1..2f8e862653 100644
--- a/content/changes/2014-03-04-timezone-handling-changes.html
+++ b/content/changes/2014-03-04-timezone-handling-changes.html
@@ -1,7 +1,5 @@
---
-kind: change
title: Improved timezone handling in the API
-created_at: 2014-03-04
author_name: dbussink
---
diff --git a/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md b/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md
index e19dd70b96..3a6aabfff0 100644
--- a/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md
+++ b/content/changes/2014-03-05-reminder-about-upcoming-cutover-test.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "Reminder: March 12 Cutover Test for Default Media Type"
-created_at: 2014-03-05
author_name: jasonrudolph
---
diff --git a/content/changes/2014-03-12-page-build-event-for-webhooks.md b/content/changes/2014-03-12-page-build-event-for-webhooks.md
index bdc50b2a1c..64e19a83c8 100644
--- a/content/changes/2014-03-12-page-build-event-for-webhooks.md
+++ b/content/changes/2014-03-12-page-build-event-for-webhooks.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Page Build Event for Webhooks
-created_at: 2014-3-12
author_name: benbalter
---
diff --git a/content/changes/2014-03-18-paginating-method-changes.md b/content/changes/2014-03-18-paginating-method-changes.md
index 3f7c05c000..9cba74b8db 100644
--- a/content/changes/2014-03-18-paginating-method-changes.md
+++ b/content/changes/2014-03-18-paginating-method-changes.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Pagination changes for some resource lists
-created_at: 2014-03-18
author_name: pengwynn
---
@@ -121,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/2014-03-27-combined-status-api.md b/content/changes/2014-03-27-combined-status-api.md
index bb1c5dd742..2edc34295a 100644
--- a/content/changes/2014-03-27-combined-status-api.md
+++ b/content/changes/2014-03-27-combined-status-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview the New Combined Status API
-created_at: 2014-03-27
author_name: bhuga
---
diff --git a/content/changes/2014-04-04-create-public-repo-without-repo-scope.md b/content/changes/2014-04-04-create-public-repo-without-repo-scope.md
index b1627b6f2b..1231f241a4 100644
--- a/content/changes/2014-04-04-create-public-repo-without-repo-scope.md
+++ b/content/changes/2014-04-04-create-public-repo-without-repo-scope.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Grant access to create public repositories without granting access to private repositories
-created_at: 2014-04-04
author_name: pengwynn
---
diff --git a/content/changes/2014-04-07-understanding-search-results-and-potential-timeouts.md b/content/changes/2014-04-07-understanding-search-results-and-potential-timeouts.md
index baf4f56c8a..07090d55c5 100644
--- a/content/changes/2014-04-07-understanding-search-results-and-potential-timeouts.md
+++ b/content/changes/2014-04-07-understanding-search-results-and-potential-timeouts.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Understanding search results and potential timeouts
-created_at: 2014-04-07
author_name: izuzak
---
diff --git a/content/changes/2014-04-08-reset-api-tokens.md b/content/changes/2014-04-08-reset-api-tokens.md
index ebc9725a4c..ed07db685f 100644
--- a/content/changes/2014-04-08-reset-api-tokens.md
+++ b/content/changes/2014-04-08-reset-api-tokens.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "Recommendation: Reset OAuth authorizations"
-created_at: 2014-04-08
author_name: pengwynn
---
diff --git a/content/changes/2014-04-09-reminder-about-default-media-type-change.md b/content/changes/2014-04-09-reminder-about-default-media-type-change.md
index 295c34071a..ba70ed5456 100644
--- a/content/changes/2014-04-09-reminder-about-default-media-type-change.md
+++ b/content/changes/2014-04-09-reminder-about-default-media-type-change.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "Reminder: Default media type will change on April 15"
-created_at: 2014-04-09
author_name: jasonrudolph
---
diff --git a/content/changes/2014-04-10-deployment-api-preview-extension.md b/content/changes/2014-04-10-deployment-api-preview-extension.md
index 968304164c..2087c59656 100644
--- a/content/changes/2014-04-10-deployment-api-preview-extension.md
+++ b/content/changes/2014-04-10-deployment-api-preview-extension.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Extending the preview period for the Deployments API
-created_at: 2014-04-10
author_name: atmos
---
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 3c726555d8..e212e5ae0e 100644
--- a/content/changes/2014-04-22-deprecating-beta-media-type.md
+++ b/content/changes/2014-04-22-deprecating-beta-media-type.md
@@ -1,13 +1,11 @@
---
-kind: change
title: Deprecating the beta media type
-created_at: 2014-04-22
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-04-25-user-content-security.md b/content/changes/2014-04-25-user-content-security.md
index aaf499f291..f1faba04eb 100644
--- a/content/changes/2014-04-25-user-content-security.md
+++ b/content/changes/2014-04-25-user-content-security.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New user content domains
-created_at: 2014-04-25
author_name: azizshamim
---
diff --git a/content/changes/2014-05-06-gist-api-now-truncating-large-files.md b/content/changes/2014-05-06-gist-api-now-truncating-large-files.md
index 35e93549ce..9b1fa4c26c 100644
--- a/content/changes/2014-05-06-gist-api-now-truncating-large-files.md
+++ b/content/changes/2014-05-06-gist-api-now-truncating-large-files.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "Changes to Gist API response for large files"
-created_at: 2014-05-06
author_name: leongersing
---
diff --git a/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md b/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md
index 8e03d3839d..b6d535ad9b 100644
--- a/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md
+++ b/content/changes/2014-05-09-improved-pagination-for-the-repository-commits-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Improved pagination for the Repository Commits API
-created_at: 2014-05-09
author_name: izuzak
---
diff --git a/content/changes/2014-05-19-deployments-api-updates.md b/content/changes/2014-05-19-deployments-api-updates.md
index 17db8f757e..8343de77c2 100644
--- a/content/changes/2014-05-19-deployments-api-updates.md
+++ b/content/changes/2014-05-19-deployments-api-updates.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New attributes for the Deployments API
-created_at: 2014-05-19
author_name: atmos
---
diff --git a/content/changes/2014-06-09-new-attributes-for-pull-request-review-comment-events.md b/content/changes/2014-06-09-new-attributes-for-pull-request-review-comment-events.md
index 03d57613fc..e8420a7c35 100644
--- a/content/changes/2014-06-09-new-attributes-for-pull-request-review-comment-events.md
+++ b/content/changes/2014-06-09-new-attributes-for-pull-request-review-comment-events.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New attributes for PullRequestReviewComment events
-created_at: 2014-06-09
author_name: jdpace
---
diff --git a/content/changes/2014-06-11-improved-ci-support-for-deployments-api.md b/content/changes/2014-06-11-improved-ci-support-for-deployments-api.md
index 43079a819e..8f5a6e1ab3 100644
--- a/content/changes/2014-06-11-improved-ci-support-for-deployments-api.md
+++ b/content/changes/2014-06-11-improved-ci-support-for-deployments-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Improved CI support for the Deployments API
-created_at: 2014-06-11
author_name: atmos
---
diff --git a/content/changes/2014-06-19-combined-status-api-pagination.md b/content/changes/2014-06-19-combined-status-api-pagination.md
index 4088a3e858..7cb5fc9c98 100644
--- a/content/changes/2014-06-19-combined-status-api-pagination.md
+++ b/content/changes/2014-06-19-combined-status-api-pagination.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Pagination in the Combined Status API
-created_at: 2014-06-19
author_name: bhuga
---
diff --git a/content/changes/2014-06-23-the-github-enterprise-api-documentation-has-a-new-home.md b/content/changes/2014-06-23-the-github-enterprise-api-documentation-has-a-new-home.md
index c4dc4a1a53..4ec77ea539 100644
--- a/content/changes/2014-06-23-the-github-enterprise-api-documentation-has-a-new-home.md
+++ b/content/changes/2014-06-23-the-github-enterprise-api-documentation-has-a-new-home.md
@@ -1,7 +1,5 @@
---
-kind: change
title: The GitHub Enterprise API documentation has a new home!
-created_at: 2014-06-23
author_name: gjtorikian
---
diff --git a/content/changes/2014-07-07-example-webhook-payloads.md b/content/changes/2014-07-07-example-webhook-payloads.md
index 26263e4821..b7403f75f8 100644
--- a/content/changes/2014-07-07-example-webhook-payloads.md
+++ b/content/changes/2014-07-07-example-webhook-payloads.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New example webhook payloads
-created_at: 2014-07-07
author_name: kdaigle
---
diff --git a/content/changes/2014-07-09-status-contexts-are-official.md b/content/changes/2014-07-09-status-contexts-are-official.md
index a9ec470850..614febd9d4 100644
--- a/content/changes/2014-07-09-status-contexts-are-official.md
+++ b/content/changes/2014-07-09-status-contexts-are-official.md
@@ -1,7 +1,5 @@
---
-kind: change
title: The Combined Status API is official
-created_at: 2014-07-09
author_name: bhuga
---
diff --git a/content/changes/2014-07-28-assignee-and-label-actions-for-issue-events.md b/content/changes/2014-07-28-assignee-and-label-actions-for-issue-events.md
index b66d1f1363..80e7045040 100644
--- a/content/changes/2014-07-28-assignee-and-label-actions-for-issue-events.md
+++ b/content/changes/2014-07-28-assignee-and-label-actions-for-issue-events.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New assigned/labeled actions for issue and pull request events
-created_at: 2014-07-28
author_name: jdpace
---
diff --git a/content/changes/2014-08-05-team-memberships-api.md b/content/changes/2014-08-05-team-memberships-api.md
index 944828cc70..fb85053ecb 100644
--- a/content/changes/2014-08-05-team-memberships-api.md
+++ b/content/changes/2014-08-05-team-memberships-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: We're changing the way you add new members to your organization
-created_at: 2014-08-05
author_name: jakeboxer
---
diff --git a/content/changes/2014-08-15-deployments-api-changes.md b/content/changes/2014-08-15-deployments-api-changes.md
index 210e8a5d67..ac6455dc22 100644
--- a/content/changes/2014-08-15-deployments-api-changes.md
+++ b/content/changes/2014-08-15-deployments-api-changes.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New features for the Deployments API preview
-created_at: 2014-08-15
author_name: atmos
---
diff --git a/content/changes/2014-08-28-accepting-organization-invitations-from-the-api.md b/content/changes/2014-08-28-accepting-organization-invitations-from-the-api.md
index 9fbd8ef0a4..e62023979b 100644
--- a/content/changes/2014-08-28-accepting-organization-invitations-from-the-api.md
+++ b/content/changes/2014-08-28-accepting-organization-invitations-from-the-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Accepting organization invitations from the API
-created_at: 2014-08-28
author_name: jakeboxer
---
diff --git a/content/changes/2014-09-05-removing-gravatar-id.md b/content/changes/2014-09-05-removing-gravatar-id.md
index 102ba6bcab..3d9f4442a1 100644
--- a/content/changes/2014-09-05-removing-gravatar-id.md
+++ b/content/changes/2014-09-05-removing-gravatar-id.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Removing Gravatar ID from user payloads
-created_at: 2014-09-05
author_name: mastahyeti
---
diff --git a/content/changes/2014-09-12-changing-organization-feeds.md b/content/changes/2014-09-12-changing-organization-feeds.md
index 45f2bfdefe..c885113e98 100644
--- a/content/changes/2014-09-12-changing-organization-feeds.md
+++ b/content/changes/2014-09-12-changing-organization-feeds.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Changing organization feeds in the Feeds API
-created_at: 2014-09-12
author_name: mastahyeti
---
diff --git a/content/changes/2014-09-16-finalizing-the-organization-and-team-membership-apis.md b/content/changes/2014-09-16-finalizing-the-organization-and-team-membership-apis.md
index e82a76c0fb..5b6f7b340b 100644
--- a/content/changes/2014-09-16-finalizing-the-organization-and-team-membership-apis.md
+++ b/content/changes/2014-09-16-finalizing-the-organization-and-team-membership-apis.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Finalizing the Organization and Team Membership APIs
-created_at: 2014-09-16
author_name: jakeboxer
---
diff --git a/content/changes/2014-09-23-one-more-week-before-the-add-team-member-api-breaking-change.md b/content/changes/2014-09-23-one-more-week-before-the-add-team-member-api-breaking-change.md
index 4d0d704621..8ef7561d6d 100644
--- a/content/changes/2014-09-23-one-more-week-before-the-add-team-member-api-breaking-change.md
+++ b/content/changes/2014-09-23-one-more-week-before-the-add-team-member-api-breaking-change.md
@@ -1,7 +1,5 @@
---
-kind: change
title: One more week before the "Add team member" API breaking change
-created_at: 2014-09-23
author_name: jakeboxer
---
diff --git a/content/changes/2014-10-06-new-attributes-for-issue-events-api.md b/content/changes/2014-10-06-new-attributes-for-issue-events-api.md
index 0f9e1f70db..009d26b12c 100644
--- a/content/changes/2014-10-06-new-attributes-for-issue-events-api.md
+++ b/content/changes/2014-10-06-new-attributes-for-issue-events-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New Attributes for Issue Events API
-created_at: 2014-10-06
author_name: jdpace
---
diff --git a/content/changes/2014-10-16-removed-ssl-version-3-support-from-webhooks-and-services.md b/content/changes/2014-10-16-removed-ssl-version-3-support-from-webhooks-and-services.md
index 79a4d3612f..9414413fd5 100644
--- a/content/changes/2014-10-16-removed-ssl-version-3-support-from-webhooks-and-services.md
+++ b/content/changes/2014-10-16-removed-ssl-version-3-support-from-webhooks-and-services.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Removed SSLv3 support from webhooks and services
-created_at: 2014-10-16
author_name: kdaigle
---
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 d1acc2c8a5..e74d85137c 100644
--- a/content/changes/2014-10-21-deployment-webhook-payload-changes.md
+++ b/content/changes/2014-10-21-deployment-webhook-payload-changes.md
@@ -1,11 +1,9 @@
---
-kind: change
title: Deployment webhook payload changes
-created_at: 2014-10-21
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 f9b840056c..c58ae0ebe4 100644
--- a/content/changes/2014-10-24-status-api-limits.md
+++ b/content/changes/2014-10-24-status-api-limits.md
@@ -1,17 +1,15 @@
---
-kind: change
title: Status API Limits
-created_at: 2014-10-29
author_name: rsanheim
---
To ensure a high level of service for all API consumers, we will soon limit the number of [statuses]
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
+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-11-25-the-deployments-api-is-official.md b/content/changes/2014-11-25-the-deployments-api-is-official.md
index 16b1f62554..90bcc90c4d 100644
--- a/content/changes/2014-11-25-the-deployments-api-is-official.md
+++ b/content/changes/2014-11-25-the-deployments-api-is-official.md
@@ -1,7 +1,5 @@
---
-kind: change
title: The Deployments API is official
-created_at: 2014-11-25
author_name: atmos
---
diff --git a/content/changes/2014-12-03-preview-the-new-organization-webhooks-api.md b/content/changes/2014-12-03-preview-the-new-organization-webhooks-api.md
index cfd1a78726..f64f7a2f3a 100644
--- a/content/changes/2014-12-03-preview-the-new-organization-webhooks-api.md
+++ b/content/changes/2014-12-03-preview-the-new-organization-webhooks-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview the New Organization Webhooks API
-created_at: 2014-12-03
author_name: jdpace
---
diff --git a/content/changes/2014-12-08-organization-permissions-api-preview.md b/content/changes/2014-12-08-organization-permissions-api-preview.md
index 35d8e36b10..cc32c582c4 100644
--- a/content/changes/2014-12-08-organization-permissions-api-preview.md
+++ b/content/changes/2014-12-08-organization-permissions-api-preview.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview the upcoming organization permission changes
-created_at: 2014-12-08
author_name: jakeboxer
---
**UPDATE (2014-12-12):** The [List your organizations][list-your-organizations] API is now included in this preview as well.
diff --git a/content/changes/2014-12-08-removing-authorizations-token.md b/content/changes/2014-12-08-removing-authorizations-token.md
index 566f08fc4d..994fe04884 100644
--- a/content/changes/2014-12-08-removing-authorizations-token.md
+++ b/content/changes/2014-12-08-removing-authorizations-token.md
@@ -1,13 +1,11 @@
---
-kind: change
title: Removing token attribute from Authorizations API responses
-created_at: 2014-12-08
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
@@ -62,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/2014-12-09-new-attributes-for-stars-api.md b/content/changes/2014-12-09-new-attributes-for-stars-api.md
index fd06221d83..8f0f6673d4 100644
--- a/content/changes/2014-12-09-new-attributes-for-stars-api.md
+++ b/content/changes/2014-12-09-new-attributes-for-stars-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New Attributes for Starring API
-created_at: 2014-12-09
author_name: arfon
---
diff --git a/content/changes/2014-12-12-replace-older-ssh-keys-created-by-your-application.md b/content/changes/2014-12-12-replace-older-ssh-keys-created-by-your-application.md
index 2fe014c478..41c509f4cc 100644
--- a/content/changes/2014-12-12-replace-older-ssh-keys-created-by-your-application.md
+++ b/content/changes/2014-12-12-replace-older-ssh-keys-created-by-your-application.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Replace older SSH keys created by your application
-created_at: 2014-12-12
author_name: jasonrudolph
---
Back in February, we [improved the security audit trail for SSH keys](/changes/2014-02-24-finer-grained-scopes-for-ssh-keys/#keys-are-now-immutable). Soon, organizations will be able to block access for SSH keys that were created prior to those improvements. If your application relies on [deploy keys](/guides/managing-deploy-keys/#deploy-keys) or [user keys](/v3/users/keys/) for repository access, we recommend replacing any keys created before February 24, 2014.
diff --git a/content/changes/2015-01-07-prepare-for-organization-permissions-changes.md b/content/changes/2015-01-07-prepare-for-organization-permissions-changes.md
index 83d50f2e99..9df288c09f 100644
--- a/content/changes/2015-01-07-prepare-for-organization-permissions-changes.md
+++ b/content/changes/2015-01-07-prepare-for-organization-permissions-changes.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Prepare for upcoming organization permissions changes
-created_at: 2015-01-07
author_name: jakeboxer
---
diff --git a/content/changes/2015-01-08-discovering-resources-for-a-user.md b/content/changes/2015-01-08-discovering-resources-for-a-user.md
index a257d5a67b..7687d01fcd 100644
--- a/content/changes/2015-01-08-discovering-resources-for-a-user.md
+++ b/content/changes/2015-01-08-discovering-resources-for-a-user.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "New guide: Discovering resources for a user"
-created_at: 2015-01-08
author_name: jasonrudolph
---
diff --git a/content/changes/2015-01-19-an-integrators-guide-to-organization-application-policies.md b/content/changes/2015-01-19-an-integrators-guide-to-organization-application-policies.md
index e2663bb9be..0630465be3 100644
--- a/content/changes/2015-01-19-an-integrators-guide-to-organization-application-policies.md
+++ b/content/changes/2015-01-19-an-integrators-guide-to-organization-application-policies.md
@@ -1,7 +1,5 @@
---
-kind: change
title: "An integrator's guide to organization application policies"
-created_at: 2015-01-19
author_name: pengwynn
---
diff --git a/content/changes/2015-02-03-removing-authorizations-token-update.md b/content/changes/2015-02-03-removing-authorizations-token-update.md
index 6999353c73..a7d53f037b 100644
--- a/content/changes/2015-02-03-removing-authorizations-token-update.md
+++ b/content/changes/2015-02-03-removing-authorizations-token-update.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Removing token attribute from Authorizations API responses (Update)
-created_at: 2015-02-03
author_name: ptoomey3
---
diff --git a/content/changes/2015-02-18-new-releases-api-methods.md b/content/changes/2015-02-18-new-releases-api-methods.md
index a9af04fb61..639bcb10b4 100644
--- a/content/changes/2015-02-18-new-releases-api-methods.md
+++ b/content/changes/2015-02-18-new-releases-api-methods.md
@@ -1,7 +1,5 @@
---
-kind: change
title: New Releases API methods
-created_at: 2015-02-18
author_name: pengwynn
---
diff --git a/content/changes/2015-02-20-migration-period-removing-authorizations-token.md b/content/changes/2015-02-20-migration-period-removing-authorizations-token.md
index 49d551e55b..9b154e13f2 100644
--- a/content/changes/2015-02-20-migration-period-removing-authorizations-token.md
+++ b/content/changes/2015-02-20-migration-period-removing-authorizations-token.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Breaking changes to Authorizations API responses on April 20
-created_at: 2015-02-19
author_name: ptoomey3
---
diff --git a/content/changes/2015-02-24-more-time-to-prepare-for-the-breaking-changes-to-organization-permissions.md b/content/changes/2015-02-24-more-time-to-prepare-for-the-breaking-changes-to-organization-permissions.md
index 14c9239010..0b9370abd7 100644
--- a/content/changes/2015-02-24-more-time-to-prepare-for-the-breaking-changes-to-organization-permissions.md
+++ b/content/changes/2015-02-24-more-time-to-prepare-for-the-breaking-changes-to-organization-permissions.md
@@ -1,7 +1,5 @@
---
-kind: change
title: More time to prepare for the breaking changes to organization permissions
-created_at: 2015-02-24
author_name: jakeboxer
---
diff --git a/content/changes/2015-03-09-licenses-api.md b/content/changes/2015-03-09-licenses-api.md
index d88197bad5..c38277b3b5 100644
--- a/content/changes/2015-03-09-licenses-api.md
+++ b/content/changes/2015-03-09-licenses-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Licenses API
-created_at: 2015-03-09
author_name: benbalter
---
diff --git a/content/changes/2015-04-17-preview-repository-redirects.md b/content/changes/2015-04-17-preview-repository-redirects.md
index 43df4ba747..9f185466b8 100644
--- a/content/changes/2015-04-17-preview-repository-redirects.md
+++ b/content/changes/2015-04-17-preview-repository-redirects.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Preview repository redirects
-created_at: 2015-04-17
author_name: jasonrudolph
---
diff --git a/content/changes/2015-04-20-authorizations-api-response-changes-are-now-in-effect.md b/content/changes/2015-04-20-authorizations-api-response-changes-are-now-in-effect.md
index 25dc4899ca..46a41d715e 100644
--- a/content/changes/2015-04-20-authorizations-api-response-changes-are-now-in-effect.md
+++ b/content/changes/2015-04-20-authorizations-api-response-changes-are-now-in-effect.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Authorizations API response changes are now in effect
-created_at: 2015-04-20
author_name: ptoomey3
---
diff --git a/content/changes/2015-04-21-organization-hooks-api-finalized.md b/content/changes/2015-04-21-organization-hooks-api-finalized.md
index c1bdbc0619..9d0e70aea1 100644
--- a/content/changes/2015-04-21-organization-hooks-api-finalized.md
+++ b/content/changes/2015-04-21-organization-hooks-api-finalized.md
@@ -1,11 +1,9 @@
---
-kind: change
title: Organization Webhooks API finalized
-created_at: 2015-04-21
author_name: pengwynn
---
-After [four months in preview release][ann], the [Organization Webhooks API][docs] is now considered stable and ready for production use.
+After [four months in preview release][ann], the [Organization Webhooks API][docs] is now considered stable and ready for production use.
### Preview media type no longer needed
diff --git a/content/changes/2015-05-26-repository-redirects-are-coming.md b/content/changes/2015-05-26-repository-redirects-are-coming.md
index 57cfe7cb84..ff577c0648 100644
--- a/content/changes/2015-05-26-repository-redirects-are-coming.md
+++ b/content/changes/2015-05-26-repository-redirects-are-coming.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Repository redirects are coming to API v3 in July
-created_at: 2015-05-26
author_name: jasonrudolph
---
diff --git a/content/changes/2015-06-10-breaking-changes-to-organization-permissions-coming-on-june-24.md b/content/changes/2015-06-10-breaking-changes-to-organization-permissions-coming-on-june-24.md
index e2d03d6569..d56295e02b 100644
--- a/content/changes/2015-06-10-breaking-changes-to-organization-permissions-coming-on-june-24.md
+++ b/content/changes/2015-06-10-breaking-changes-to-organization-permissions-coming-on-june-24.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Breaking changes to organization permissions coming on June 24
-created_at: 2015-06-10
author_name: jakeboxer
---
diff --git a/content/changes/2015-06-11-pages-a-records.md b/content/changes/2015-06-11-pages-a-records.md
index 16f2076255..a18197d3b8 100644
--- a/content/changes/2015-06-11-pages-a-records.md
+++ b/content/changes/2015-06-11-pages-a-records.md
@@ -1,7 +1,5 @@
---
-kind: change
title: GitHub Pages' A Records Added to Meta API
-created_at: 2015-06-11
author_name: leereilly
---
diff --git a/content/changes/2015-06-17-organizations-endpoint.md b/content/changes/2015-06-17-organizations-endpoint.md
index 4e78f681ea..39326640a0 100644
--- a/content/changes/2015-06-17-organizations-endpoint.md
+++ b/content/changes/2015-06-17-organizations-endpoint.md
@@ -1,7 +1,5 @@
---
-kind: change
title: List all organizations
-created_at: 2015-06-17
author_name: keavy
---
diff --git a/content/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions.md b/content/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions.md
index c5d4c952ca..1bd6623359 100644
--- a/content/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions.md
+++ b/content/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions.md
@@ -1,7 +1,5 @@
---
-kind: change
title: API enhancements for working with organization permissions
-created_at: 2015-06-24
author_name: jakeboxer
---
diff --git a/content/changes/2015-06-24-breaking-changes-to-organization-permissions-are-now-official.md b/content/changes/2015-06-24-breaking-changes-to-organization-permissions-are-now-official.md
index e734292909..fdecc9b91d 100644
--- a/content/changes/2015-06-24-breaking-changes-to-organization-permissions-are-now-official.md
+++ b/content/changes/2015-06-24-breaking-changes-to-organization-permissions-are-now-official.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Breaking changes to organization permissions are now official
-created_at: 2015-06-24
author_name: jakeboxer
---
diff --git a/content/changes/2015-06-24-licenses-api-update.md b/content/changes/2015-06-24-licenses-api-update.md
index 38712bc5b3..26f5b340d3 100644
--- a/content/changes/2015-06-24-licenses-api-update.md
+++ b/content/changes/2015-06-24-licenses-api-update.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Licenses API update
-created_at: 2015-06-24
author_name: mislav
---
@@ -11,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/changes/2015-07-21-automatic-redirects-for-renamed-repositories.md b/content/changes/2015-07-21-automatic-redirects-for-renamed-repositories.md
index 76c2b024f6..4477688d15 100644
--- a/content/changes/2015-07-21-automatic-redirects-for-renamed-repositories.md
+++ b/content/changes/2015-07-21-automatic-redirects-for-renamed-repositories.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Automatic redirects for renamed repositories
-created_at: 2015-07-21
author_name: jasonrudolph
---
diff --git a/content/changes/2015-07-22-more-flexible-options-for-listing-repositories.md b/content/changes/2015-07-22-more-flexible-options-for-listing-repositories.md
index 23290eaa4d..26a762e414 100644
--- a/content/changes/2015-07-22-more-flexible-options-for-listing-repositories.md
+++ b/content/changes/2015-07-22-more-flexible-options-for-listing-repositories.md
@@ -1,7 +1,5 @@
---
-kind: change
title: More flexible options for listing repositories
-created_at: 2015-07-22
author_name: jakeboxer
---
diff --git a/content/changes/2015-08-04-get-license-contents.md b/content/changes/2015-08-04-get-license-contents.md
index 69da1516b1..676bfbc447 100644
--- a/content/changes/2015-08-04-get-license-contents.md
+++ b/content/changes/2015-08-04-get-license-contents.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Get the contents of a repository’s license
-created_at: 2015-08-04
author_name: benbalter
---
diff --git a/content/changes/2015-09-03-ensure-your-app-is-ready-for-protected-branches.md b/content/changes/2015-09-03-ensure-your-app-is-ready-for-protected-branches.md
index e750d08810..e32d9ef35f 100644
--- a/content/changes/2015-09-03-ensure-your-app-is-ready-for-protected-branches.md
+++ b/content/changes/2015-09-03-ensure-your-app-is-ready-for-protected-branches.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Ensure your app is ready for Protected Branches
-created_at: 2015-09-03
author_name: aroben
---
diff --git a/content/changes/2015-11-11-protected-branches-api.md b/content/changes/2015-11-11-protected-branches-api.md
index 050e89c0c1..6b09f0ac9b 100644
--- a/content/changes/2015-11-11-protected-branches-api.md
+++ b/content/changes/2015-11-11-protected-branches-api.md
@@ -1,10 +1,10 @@
---
-kind: change
title: Protected Branches API Preview Period
-created_at: 2015-11-11
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:
@@ -35,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-01-05-api-enhancements-for-working-with-organization-permissions-are-now-official.md b/content/changes/2016-01-05-api-enhancements-for-working-with-organization-permissions-are-now-official.md
index af17de6f11..84fb64bbb2 100644
--- a/content/changes/2016-01-05-api-enhancements-for-working-with-organization-permissions-are-now-official.md
+++ b/content/changes/2016-01-05-api-enhancements-for-working-with-organization-permissions-are-now-official.md
@@ -1,7 +1,5 @@
---
-kind: change
title: API enhancements for working with organization permissions are now official
-created_at: 2016-01-05
author_name: jakeboxer
---
diff --git a/content/changes/2016-02-11-issue-locking-api.md b/content/changes/2016-02-11-issue-locking-api.md
index 792f453107..07177d4910 100644
--- a/content/changes/2016-02-11-issue-locking-api.md
+++ b/content/changes/2016-02-11-issue-locking-api.md
@@ -1,7 +1,5 @@
---
-kind: change
title: Issue Locking and Unlocking API Preview Period
-created_at: 2016-02-11
author_name: davidcelis
---
diff --git a/content/changes/2016-02-19-source-import-preview-api.md b/content/changes/2016-02-19-source-import-preview-api.md
new file mode 100644
index 0000000000..1caf3c446e
--- /dev/null
+++ b/content/changes/2016-02-19-source-import-preview-api.md
@@ -0,0 +1,18 @@
+---
+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://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:
+
+ application/vnd.github.barred-rock-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/migration/source_imports/
+[contact]: https://github.com/contact?form%5Bsubject%5D=Source+Import+API
diff --git a/content/changes/2016-02-24-commit-reference-sha-api.md b/content/changes/2016-02-24-commit-reference-sha-api.md
new file mode 100644
index 0000000000..e78af07bab
--- /dev/null
+++ b/content/changes/2016-02-24-commit-reference-sha-api.md
@@ -0,0 +1,41 @@
+---
+title: Commit Reference SHA-1 Preview Period
+author_name: mikemcquaid
+---
+
+We're introducing a new API media type to allow users to get the SHA-1 of a commit reference. This can be useful in working out if you have the latest version of a remote branch based on your local branch's SHA-1. Developers with read access to a repository can start experimenting with this new media type today during the preview period.
+
+To get the commit reference's SHA-1, make a `GET` request to the repository's reference:
+
+``` command-line
+$ curl "https://api.github.com/repos/Homebrew/homebrew/commits/master" \
+ -H "Accept: application/vnd.github.chitauri-preview+sha"
+```
+
+To check if a remote branch's SHA-1 is the same as your local branch's SHA-1, make a `GET` request to the repository's branch and provide the current SHA-1 for the local branch as the ETag:
+
+``` command-line
+$ curl "https://api.github.com/repos/Homebrew/homebrew/commits/master" \
+ -H "Accept: application/vnd.github.chitauri-preview+sha" \
+ -H "If-None-Match: \"814412cfbd631109df337e16c807207e78c0d24e\""
+```
+
+If the remote and your local branch point to the same SHA-1 then this call will return a `304 Unmodified` status code (and not use your rate limit).
+
+You can see an example of this API in a pull request to Homebrew/homebrew's updater: https://github.com/Homebrew/homebrew/pull/49219.
+
+#### How can I try it?
+
+To use this new API media type during the preview period, you’ll need to provide the following custom [media type][media-types] in the `Accept` header:
+
+```
+application/vnd.github.chitauri-preview+sha
+```
+
+During the preview period, we may change aspects of this API media type 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.
+
+Take a look at [the documentation][docs] and, if you have any questions, please [get in touch][contact].
+
+[contact]: https://github.com/contact?form%5Bsubject%5D=Commit+Reference+SHA-1+Preview
+[docs]: /v3/repos/commits/#get-the-sha-1-of-a-commit-reference
+[media-types]: /v3/media/
diff --git a/content/changes/2016-03-15-new-webhook-actions.md b/content/changes/2016-03-15-new-webhook-actions.md
new file mode 100644
index 0000000000..82e916d655
--- /dev/null
+++ b/content/changes/2016-03-15-new-webhook-actions.md
@@ -0,0 +1,53 @@
+---
+title: New webhook event actions are coming
+author_name: davidcelis
+---
+
+We will soon begin introducing new `action` values for several existing webhook events. If you currently subscribe to webhooks but do not check the payload's `action` value, you may end up incorrectly processing events after this change is released. To ensure that your webhook processing is not affected by these new `action` values, **you should audit your webhook processing logic by April 15th, 2016**.
+
+We are providing an advance notice to warn of these changes. In the future, we may continue adding new actions without providing further warning.
+
+### A brief overview of GitHub webhook actions
+
+Webhook events can have multiple actions. For example, the [`IssuesEvent`](https://developer.github.com/v3/activity/events/types/#issuesevent) has several possible actions. These include `opened` when the issue is created, `closed` when the issue is closed, and `assigned` when the issue is assigned to someone. Historically, we haven't added new actions to webhook events that have only one action. However, as GitHub's feature set grows, we may occasionally add new actions to existing event types. We encourage you to take some time and ensure that your application explicitly checks the action before doing any processing.
+
+### What to avoid when working with event actions
+
+Here's an example of functionality that **will not work** when attempting to process an `IssuesEvent`. In this example, the `process_closed` method will be called for any event action which is not `opened` or `assigned`. This means that the `process_closed` method will be called for events with the `closed` action, but also other events with actions other than `opened` or `assigned` that are delivered to the webhook.
+
+```ruby
+# The following is not future-proof!
+case action
+when "opened"
+ process_opened
+when "assigned"
+ process_assigned
+else
+ process_closed
+end
+```
+
+### How to work with new event actions
+
+We suggest that you explicitly check event actions and act accordingly. In this example, the `closed` action is checked first before calling the `process_closed` method. Additionally, for unknown actions, we log that something new was encountered:
+
+```ruby
+# The following is recommended
+case action
+when "opened"
+ process_opened
+when "assigned"
+ process_assigned
+when "closed"
+ process_closed
+else
+ puts "Ooohh, something new from GitHub!"
+end
+```
+
+We may also add new webhook event types from time to time. If your webhook is configured to "Send me **everything**", your code should also explicitly check for the event type in a similar way as we have done with checking for the action type above. Take a look at our [integrators best practices guide][best-practices] for more tips.
+
+If you have any questions or feedback, please [get in touch][get-in-touch].
+
+[best-practices]: https://developer.github.com/guides/best-practices-for-integrators/
+[get-in-touch]: https://github.com/contact?form[subject]=New+Webhook+Actions
diff --git a/content/changes/2016-03-17-the-451-status-code-is-now-supported.md b/content/changes/2016-03-17-the-451-status-code-is-now-supported.md
new file mode 100644
index 0000000000..d9c1d1a451
--- /dev/null
+++ b/content/changes/2016-03-17-the-451-status-code-is-now-supported.md
@@ -0,0 +1,26 @@
+---
+title: The 451 status code is now supported
+author_name: gjtorikian
+---
+
+In December 2015, [the IETF ratified status code `451`](https://datatracker.ietf.org/doc/rfc7725/). A `451` response indicates that a resource is unavailable due to an external legal request.
+
+The GitHub API will now respond with a `451` status code for resources it has been asked to take down due to a DMCA notice. For example:
+
+``` command-line
+$ curl https://api.github.com/repos/github/a-repository-that-s-been-taken-down
+> HTTP/1.1 451
+> Server: GitHub.com
+
+> {
+> "message": "Repository access blocked",
+> "block": {
+> "reason": "dmca",
+> "created_at": "2016-03-17T15:39:46-07:00"
+> }
+> }
+```
+
+This `451` code will be returned for repositories and gists. Previously, the API responded with a `403 - Forbidden`. Aside from the semantic difference, we feel that it's important for users to know precisely why their data cannot be served.
+
+If you're receiving a `451` due to a DMCA takedown, please read our article on [submitting a DMCA counter notice](https://help.github.com/articles/guide-to-submitting-a-dmca-counter-notice/) and know your rights. For more information, see [GitHub's DMCA Takedown Policy](https://help.github.com/articles/dmca-takedown-policy/).
diff --git a/content/changes/2016-04-01-squash-api-preview.md b/content/changes/2016-04-01-squash-api-preview.md
new file mode 100644
index 0000000000..9d43ccac5e
--- /dev/null
+++ b/content/changes/2016-04-01-squash-api-preview.md
@@ -0,0 +1,29 @@
+---
+title: Preview Squash Support for the Pull Request Merge API
+author_name: scottjg
+---
+
+With the [recent addition](https://github.com/blog/2141-squash-your-commits) of squashing Pull Requests via the merge button, we're adding support to squash Pull Requests in the API as well. You can squash a pull request in the [Pull Request Merge API][docs] during the preview period by providing a custom [media type][media-type] in the `Accept` header:
+
+ application/vnd.github.polaris-preview
+
+For example:
+
+``` command-line
+curl "https://api.github.com/repos/github/hubot/pulls/123/merge" \
+ -XPUT \
+ -H 'Authorization: token TOKEN' \
+ -H "Accept: application/vnd.github.polaris-preview" \
+ -d '{
+ "squash": true,
+ "commit_title": "Never tell me the odds"
+ }'
+```
+
+During the preview period, we may change aspects of these API methods 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
+[docs]: /v3/pulls/#merge-a-pull-request-merge-button
+[contact]: https://github.com/contact?form%5Bsubject%5D=Squash+API+Preview
diff --git a/content/changes/2016-04-04-git-signing-api-preview.md b/content/changes/2016-04-04-git-signing-api-preview.md
new file mode 100644
index 0000000000..cd8a9364ea
--- /dev/null
+++ b/content/changes/2016-04-04-git-signing-api-preview.md
@@ -0,0 +1,29 @@
+---
+title: Preview support for Git signing
+author_name: mastahyeti
+---
+
+GitHub [recently started verifying GPG signed commits and tags](https://github.com/blog/2144-gpg-signature-verification). We are adding API support for signature verification and user GPG key management as well. You can enable these changes during the preview period by providing a custom [media type][media-type] in the `Accept` header:
+
+ application/vnd.github.cryptographer-preview
+
+For example:
+
+``` command-line
+curl "https://api.github.com/user/gpg_keys" \
+ -H 'Authorization: token TOKEN' \
+ -H "Accept: application/vnd.github.cryptographer-preview" \
+```
+
+You can learn more about the new signature verification response objects in the updated [repository commit][repo-commit-doc], [Git commit][git-commit-doc], and [Git tag][git-tag-doc] documentation. There is also new [GPG key management][gpg-keys-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
+[repo-commit-doc]: /v3/repos/commits
+[git-commit-doc]: /v3/git/commits
+[git-tag-doc]: /v3/git/tags
+[gpg-keys-doc]: /v3/users/gpg_keys
+[contact]: https://github.com/contact?form%5Bsubject%5D=Squash+API+Preview
diff --git a/content/changes/2016-04-06-deployment-and-deployment-status-enhancements.md b/content/changes/2016-04-06-deployment-and-deployment-status-enhancements.md
new file mode 100644
index 0000000000..c13aa14ccb
--- /dev/null
+++ b/content/changes/2016-04-06-deployment-and-deployment-status-enhancements.md
@@ -0,0 +1,49 @@
+---
+title: Deployment and DeploymentStatus API enhancements preview period
+author_name: tarebyte
+---
+
+We've expanded our Deployments APIs to accommodate more powerful deployment practices and to lay the foundation for a more seamless integration of deployments within GitHub.
+
+## Link to a live deployment
+
+To enable easy access to a live version of a deployment, we've added an `environment_url` field to the Deployments API. This environment will be exposed as a link in the Pull Request timeline to enable users to directly access a running version of their code without leaving the context of their work.
+
+*Note: To add some clarity, we've renamed the `target_url` field to `log_url`. We will continue accept `target_url` to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Future API versions might not support `target_url`*.
+
+## Inactive deployment status
+
+We recognize that deployments in many common practices don't last forever. So, we've added a new `inactive` state to Deployment Statuses. You can use this state to communicate that a deployment is no longer active (e.g. something different has been deployed to the environment or the environment has been destroyed).
+
+## More information about environments
+
+We've expanded our Deployments API to provide additional information about the environments associated with deployments.
+
+We've added a new `transient_environment` field to allow you to communicate that an environment is specific to a deployment and will no longer exist at some point in the future (e.g. a temporary testing environment like a [Heroku Review App][heroku-review-app]). By pairing this with other additions, we can determine that an `inactive` deployment associated with a `transient_environment` has an `environment_url` that is no longer accessible.
+
+Similarly, we've added a new `production_environment` field to allow you to communicate that an environment is one with which end users directly interact. We automatically set `production_environment` to `true` if the value for `environment` is ``"production"``.
+
+## Automatic creation of inactive statuses
+
+Each time we receive a new successful deployment status, we automatically add a new `inactive` status to all previous deployments made within the relevant repository to the same environment (based on the value of `environment`) given the environment is both non-transient and non-production. You can opt out of this behavior by passing `false` with the new `auto_inactive` parameter.
+
+For example, if `feature-branch` within `https://github.com/user/repository` is deployed to an environment named `staging` (which is a non-transient, non-production environment) and `bugfix-branch` within `https://github.com/user/repository` is later deployed to an environment named `staging`, we would automatically create a new `inactive` status for the deployment associated with `feature-branch`.
+
+#### How can I try it?
+
+Starting today, these API enhancements are available for developers to preview. At the end of the preview period, these enhancements will become official components of the GitHub API.
+
+To access the API during the preview period, you must provide a custom [media type][media-types] in the Accept header:
+
+```
+application/vnd.github.ant-man-preview+json
+```
+
+During the preview period, we may change aspects of these enhancements. If we do, we will announce the changes on the developer blog, but we will not provide any advance notice.
+
+Take a look at [the documentation][docs] for full details. We would love to hear your thoughts on these enhancements. If you have any questions or feedback, please [get in touch with us][contact]!
+
+[contact]: https://github.com/contact?form%5Bsubject%5D=Deployment+and+DeploymentStatus+API+enhancements+preview+period
+[media-types]: /v3/media/
+[heroku-review-app]: https://devcenter.heroku.com/articles/github-integration-review-apps
+[docs]:https://developer.github.com/v3/repos/deployments/
diff --git a/content/changes/2016-04-12-commit-reference-sha-api-is-now-official.md b/content/changes/2016-04-12-commit-reference-sha-api-is-now-official.md
new file mode 100644
index 0000000000..adbec89580
--- /dev/null
+++ b/content/changes/2016-04-12-commit-reference-sha-api-is-now-official.md
@@ -0,0 +1,14 @@
+---
+title: Commit Reference SHA-1 API is now official
+author_name: mikemcquaid
+---
+
+We're making the [Commit Reference SHA-1 API][api-enhancements-blog-post] part of the official GitHub API.
+
+During the preview period you needed to provide the `application/vnd.github.chitauri-preview+sha` preview media type in the `Accept` header to opt-in to the changes. Now that the preview period has ended the custom [media type][custom-media-types] has changed to `application/vnd.github.v3.sha` (but the preview type will continue to work).
+
+If you have any questions or feedback, please [get in touch with us][contact]!
+
+[api-enhancements-blog-post]: /changes/2016-02-24-commit-reference-sha-api/
+[custom-media-types]: /v3/media/
+[contact]: https://github.com/contact?form[subject]=Commit+Reference+SHA-1+API
diff --git a/content/changes/2016-04-18-new-webhook-actions-are-live.md b/content/changes/2016-04-18-new-webhook-actions-are-live.md
new file mode 100644
index 0000000000..40c28b16ce
--- /dev/null
+++ b/content/changes/2016-04-18-new-webhook-actions-are-live.md
@@ -0,0 +1,65 @@
+---
+title: New webhook event actions are now live
+author_name: davidcelis
+---
+
+As [promised last month][notice], we've expanded several webhook events with new functionality. Webhook events involving repositories, issues, and comments have all been updated to include new actions.
+
+Repository events will now fire when a repository is deleted, made public, or made private. In addition, while repository creation events will still only fire for organizations, the new repository event actions can be delivered for user-owned repositories.
+
+Events for issues, pull requests, and comments have also been updated and will now fire when these objects are edited or deleted. When an issue, pull request, or a comment has been edited, the event's payload will include a "changes" object. For example, if you've updated the title and body of an issue, the webhook payload informs you of what the issue used to look like:
+
+```json
+{
+ "action": "edited",
+ "changes": {
+ "title": { "from": "This is the old title." },
+ "body": { "from": "This is the old body." }
+ },
+ "issue": {
+ "title": "This is the new title.",
+ "body": "This is the new body."
+ }
+}
+```
+
+The new values will be present in the `issue` object itself, as detailed above. Unchanged values will not be present within the `changes` object. Comment edits follow a similar pattern, though because they have no titles, the only change included in the payload would be the comment's body.
+
+## List of comprehensive changes
+
+New actions were added to five events, all of which are detailed below.
+
+### [RepositoryEvent][repository-event]
+
+* `deleted`: sent when a user-owned or organization-owned repository is deleted.
+* `publicized`: sent when a user-owned or organization-owned repository is switched from private to public.
+* `privatized`: sent when a user-owned or organization-owned repository is switched from public to private.
+
+### [IssuesEvent][issues-event]
+
+* `edited`: sent when the title and/or body of an issue is edited.
+
+### [IssueCommentEvent][issue-comment-event]
+
+* `edited`: sent when a comment on an issue or pull request is edited
+* `deleted`: sent when a comment on an issue or pull request is deleted
+
+### [PullRequestEvent][pull-request-event]
+
+* `edited`: sent when the title and/or body of a pull request is edited.
+
+### [PullRequestReviewCommentEvent][pull-request-review-comment-event]
+
+* `edited`: sent when a comment on a pull request's unified diff (in the Files Changed tab) is edited
+* `deleted`: sent when a comment on a pull request's unified diff (in the Files Changed tab) is deleted
+
+Take a look at [the documentation][docs] for full details. If you have any questions or feedback, please [get in touch][get-in-touch].
+
+[docs]: https://developer.github.com/webhooks/
+[get-in-touch]: https://github.com/contact?form[subject]=New+Webhook+Actions
+[issue-comment-event]: https://developer.github.com/v3/activity/events/types/#issuecommentevent
+[issues-event]: https://developer.github.com/v3/activity/events/types/#issuesevent
+[notice]: https://developer.github.com/changes/2016-03-15-new-webhook-actions/
+[pull-request-event]: https://developer.github.com/v3/activity/events/types/#pullrequestevent
+[pull-request-review-comment-event]: https://developer.github.com/v3/activity/events/types/#pullrequestreviewcommentevent
+[repository-event]: https://developer.github.com/v3/activity/events/types/#repositoryevent
diff --git a/content/changes/2016-04-21-oauth-authorizations-grants-api-preview.md b/content/changes/2016-04-21-oauth-authorizations-grants-api-preview.md
new file mode 100644
index 0000000000..7e60f4baec
--- /dev/null
+++ b/content/changes/2016-04-21-oauth-authorizations-grants-api-preview.md
@@ -0,0 +1,29 @@
+---
+title: Preview support for OAuth authorizations grants API
+author_name: ptoomey3
+---
+
+GitHub recently made changes to [the application authorizations settings screen within GitHub][authorized-application-listing] to display one entry for each OAuth application a user has authorized. Previously this screen showed one entry for each OAuth token that was generated by an OAuth application. For example, if you installed two instances of GitHub Desktop, you would see one entry for each installation. To simplify OAuth application management, we now show a single entry for each OAuth application. For OAuth applications that use the [web flow][web-flow] this was not a problem, since the web flow never generates more than one token for a given OAuth application and user. However, going forward, GitHub would like to allow all OAuth applications, including those that use the web flow, to generate more than one token.
+
+In preparation for that change, we are adding API support to simplify management of OAuth applications that matches what is available on GitHub.com. You can enable these changes during the preview period by providing a custom [media type][media-type] in the `Accept` header:
+
+ application/vnd.github.damage-preview
+
+For example:
+
+``` command-line
+curl -u username "https://api.github.com/applications/grants" \
+ -H "Accept: application/vnd.github.damage-preview"
+```
+
+You can learn more about the new APIs in the [OAuth authorizations][oauth-authorizations-api] 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
+[oauth-authorizations-api]: /v3/oauth_authorizations
+[authorized-application-listing]: https://github.com/settings/applications#authorized
+[contact]: https://github.com/contact?form%5Bsubject%5D=OAuth+Authorizations+Grants+API+Preview
+[web-flow]: /v3/oauth/#web-application-flow
diff --git a/content/changes/2016-05-03-source-import-api-enhancements-for-working-with-git-lfs.md b/content/changes/2016-05-03-source-import-api-enhancements-for-working-with-git-lfs.md
new file mode 100644
index 0000000000..4f7f8bb308
--- /dev/null
+++ b/content/changes/2016-05-03-source-import-api-enhancements-for-working-with-git-lfs.md
@@ -0,0 +1,40 @@
+---
+title: Source Import API enhancements for working with Git LFS
+author_name: lizzhale
+---
+
+Today we're introducing enhancements to the [Source Import API][docs] to support importing repositories with files larger than 100MB.
+
+**Changes to parameters for starting an import**
+
+[Starting an import][start-an-import] no longer requires a `vcs` parameter. Please be aware that without this parameter, the import job will take additional time to detect the vcs type before beginning the import. This detection step will be reflected in the response.
+
+**New methods**
+
+We've added 3 new methods that will enable API consumers to:
+
+ * [update][update-existing-import] the authentication or project choice for an import. If no parameters are provided during the request, the import will be restarted. Please note that this is a **breaking change**. Updating authentication for the originating URL is no longer supported through the [start an import][start-an-import] method. Please update your applications to use the new method.
+
+ * [set their preference][set-git-lfs-preference] for using Git LFS to import files larger than 100MB.
+
+ * [list all the files larger than 100MB][get-large-files] that were found during the import.
+
+**New attributes for Git LFS**
+
+Several new response attributes (`use_lfs`, `has_large_files`, `large_files_size`, `large_files`) were added to provide details regarding the large files found during the import. You can read more about the attributes [here][git-lfs-related-fields].
+
+As before, to access the API during the preview period, you must provide a custom [media type][media-type] in the `Accept` header:
+
+ application/vnd.github.barred-rock-preview
+
+For more information, see the [Source Import API documentation][docs], and if you have any questions or feedback, please [let us know][contact].
+
+
+[docs]: /v3/migration/source_imports/
+[start-an-import]: /v3/migration/source_imports/#start-an-import
+[update-existing-import]: /v3/migration/source_imports/#update-existing-import
+[set-git-lfs-preference]: /v3/migration/source_imports/#set-git-lfs-preference
+[get-large-files]: /v3/migration/source_imports/#get-large-files
+[git-lfs-related-fields]: /v3/migration/source_imports/#git-lfs-related-fields
+[media-type]: /v3/media
+[contact]: https://github.com/contact?form%5Bsubject%5D=Source+Import+API
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/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/changes/2016-06-07-reactions-api-update.md b/content/changes/2016-06-07-reactions-api-update.md
new file mode 100644
index 0000000000..017d189394
--- /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/content/changes/2016-06-14-repository-invitations.md b/content/changes/2016-06-14-repository-invitations.md
new file mode 100644
index 0000000000..00cddde89d
--- /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/repos/github/hubot/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=Repository+Invitations+API+Preview
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..81fb174003
--- /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+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]!
+
+[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/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/changes/2016-07-06-github-pages-preview-api.md b/content/changes/2016-07-06-github-pages-preview-api.md
new file mode 100644
index 0000000000..ab14cbee46
--- /dev/null
+++ b/content/changes/2016-07-06-github-pages-preview-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/repos/github/developer.github.com/pages/builds" \
+ -X POST
+ -H 'Authorization: token TOKEN' \
+ -H "Accept: application/vnd.github.mister-fantastic-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/repos/github/developer.github.com/pages" \
+ -H 'Authorization: token TOKEN' \
+ -H "Accept: application/vnd.github.mister-fantastic-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/changes/2016-07-12-ending-multiple-assignees-preview-period.md b/content/changes/2016-07-12-ending-multiple-assignees-preview-period.md
new file mode 100644
index 0000000000..13f6fc318b
--- /dev/null
+++ b/content/changes/2016-07-12-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/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/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/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/changes/2016-5-27-multiple-assignees.md b/content/changes/2016-5-27-multiple-assignees.md
new file mode 100644
index 0000000000..1a9c70fbb0
--- /dev/null
+++ b/content/changes/2016-5-27-multiple-assignees.md
@@ -0,0 +1,28 @@
+---
+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.
+
+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
+
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!
diff --git a/content/guides/best-practices-for-integrators.md b/content/guides/best-practices-for-integrators.md
index c2f07a570e..f0cd17c9b4 100644
--- a/content/guides/best-practices-for-integrators.md
+++ b/content/guides/best-practices-for-integrators.md
@@ -10,7 +10,7 @@ Interested in integrating with the GitHub platform? [You're in good company](htt
## Secure payloads delivered from GitHub
-It's very important that you secure [the payloads sent from GitHub](/v3/activity/events/types/). Although no personal information (like passwords) is ever transmitted in a payload, leaking *any* information is not good. Some information that might be sensitive include committer email address or the names of private repositories.
+It's very important that you secure [the payloads sent from GitHub][event-types]. Although no personal information (like passwords) is ever transmitted in a payload, leaking *any* information is not good. Some information that might be sensitive include committer email address or the names of private repositories.
There are three steps you can take to secure receipt of payloads delivered by GitHub:
@@ -54,6 +54,76 @@ For the stability of your app, you shouldn't try to parse this data or try to gu
For example, when working with paginated results, it's often tempting to construct URLs that append `?page=` to the end. Avoid that temptation. [Our guide on pagination](/guides/traversing-with-pagination) offers some safe tips on dependably following paginated results.
+## Check the event type and action before processing the event
+
+There are multiple [webhook event types][event-types], and each event can have multiple actions. As GitHub's feature set grows, we will occasionally add new event types or add new actions to existing event types. Ensure that your application explicitly checks the type and action of an event before doing any webhook processing. The `X-GitHub-Event` request header can be used to know which event has been received so that processing can be handled appropriately. Similarly, the payload has a top-level `action` key that can be used to know which action was taken on the relevant object.
+
+For example, if you have configured a GitHub webhook to "Send me **everything**", your application will begin receiving new event types and actions as they are added. It is therefore **not recommended to use any sort of catch-all else clause**. Take the following code example:
+
+```ruby
+# Not recommended: a catch-all else clause
+def receive
+ event_type = request.headers["X-GitHub-Event"]
+ payload = request.body
+
+ case event_type
+ when "repository"
+ process_repository(payload)
+ when "issues"
+ process_issues(payload)
+ else
+ process_pull_requests
+ end
+end
+```
+
+In this code example, the `process_repository` and `process_issues` methods will be correctly called if a `repository` or `issues` event was received. However, any other event type would result in `process_pull_requests` being called. As new event types are added, this would result in incorrect behavior and new event types would be processed in the same way that a `pull_request` event would be processed.
+
+Instead, we suggest explicitly checking event types and acting accordingly. In the following code example, we explicitly check for a `pull_request` event and the `else` clause simply logs that we've received a new event type:
+
+```ruby
+# Recommended: explicitly check each event type
+def receive
+ event_type = request.headers["X-GitHub-Event"]
+ payload = JSON.parse(request.body)
+
+ case event_type
+ when "repository"
+ process_repository(payload)
+ when "issues"
+ process_issue(payload)
+ when "pull_request"
+ process_pull_requests(payload)
+ else
+ puts "Oooh, something new from GitHub: #{event_type}"
+ end
+end
+```
+
+Because each event can also have multiple actions, it's recommended that actions are checked similarly. For example, the [`IssuesEvent`](https://developer.github.com/v3/activity/events/types/#issuesevent) has several possible actions. These include `opened` when the issue is created, `closed` when the issue is closed, and `assigned` when the issue is assigned to someone.
+
+As with adding event types, we may add new actions to existing events. It is therefore again **not recommended to use any sort of catch-all else clause** when checking an event's action. Instead, we suggest explicitly checking event actions as we did with the event type. An example of this looks very similar to what we suggested for event types above:
+
+```ruby
+# Recommended: explicitly check each action
+def process_issue(payload)
+ case payload["action"]
+ when "opened"
+ process_issue_opened(payload)
+ when "assigned"
+ process_issue_assigned(payload)
+ when "closed"
+ process_issue_closed(payload)
+ else
+ puts "Oooh, something new from GitHub: #{payload["action"]}"
+ end
+end
+```
+
+In this example the `closed` action is checked first before calling the `process_closed` method. Any unidentified actions are logged for future reference.
+
+{% if page.version == 'dotcom' %}
+
## Dealing with rate limits
The GitHub API [rate limit](/v3/#rate-limiting) ensures that the API is fast and available for everyone.
@@ -79,6 +149,8 @@ To avoid hitting this limit, you should ensure your application follows the guid
We reserve the right to change these guidelines as needed to ensure availability.
+{% endif %}
+
## Dealing with API errors
Although your code would never introduce a bug, you may find that you've encountered successive errors when trying to access the API.
@@ -86,3 +158,5 @@ Although your code would never introduce a bug, you may find that you've encount
Rather than ignore repeated `4xx` and `5xx` status codes, you should ensure that you're correctly interacting with the API. For example, if an endpoint requests a string and you're passing it a numeric value, you're going to receive a `5xx` validation error, and your call won't succeed. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a `4xx` error.
Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse.
+
+[event-types]: /v3/activity/events/types/
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 a55fe5e1e4..8644ae2d2f 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
@@ -67,7 +67,7 @@ Great! Click on **Let me select individual events.**, and select the following:
* 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
@@ -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.
@@ -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')
@@ -161,8 +161,7 @@ to simulate work that's going on. During that processing, we also make a call to
`create_deployment_status`, which lets a receiver know what's going on, as we
switch the status to `pending`.
-After the deployment is finished, we set the status to `success`. You'll notice
-that this pattern is the exact same as when we you your CI statuses.
+After the deployment is finished, we set the status to `success`.
## Conclusion
@@ -176,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/guides/getting-started.md b/content/guides/getting-started.md
index bebccc05ac..f1dd314067 100644
--- a/content/guides/getting-started.md
+++ b/content/guides/getting-started.md
@@ -22,7 +22,7 @@ Let's start by testing our setup. Open up a command prompt and enter the
following command:
``` command-line
-$ curl https://{{ site.data.variables.product.api_url_pre }}/zen
+$ curl {{ site.data.variables.product.api_url_pre }}/zen
> Keep it logically awesome.
```
@@ -33,12 +33,12 @@ Next, let's `GET` [Chris Wanstrath's][defunkt github] [GitHub profile][users api
``` command-line
# GET /users/defunkt
-$ curl https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ curl {{ site.data.variables.product.api_url_pre }}/users/defunkt
> {
> "login": "defunkt",
> "id": 2,
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/users/defunkt",
+> "url": "{{ site.data.variables.product.api_url_pre }}/users/defunkt",
> "html_url": "https://github.com/defunkt",
> ...
> }
@@ -47,7 +47,7 @@ $ curl https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
Mmmmm, tastes like [JSON][json]. Let's add the `-i` flag to include headers:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ curl -i {{ site.data.variables.product.api_url_pre }}/users/defunkt
> HTTP/1.1 200 OK
> Server: GitHub.com
@@ -69,7 +69,7 @@ $ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
> {
> "login": "defunkt",
> "id": 2,
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/users/defunkt",
+> "url": "{{ site.data.variables.product.api_url_pre }}/users/defunkt",
> "html_url": "https://github.com/defunkt",
> ...
> }
@@ -101,7 +101,7 @@ The easiest way to authenticate with the {{ site.data.variables.product.product_
username and password via Basic Authentication.
``` command-line
-$ curl -i -u your_username https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ curl -i -u your_username {{ site.data.variables.product.api_url_pre }}/users/defunkt
> Enter host password for user your_username:
```
@@ -121,7 +121,7 @@ If you have [two-factor authentication][2fa] enabled, the API will return a
`401 Unauthorized` error code for the above request (and every other API request):
``` command-line
-$ curl -i -u your_username https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ curl -i -u your_username {{ site.data.variables.product.api_url_pre }}/users/defunkt
> Enter host password for user your_username:
@@ -145,7 +145,7 @@ associated with your {{ site.data.variables.product.product_name }} account. For
[your own user profile][auth user api]:
``` command-line
-$ curl -i -u your_username https://{{ site.data.variables.product.api_url_pre }}/user
+$ curl -i -u your_username {{ site.data.variables.product.api_url_pre }}/user
> {
> ...
@@ -196,10 +196,10 @@ to create an OAuth token. Try pasting and running the following command:
``` command-line
$ curl -i -u your_username -d '{"scopes": ["repo", "user"], "note": "getting-started"}' \
-$ https://{{ site.data.variables.product.api_url_pre }}/authorizations
+$ {{ site.data.variables.product.api_url_pre }}/authorizations
> HTTP/1.1 201 Created
-> Location: https://{{ site.data.variables.product.api_url_pre }}/authorizations/2
+> Location: {{ site.data.variables.product.api_url_pre }}/authorizations/2
> Content-Length: 384
> {
@@ -209,7 +209,7 @@ $ https://{{ site.data.variables.product.api_url_pre }}/authorizations
> ],
> "token": "5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4",
> "updated_at": "2012-11-14T14:04:24Z",
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/authorizations/2",
+> "url": "{{ site.data.variables.product.api_url_pre }}/authorizations/2",
> "app": {
> "url": "https://developer.github.com/v3/oauth/#oauth-authorizations-api",
> "name": "GitHub API"
@@ -246,7 +246,7 @@ in the [X-GitHub-OTP request header][2fa header]:
``` command-line
$ curl -i -u your_username -H "X-GitHub-OTP: your_2fa_OTP_code" \
-d '{"scopes": ["repo", "user"], "note": "getting-started"}' \
- https://{{ site.data.variables.product.api_url_pre }}/authorizations
+ {{ site.data.variables.product.api_url_pre }}/authorizations
```
If you enabled 2FA with a mobile application, go ahead and get an OTP code from
@@ -259,7 +259,7 @@ in the rest of our examples. Let's grab our own user info again, using OAuth thi
``` command-line
$ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
- https://{{ site.data.variables.product.api_url_pre }}/user
+ {{ site.data.variables.product.api_url_pre }}/user
```
**Treat OAuth tokens like passwords!** Don't share them with other users or store
@@ -276,26 +276,26 @@ information. We can [`GET` repository details][get repo] in the same way we fetc
details earlier:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/repos/twbs/bootstrap
+$ curl -i {{ site.data.variables.product.api_url_pre }}/repos/twbs/bootstrap
```
In the same way, we can [view repositories for the authenticated user][user repos api]:
``` command-line
$ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
- https://{{ site.data.variables.product.api_url_pre }}/user/repos
+ {{ site.data.variables.product.api_url_pre }}/user/repos
```
Or, we can [list repositories for another user][other user repos api]:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/technoweenie/repos
+$ curl -i {{ site.data.variables.product.api_url_pre }}/users/technoweenie/repos
```
Or, we can [list repositories for an organization][org repos api]:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/orgs/mozilla/repos
+$ curl -i {{ site.data.variables.product.api_url_pre }}/orgs/mozilla/repos
```
The information returned from these calls will depend on how we authenticate:
@@ -311,7 +311,7 @@ for the repository. In this way, we can fetch only directly-owned repositories,
organization repositories, or repositories the user collaborates on via a team.
``` command-line
-$ curl -i "https://{{ site.data.variables.product.api_url_pre }}/users/technoweenie/repos?type=owner"
+$ curl -i "{{ site.data.variables.product.api_url_pre }}/users/technoweenie/repos?type=owner"
```
In this example, we grab only those repositories that technoweenie owns, not the
@@ -333,7 +333,7 @@ $ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
"private": true, \
"gitignore_template": "nanoc" \
}' \
- https://{{ site.data.variables.product.api_url_pre }}/user/repos
+ {{ site.data.variables.product.api_url_pre }}/user/repos
```
In this minimal example, we create a new repository for our blog (to be served
@@ -348,7 +348,7 @@ an owner, just change the API method from `/user/repos` to `/orgs//rep
Next, let's fetch our newly created repository:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/blog
+$ curl -i {{ site.data.variables.product.api_url_pre }}/repos/pengwynn/blog
> HTTP/1.1 404 Not Found
@@ -375,7 +375,7 @@ authenticated user. To [see all your issues][get issues api], call `GET /issues`
``` command-line
$ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
- https://{{ site.data.variables.product.api_url_pre }}/issues
+ {{ site.data.variables.product.api_url_pre }}/issues
```
To get only the [issues under one of your {{ site.data.variables.product.product_name }} organizations][get issues api], call `GET
@@ -383,13 +383,13 @@ To get only the [issues under one of your {{ site.data.variables.product.product
``` command-line
$ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
- https://{{ site.data.variables.product.api_url_pre }}/orgs/rails/issues
+ {{ site.data.variables.product.api_url_pre }}/orgs/rails/issues
```
We can also get [all the issues under a single repository][repo issues api]:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/repos/rails/rails/issues
+$ curl -i {{ site.data.variables.product.api_url_pre }}/repos/rails/rails/issues
```
### Pagination
@@ -399,12 +399,12 @@ making multiple API calls to get the data. Let's repeat that last call, this
time taking note of the response headers:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/repos/rails/rails/issues
+$ curl -i {{ site.data.variables.product.api_url_pre }}/repos/rails/rails/issues
> HTTP/1.1 200 OK
> ...
-> Link: <https://{{ site.data.variables.product.api_url_pre }}/repositories/8514/issues?page=2>; rel="next", <https://{{ site.data.variables.product.api_url_pre }}/repositories/8514/issues?page=30>; rel="last"
+> Link: <{{ site.data.variables.product.api_url_pre }}/repositories/8514/issues?page=2>; rel="next", <{{ site.data.variables.product.api_url_pre }}/repositories/8514/issues?page=30>; rel="last"
> ...
```
@@ -430,10 +430,10 @@ $ "title": "New logo", \
$ "body": "We should have one", \
$ "labels": ["design"] \
$ }' \
-$ https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues
+$ {{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues
> HTTP/1.1 201 Created
-> Location: https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues/17
+> Location: {{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues/17
> X-RateLimit-Limit: 5000
> {
@@ -452,7 +452,7 @@ $ https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sa
> "gravatar_id": "7e19cd5486b5d6dc1ef90e671ba52ae0",
> "avatar_url": "https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
> "id": 865,
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/users/pengwynn"
+> "url": "{{ site.data.variables.product.api_url_pre }}/users/pengwynn"
> },
> "closed_at": null,
> "updated_at": "2012-11-14T15:25:33Z",
@@ -463,13 +463,13 @@ $ https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sa
> {
> "color": "ededed",
> "name": "design",
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/labels/design"
+> "url": "{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/labels/design"
> }
> ],
> "id": 8356941,
> "assignee": null,
> "state": "open",
-> "url": "https://{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues/17"
+> "url": "{{ site.data.variables.product.api_url_pre }}/repos/pengwynn/api-sandbox/issues/17"
> }
```
@@ -484,7 +484,7 @@ requests][conditional-requests] and helps you do the right thing. Consider the
first call we made to get defunkt's profile:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ curl -i {{ site.data.variables.product.api_url_pre }}/users/defunkt
> HTTP/1.1 200 OK
> ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"
@@ -497,7 +497,7 @@ we can tell the API to give us the resource again, only if it has changed:
``` command-line
$ curl -i -H 'If-None-Match: "bfd85cbf23ac0b0c8a29bee02e7117c6"' \
-$ https://{{ site.data.variables.product.api_url_pre }}/users/defunkt
+$ {{ site.data.variables.product.api_url_pre }}/users/defunkt
> HTTP/1.1 304 Not Modified
```
diff --git a/content/guides/managing-deploy-keys.md b/content/guides/managing-deploy-keys.md
index 207108da09..5c830b6b62 100644
--- a/content/guides/managing-deploy-keys.md
+++ b/content/guides/managing-deploy-keys.md
@@ -89,16 +89,20 @@ A deploy key is an SSH key that is stored on your server and grants access to a
If your server needs to access multiple repositories, you can choose to create a new {{ site.data.variables.product.product_name }} account and attach an SSH key that will be used exclusively for automation. Since this {{ site.data.variables.product.product_name }} account won't be used by a human, it's called a machine user. You can then [add the machine user as collaborator][collaborator] or [add the machine user to a team][team] with access to the repositories it needs to manipulate. **NOTE**: Adding a machine user as a collaborator always grants read/write access. Adding a machine user to a team grants the permissions of the team.
+{% if page.version == 'dotcom' %}
+
{{#tip}}
-**Tip:** Our [terms of service](https://help.github.com/articles/github-terms-of-service) state:
+**Tip:** Our [terms of service][tos] state:
> *Accounts registered by "bots" or other automated methods are not permitted.*
-This means that you cannot automate the creation of accounts. But if you want to create a single machine user for automating tasks such as deploy scripts in your project or organization, that is totally cool.
+This means that you cannot automate the creation of accounts. But if you want to create a single machine user for automating tasks such as deploy scripts in your project or organization, that is totally cool.
{{/tip}}
+{% endif %}
+
#### Pros
* Anyone with access to the repository and server has the ability to deploy the project.
@@ -117,7 +121,7 @@ This means that you cannot automate the creation of accounts. But if you want to
[ssh-agent-forwarding]: /guides/using-ssh-agent-forwarding/
[generating-ssh-keys]: https://help.github.com/articles/generating-ssh-keys
-[tos]: https://help.github.com/articles/github-terms-of-service
+[tos]: https://help.github.com/articles/github-terms-of-service/
[git-automation]: https://help.github.com/articles/git-automation-with-oauth-tokens
[collaborator]: https://help.github.com/articles/how-do-i-add-a-collaborator
[team]: https://help.github.com/articles/adding-organization-members-to-a-team
diff --git a/content/guides/traversing-with-pagination.md b/content/guides/traversing-with-pagination.md
index 66a64ea1c2..ff4d11cf0b 100644
--- a/content/guides/traversing-with-pagination.md
+++ b/content/guides/traversing-with-pagination.md
@@ -32,7 +32,7 @@ of an API call. For example, let's make a curl request to the search API, to fin
out how many times Mozilla projects use the phrase `addClass`:
``` command-line
-$ curl -I "https://{{ site.data.variables.product.api_url_pre }}/search/code?q=addClass+user:mozilla"
+$ curl -I "{{ site.data.variables.product.api_url_pre }}/search/code?q=addClass+user:mozilla"
```
The `-I` parameter indicates that we only care about the headers, not the actual
@@ -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/integrations-directory/getting-listed.md b/content/integrations-directory/getting-listed.md
index 0ae07941a8..7a96f11057 100644
--- a/content/integrations-directory/getting-listed.md
+++ b/content/integrations-directory/getting-listed.md
@@ -22,12 +22,12 @@ All three are for GitHub-use only. If there's an urgent issue that needs your at
We'd like to have a minimum set of links to include in every integration listing, so that our users have all the information they need. These are:
+- Pricing - If your integration costs money or has differed priced tiers of service, please include this URL.
- Documentation - Please provide a URL with more information on how to use your integration.
- Terms of service - Please provide the Terms of Service URL for users using your integration.
- Privacy Policy - If different than Terms of Service, please include the URL here.
- Support - Please provide a URL or email address for users to contact you directly.
- Status - You should provide us a URL that will be updated when your application is down or experiencing problems. This could be a status site, a blog, a Twitter account, or more. This URL should be publicly accessible.
-- Pricing - If your integration costs money or has differed priced tiers of service, please include this URL.
- Installation - Provide the URL for direct installation for users. Note the OAuth requirement below.
### Provide updates to your listing
@@ -37,11 +37,9 @@ 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:
+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.
-* Build
-* Collaborate
-* Deploy
+If your integration supports both GitHub.com and GitHub Enterprise, please let us know.
## Technical requirements
diff --git a/content/libraries.md b/content/libraries.md
index a4d641e1e8..2958416746 100644
--- a/content/libraries.md
+++ b/content/libraries.md
@@ -134,7 +134,7 @@ covers the entire API.
* [Github Nette Extension][kdyby-github]
* [GitHub API Easy Access][milo-github-api]
* [GitHub bridge for Laravel][github-laravel]
-* [GitHub API v3 wrapper][github-api-v3-wrapper]
+* [PHP5.6|PHP7 Client & WebHook wrapper][flexyproject-githubapi]
[github-php-client]: https://github.com/tan-tan-kanarek/github-php-client
[php-github-api]: https://github.com/KnpLabs/php-github-api
@@ -144,7 +144,7 @@ covers the entire API.
[kdyby-github]: https://github.com/kdyby/github
[milo-github-api]: https://github.com/milo/github-api
[github-laravel]: https://github.com/GrahamCampbell/Laravel-GitHub
-[github-api-v3-wrapper]: https://github.com/Scion-Framework/GitHubAPI
+[flexyproject-githubapi]: https://github.com/FlexyProject/GitHubAPI
## Python
diff --git a/content/search/search-index.json b/content/search/search-index.json
index bfe42d8c8b..708851ff81 100644
--- a/content/search/search-index.json
+++ b/content/search/search-index.json
@@ -1,17 +1,26 @@
-[
- <% if @config[:audience] %>
- <% @preface = "/enterprise/#{@config[:audience]}" %>
- <% end %>
- <% @items.select { |item| !item.attributes[:hide_from_search] }.each do |item| %>
- <% next if item[:filename].nil? || !item[:filename].end_with?('.md') %>
- <% @path = item[:filename].split('/')[1..-1].join('/')[0..-4] %>
- <% @path.chomp!('/index') if @path.end_with?('/index') %>
- {
- "title": "<%= clean_for_json(item[:title]) %>",
- <%# Split off the directory name, join, then remove the '.md' extension %>
- "url": "<%= @preface %>/<%= @path %>/",
- "body": "<%= clean_for_json(item.compiled_content) %>"
- },
- <% end %>
- {}
-]
+<%
+ #build the JSON tree
+ if @config[:audience]
+ @preface = "/enterprise/#{@config[:audience]}"
+ end
+ @output = []
+ @items.select { |item| !item.attributes[:hide_from_search] }.each do |item|
+ next if item[:filename].nil? || !item[:filename].end_with?('.md')
+ @path = item[:filename].split('/')[1..-1].join('/')[0..-4]
+ @path.chomp!('/index') if @path.end_with?('/index')
+
+ @output.push({
+ :title => "#{clean_for_json(item[:title])}",
+ :url => "#{@preface}/#{@path}/",
+ :body => "#{clean_for_json(item.compiled_content)}"
+ })
+ end
+%>
+<%=
+ #output the generated tree
+ if ENV['RACK_ENV'] == "production"
+ JSON.generate(@output.sort{|a, b| a[:title] <=> b[:title]})
+ else
+ JSON.pretty_generate(@output.sort{|a, b| a[:title] <=> b[:title]})
+ end
+%>
diff --git a/content/v3.md b/content/v3.md
index 9c049a2a06..a387737d67 100644
--- a/content/v3.md
+++ b/content/v3.md
@@ -22,7 +22,7 @@ All API access is over HTTPS, and accessed from the `{{ site.data.variables.prod
sent and received as JSON.
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/octocat/orgs
+$ curl -i {{ site.data.variables.product.api_url_pre }}/users/octocat/orgs
> HTTP/1.1 200 OK
> Server: nginx
@@ -32,9 +32,11 @@ $ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/octocat/or
> 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
@@ -83,7 +85,7 @@ specified as a segment in the path can be passed as an HTTP query string
parameter:
``` command-line
-$ curl -i "https://{{ site.data.variables.product.api_url_pre }}/repos/vmg/redcarpet/issues?state=closed"
+$ curl -i "{{ site.data.variables.product.api_url_pre }}/repos/vmg/redcarpet/issues?state=closed"
```
In this example, the 'vmg' and 'redcarpet' values are provided for the `:owner`
@@ -94,7 +96,7 @@ For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL sh
with a Content-Type of 'application/json':
``` command-line
-$ curl -i -u username -d '{"scopes":["public_repo"]}' https://{{ site.data.variables.product.api_url_pre }}/authorizations
+$ curl -i -u username -d '{"scopes":["public_repo"]}' {{ site.data.variables.product.api_url_pre }}/authorizations
```
## Root Endpoint
@@ -102,7 +104,7 @@ $ curl -i -u username -d '{"scopes":["public_repo"]}' https://{{ site.data.varia
You can issue a `GET` request to the root endpoint to get all the endpoint categories that the API supports:
``` command-line
-$ curl https://{{ site.data.variables.product.api_url_pre }}
+$ curl {{ site.data.variables.product.api_url_pre }}
```
{% if page.version != 'dotcom' %}
@@ -210,19 +212,19 @@ of private repositories to unauthorized users.
### Basic Authentication
``` command-line
-$ curl -u "username" https://{{ site.data.variables.product.api_url_pre }}
+$ curl -u "username" {{ site.data.variables.product.api_url_pre }}
```
### OAuth2 Token (sent in a header)
``` command-line
-$ curl -H "Authorization: token OAUTH-TOKEN" https://{{ site.data.variables.product.api_url_pre }}
+$ curl -H "Authorization: token OAUTH-TOKEN" {{ site.data.variables.product.api_url_pre }}
```
### OAuth2 Token (sent as a parameter)
``` command-line
-$ curl https://{{ site.data.variables.product.api_url_pre }}/?access_token=OAUTH-TOKEN
+$ curl {{ site.data.variables.product.api_url_pre }}/?access_token=OAUTH-TOKEN
```
Read [more about OAuth2](/v3/oauth/). Note that OAuth2 tokens can be [acquired
@@ -232,19 +234,24 @@ are not websites.
### OAuth2 Key/Secret
``` command-line
-$ curl 'https://{{ site.data.variables.product.api_url_pre }}/users/whatever?client_id=xxxx&client_secret=yyyy'
+$ curl '{{ site.data.variables.product.api_url_pre }}/users/whatever?client_id=xxxx&client_secret=yyyy'
```
This should only be used in server to server scenarios. Don't leak your
-OAuth application's client secret to your users. Read [more about
-unauthenticated rate limiting](#increasing-the-unauthenticated-rate-limit-for-oauth-applications).
+OAuth application's client secret to your users.
+
+{% if page.version == 'dotcom' %}
+
+Read [more about unauthenticated rate limiting](#increasing-the-unauthenticated-rate-limit-for-oauth-applications).
+
+{% endif %}
### Failed login limit
Authenticating with invalid credentials will return `401 Unauthorized`:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }} -u foo:bar
+$ curl -i {{ site.data.variables.product.api_url_pre }} -u foo:bar
> HTTP/1.1 401 Unauthorized
> {
@@ -258,7 +265,7 @@ the API will temporarily reject all authentication attempts for that user
(including ones with valid credentials) with `403 Forbidden`:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }} -u valid_username:valid_password
+$ curl -i {{ site.data.variables.product.api_url_pre }} -u valid_username:valid_password
> HTTP/1.1 403 Forbidden
> {
@@ -300,7 +307,7 @@ Note that for technical reasons not all endpoints respect the `?per_page` parame
see [events](https://developer.github.com/v3/activity/events/) for example.
``` command-line
-$ curl 'https://{{ site.data.variables.product.api_url_pre }}/user/repos?page=2&per_page=100'
+$ curl '{{ site.data.variables.product.api_url_pre }}/user/repos?page=2&per_page=100'
```
Note that page numbering is 1-based and that omitting the `?page`
@@ -333,6 +340,8 @@ Name | Description
`first` |The link relation for the first page of results.
`prev` |The link relation for the immediate previous page of results.
+{% if page.version == 'dotcom' %}
+
## Rate Limiting
For requests using Basic Authentication or OAuth, you can make up to 5,000
@@ -345,7 +354,7 @@ You can check the returned HTTP headers of any API request to see your current
rate limit status:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }}/users/whatever
+$ curl -i {{ site.data.variables.product.api_url_pre }}/users/whatever
> HTTP/1.1 200 OK
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> Status: 200 OK
@@ -394,7 +403,7 @@ API hit.
If your OAuth application needs to make unauthenticated calls with a higher rate limit, you can pass your app's client ID and secret as part of the query string.
``` command-line
-$ curl -i 'https://{{ site.data.variables.product.api_url_pre }}/users/whatever?client_id=xxxx&client_secret=yyyy'
+$ curl -i '{{ site.data.variables.product.api_url_pre }}/users/whatever?client_id=xxxx&client_secret=yyyy'
> HTTP/1.1 200 OK
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> Status: 200 OK
@@ -416,8 +425,6 @@ If you're using conditional requests and still exceeding your rate
limit, please [contact us][support] to request a
higher rate limit for your OAuth application.
-{% if page.version == 'dotcom' %}
-
### Abuse Rate Limits
To protect the quality of service from GitHub, additional rate limits may apply to some actions.
@@ -462,7 +469,7 @@ User-Agent: Awesome-Octocat-App
If you provide an invalid `User-Agent` header, you will receive a `403 Forbidden` response:
``` command-line
-$ curl -iH 'User-Agent: ' https://{{ site.data.variables.product.api_url_pre }}/meta
+$ curl -iH 'User-Agent: ' {{ site.data.variables.product.api_url_pre }}/meta
> HTTP/1.0 403 Forbidden
> Connection: close
> Content-Type: text/html
@@ -477,42 +484,58 @@ $ curl -iH 'User-Agent: ' https://{{ site.data.variables.product.api_url_pre }}/
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 https://{{ site.data.variables.product.api_url_pre }}/user
+$ curl -i {{ site.data.variables.product.api_url_pre }}/user
> HTTP/1.1 200 OK
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> 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 https://{{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
+$ curl -i {{ site.data.variables.product.api_url_pre }}/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
> HTTP/1.1 304 Not Modified
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> 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 https://{{ site.data.variables.product.api_url_pre }}/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
+$ 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
> Cache-Control: private, max-age=60
> 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
@@ -527,22 +550,22 @@ Here's a sample request sent from a browser hitting
`http://example.com`:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }} -H "Origin: http://example.com"
+$ 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
```
This is what the CORS preflight request looks like:
``` command-line
-$ curl -i https://{{ site.data.variables.product.api_url_pre }} -H "Origin: http://example.com" -X OPTIONS
+$ curl -i {{ site.data.variables.product.api_url_pre }} -H "Origin: http://example.com" -X OPTIONS
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
```
@@ -561,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"}]
> ]
@@ -633,7 +658,7 @@ It is possible to supply a `Time-Zone` header which defines a timezone according
to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
``` command-line
-$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://{{ site.data.variables.product.api_url_pre }}/repos/github/linguist/contents/new_file.md
+$ curl -H "Time-Zone: Europe/Amsterdam" -X POST {{ site.data.variables.product.api_url_pre }}/repos/github/linguist/contents/new_file.md
```
This means that we generate a timestamp for the moment your API call is made in
diff --git a/content/v3/activity/events.md b/content/v3/activity/events.md
index 0f62b646df..5541291631 100644
--- a/content/v3/activity/events.md
+++ b/content/v3/activity/events.md
@@ -16,13 +16,13 @@ specifies how often (in seconds) you are allowed to poll. In times of high
server load, the time may increase. Please obey the header.
``` command-line
-$ curl -I https://{{ site.data.variables.product.api_url_pre }}/users/tater/events
+$ curl -I {{ site.data.variables.product.api_url_pre }}/users/tater/events
> HTTP/1.1 200 OK
> X-Poll-Interval: 60
> ETag: "a18c3bded88eb5dbb5c849a489412bf3"
# The quotes around the ETag value are important
-$ curl -I https://{{ site.data.variables.product.api_url_pre }}/users/tater/events \
+$ curl -I {{ site.data.variables.product.api_url_pre }}/users/tater/events \
$ -H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"'
> HTTP/1.1 304 Not Modified
> X-Poll-Interval: 60
diff --git a/content/v3/activity/events/types.md b/content/v3/activity/events/types.md
index a60b30294d..9504e2de89 100644
--- a/content/v3/activity/events/types.md
+++ b/content/v3/activity/events/types.md
@@ -83,7 +83,7 @@ Key | Type | Description
Represents a [deployment](/v3/repos/deployments/#list-deployments).
-Events of this type are not visible in timelines, they are only used to trigger hooks.
+Events of this type are not visible in timelines. These events are only used to trigger hooks.
### Events API payload
@@ -108,7 +108,7 @@ Key | Type | Description
Represents a [deployment status](/v3/repos/deployments/#list-deployment-statuses).
-Events of this type are not visible in timelines, they are only used to trigger hooks.
+Events of this type are not visible in timelines. These events are only used to trigger hooks.
### Events API payload
@@ -239,13 +239,19 @@ Key | Type | Description
## IssueCommentEvent
-Triggered when an [issue comment](/v3/issues/comments/) is created on an issue or pull request.
+{% 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. Currently, can only be "created".
+`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".{% 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.
@@ -259,14 +265,17 @@ Key | Type | Description
## IssuesEvent
-Triggered when an [issue](/v3/issues) is assigned, unassigned, labeled, unlabeled, opened, 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", "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".{% 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.
@@ -301,7 +310,7 @@ Key | Type | Description
Triggered when a user is added or removed from a team.
-Events of this type are not visible in timelines, they are only used to trigger organization webhooks.
+Events of this type are not visible in timelines. These events are only used to trigger hooks.
### Events API payload
@@ -326,7 +335,7 @@ Represents an attempted build of a GitHub Pages site, whether successful or not.
Triggered on push to a GitHub Pages enabled branch (`gh-pages` for project pages, `master` for user and organization pages).
-Events of this type are not visible in timelines, they are only used to trigger hooks.
+Events of this type are not visible in timelines. These events are only used to trigger hooks.
### Events API payload
@@ -358,14 +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, 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", "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".{% endif %}
`pull_request`|`object` | The [pull request](/v3/pulls) itself.
### Webhook event name
@@ -378,13 +390,19 @@ Key | Type | Description
## PullRequestReviewCommentEvent
-Triggered when a [comment is created on a portion of the unified diff](/v3/pulls/comments) of a pull request.
+{% 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. Currently, can only be "created".
+`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".{% 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.
@@ -453,16 +471,16 @@ Key | Type | Description
## RepositoryEvent
-Triggered when a repository is created.
+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, they are only used to trigger organization webhooks.
+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. Currently, can only be "created".
-`repository`|`object` | The [repository](/v3/repos/) that was created.
+`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
@@ -476,7 +494,7 @@ Key | Type | Description
Triggered when the status of a Git commit changes.
-Events of this type are not visible in timelines, they are only used to trigger hooks.
+Events of this type are not visible in timelines. These events are only used to trigger hooks.
### Events API payload
diff --git a/content/v3/activity/notifications.md b/content/v3/activity/notifications.md
index 909b0c57a4..b09ec649a7 100644
--- a/content/v3/activity/notifications.md
+++ b/content/v3/activity/notifications.md
@@ -37,13 +37,13 @@ of high server load, the time may increase. Please obey the header.
``` command-line
# Add authentication to your requests
-$ curl -I https://{{ site.data.variables.product.api_url_pre }}/notifications
+$ curl -I {{ site.data.variables.product.api_url_pre }}/notifications
HTTP/1.1 200 OK
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60
# Pass the Last-Modified header exactly
-$ curl -I https://{{ site.data.variables.product.api_url_pre }}/notifications
+$ curl -I {{ site.data.variables.product.api_url_pre }}/notifications
$ -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
> HTTP/1.1 304 Not Modified
> X-Poll-Interval: 60
@@ -92,7 +92,11 @@ Name | Type | Description
### Response
+{% if page.version == 'dotcom' or page.version > 2.5 %}
+<%= headers 200, :pagination => default_pagination_rels %>
+{% else %}
<%= headers 200 %>
+{% endif %}
<%= json(:thread) { |h| [h] } %>
## List your notifications in a repository
@@ -112,7 +116,11 @@ Name | Type | Description
### Response
+{% if page.version == 'dotcom' or page.version > 2.5 %}
+<%= headers 200, :pagination => default_pagination_rels %>
+{% else %}
<%= headers 200 %>
+{% endif %}
<%= json(:thread) { |h| [h] } %>
## Mark as read
diff --git a/content/v3/auth.md b/content/v3/auth.md
index 0bbb5e6bde..ca387bfaa0 100644
--- a/content/v3/auth.md
+++ b/content/v3/auth.md
@@ -33,7 +33,7 @@ would authenticate you if you replace `` with your {{ site.data.variab
(cURL will prompt you to enter the password.)
``` command-line
-$ curl -u username https://{{ site.data.variables.product.api_url_pre }}/user
+$ curl -u username {{ site.data.variables.product.api_url_pre }}/user
```
### Via OAuth Tokens
@@ -42,7 +42,7 @@ Alternatively, you can use [personal access
tokens][personal-access-tokens] or OAuth tokens instead of your password.
``` command-line
-$ curl -u username:token https://{{ site.data.variables.product.api_url_pre }}/user
+$ curl -u username:token {{ site.data.variables.product.api_url_pre }}/user
```
This approach is useful if your tools only support Basic Authentication but you
diff --git a/content/v3/enterprise.md b/content/v3/enterprise.md
index db63d0df26..2bcd997e44 100644
--- a/content/v3/enterprise.md
+++ b/content/v3/enterprise.md
@@ -33,7 +33,7 @@ Every Enterprise API endpoint is only accessible to GitHub Enterprise site admin
[basic authentication]: /v3/#basic-authentication
[Management Console]: /v3/enterprise/management_console/
[User Administration]: /v3/users/administration/
-[Management Console password]: https://help.github.com/enterprise/2.0/admin/articles/accessing-the-management-console/
+[Management Console password]: https://help.github.com/enterprise/admin/articles/accessing-the-management-console/
## Releases
diff --git a/content/v3/enterprise/orgs.md b/content/v3/enterprise/orgs.md
index 1decb5336c..cc6013e48e 100644
--- a/content/v3/enterprise/orgs.md
+++ b/content/v3/enterprise/orgs.md
@@ -6,7 +6,7 @@ title: Organization Administration
{:toc}
-The Organization Administration API allows you to create organizations on a GitHub Enterprise appliance. *It is only available to [authenticated](/v3/#authentication) site administrators.* Normal users will receive a `403` response if they try to access it.
+The Organization Administration API allows you to create organizations on a GitHub Enterprise appliance. *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:
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/gists.md b/content/v3/gists.md
index 127940e465..0f73102306 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
@@ -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
diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md
index 99a243f8f7..69a0da52fe 100644
--- a/content/v3/git/commits.md
+++ b/content/v3/git/commits.md
@@ -59,3 +59,59 @@ Name | Type | Description
<%= headers 201, :Location => get_resource(:new_commit)['url'] %>
<%= json :new_commit %>
+
+{% if page.version == 'dotcom' %}
+
+## Commit signature verification
+
+{{#tip}}
+
+Commit response objects including signature verification data are currently available for developers to preview.
+During the preview period, the object formats may change without advance notice.
+Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full details.
+
+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
+
+{{/tip}}
+
+ GET /repos/:owner/:repo/git/commits/:sha
+
+### Response
+
+<%= 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 below.
+`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.
+`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.
+`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/refs.md b/content/v3/git/refs.md
index 4e664f9628..ef4a444d92 100644
--- a/content/v3/git/refs.md
+++ b/content/v3/git/refs.md
@@ -14,11 +14,26 @@ The `ref` in the URL must be formatted as `heads/branch`, not just `branch`. For
GET /repos/:owner/:repo/git/refs/heads/skunkworkz/featureA
-### Response
-
<%= headers 200 %>
<%= json :ref %>
+If the `ref` doesn't exist in the repository, but existing refs start with `ref`
+they will be returned as an array. For example, a call to get the data for a
+branch named `feature`, which doesn't exist, would return head refs
+including `featureA` and `featureB` which do.
+
+ GET /repos/:owner/:repo/git/refs/heads/feature
+
+<%= headers 200 %>
+<%= json :refs_matching %>
+
+If the `ref` doesn't match an existing ref or any prefixes a 404 will be returned.
+
+ GET /repos/:owner/:repo/git/refs/heads/feature-branch-that-no-longer-exists
+
+<%= headers 404 %>
+<%= json :refs_not_found %>
+
## Get all References
GET /repos/:owner/:repo/git/refs
diff --git a/content/v3/git/tags.md b/content/v3/git/tags.md
index 1ae156c8a3..b0605da270 100644
--- a/content/v3/git/tags.md
+++ b/content/v3/git/tags.md
@@ -63,3 +63,59 @@ Name | Type | Description
<%= headers 201, :Location => get_resource(:gittag)['url'] %>
<%= json :gittag %>
+
+{% if page.version == 'dotcom' %}
+
+## Tag signature verification
+
+{{#tip}}
+
+Tag response objects including signature verification data are currently available for developers to preview.
+During the preview period, the object formats may change without advance notice.
+Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full details.
+
+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
+
+{{/tip}}
+
+ GET /repos/:owner/:repo/git/tags/:sha
+
+### Response
+
+<%= 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 below.
+`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/issues.md b/content/v3/issues.md
index 30feabeb67..59e7f99a29 100644
--- a/content/v3/issues.md
+++ b/content/v3/issues.md
@@ -13,17 +13,23 @@ read more about the use of media types in the API [here](/v3/media/).
<%= fetch_content(:prs_as_issues) %>
-List all issues across all the authenticated user's visible repositories
+List all issues **assigned** to the authenticated user across all visible repositories
including owned repositories, member repositories, and organization
repositories:
GET /issues
-List all issues across owned and member repositories for the authenticated user:
+{{#tip}}
+
+You can use the `filter` query parameter to fetch issues that are not necessarily assigned to you. See the table below for more information.
+
+{{/tip}}
+
+List all issues across owned and member repositories assigned to the authenticated user:
GET /user/issues
-List all issues for a given organization for the authenticated user:
+List all issues for a given organization assigned to the authenticated user:
GET /orgs/:org/issues
@@ -43,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) %>
@@ -68,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) %>
@@ -79,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.
@@ -91,9 +159,10 @@ 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._
#### Example
@@ -101,8 +170,9 @@ Name | Type | Description
:title => "Found a bug",
:body => "I'm having a problem with this.",
:assignee => "octocat",
+ :assignees => [get_resource(:user)],
:milestone => 1,
- :labels => %w(Label1 Label2)
+ :labels => %w(bug)
%>
### Response
@@ -122,11 +192,11 @@ 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._
#### Example
@@ -134,9 +204,10 @@ Name | Type | Description
:title => "Found a bug",
:body => "I'm having a problem with this.",
:assignee => "octocat",
+ :assignees => [get_resource(:user)],
:milestone => 1,
:state => "open",
- :labels => %w(Label1 Label2)
+ :labels => %w(bug)
%>
### Response
@@ -144,8 +215,10 @@ Name | Type | Description
<%= headers 200 %>
<%= json :full_issue %>
+{% if page.version == 'dotcom' or page.version >= 2.6 %}
## Lock an issue
+{% if page.version == 2.6 %}
{{#tip}}
@@ -159,6 +232,7 @@ Name | Type | Description
application/vnd.github.the-key-preview+json
{{/tip}}
+{% endif %}
Users with push access can lock an issue's conversation.
@@ -172,6 +246,7 @@ Users with push access can lock an issue's conversation.
## Unlock an issue
+{% if page.version == 2.6 %}
{{#tip}}
@@ -185,6 +260,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.
@@ -194,6 +270,8 @@ Users with push access can unlock an issue's conversation.
<%= headers 204 %>
+{% endif %}
+
## Custom media types
These are the supported media types for issues. You can read more about the
diff --git a/content/v3/issues/assignees.md b/content/v3/issues/assignees.md
index 8a48cdb867..4d0c1a59a0 100644
--- a/content/v3/issues/assignees.md
+++ b/content/v3/issues/assignees.md
@@ -35,3 +35,33 @@ 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
+
+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 %>
+
+## Remove assignees from an Issue
+
+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 %>
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/issues/events.md b/content/v3/issues/events.md
index c6024c827b..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,11 +20,14 @@ determine who should be notified of comments.
The API URL for fetching the event.
actor
- Always the User that generated the event.
+ The User object that generated the event.
commit_id
The String SHA of a commit that referenced this Issue
+ commit_url
+ The GitHub API link to a commit that referenced this Issue
+
event
Identifies the actual type of Event that occurred.
@@ -32,19 +35,24 @@ 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.
+ {% if page.version == 'dotcom' or page.version > 2.5 %}
+ assigner
+ The User object that performed the assignment (or unassignment) for this Issue. Only provided for 'assigned' and 'unassigned' events.
+ {% 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/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" %>
diff --git a/content/v3/issues/timeline.md b/content/v3/issues/timeline.md
new file mode 100644
index 0000000000..c1ba039e0e
--- /dev/null
+++ b/content/v3/issues/timeline.md
@@ -0,0 +1,149 @@
+---
+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}
+
+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.
+
+ - 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 assignee.
+
+ - 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 assignee 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/content/v3/media.md b/content/v3/media.md
index 6c4b6b0b87..539acc407c 100644
--- a/content/v3/media.md
+++ b/content/v3/media.md
@@ -45,16 +45,16 @@ You can check the current version through every response's headers. Look
for the `X-GitHub-Media-Type` header:
``` command-line
-$ curl https://{{ site.data.variables.product.api_url_pre }}/users/technoweenie -I
+$ curl {{ site.data.variables.product.api_url_pre }}/users/technoweenie -I
> HTTP/1.1 200 OK
> X-GitHub-Media-Type: github.v3
-$ curl https://{{ site.data.variables.product.api_url_pre }}/users/technoweenie -I \
+$ curl {{ site.data.variables.product.api_url_pre }}/users/technoweenie -I \
$ -H "Accept: application/vnd.github.full+json"
> HTTP/1.1 200 OK
> X-GitHub-Media-Type: github.v3; param=full; format=json
-$ curl https://{{ site.data.variables.product.api_url_pre }}/users/technoweenie -I \
+$ curl {{ site.data.variables.product.api_url_pre }}/users/technoweenie -I \
$ -H "Accept: application/vnd.github.v3.full+json"
> HTTP/1.1 200 OK
> X-GitHub-Media-Type: github.v3; param=full; format=json
@@ -125,6 +125,10 @@ The Commit, Commit Comparison, and Pull Request resources support
application/vnd.github.VERSION.patch
+### sha
+
+ application/vnd.github.VERSION.sha
+
## Repository contents
### Raw
diff --git a/content/v3/meta.md b/content/v3/meta.md
index 92f374a6da..6ba388351d 100644
--- a/content/v3/meta.md
+++ b/content/v3/meta.md
@@ -30,3 +30,4 @@ Name | Type | Description
`hooks`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the addresses that incoming service hooks will originate from on GitHub.com. Subscribe to the [API Changes blog](https://developer.github.com/changes/) or follow [@GitHubAPI](https://twitter.com/GitHubAPI) on Twitter to get updated when this list changes.
`git`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the Git servers for GitHub.com.
`pages`|`array` of `strings` | An Array of IP addresses in CIDR format specifying the A records for [GitHub Pages](https://pages.github.com/).
+`importer`|`array` of `strings` | An Array of IP addresses specifying the addresses that source imports will originate from on GitHub.com.
diff --git a/content/v3/migration.md b/content/v3/migration.md
new file mode 100644
index 0000000000..5291cd5928
--- /dev/null
+++ b/content/v3/migration.md
@@ -0,0 +1,29 @@
+---
+title: Migration
+---
+
+# Migration
+
+These APIs help you move projects to or from {{ site.data.variables.product.product_name }}.
+
+{% if page.version == 'dotcom' %}
+
+## [Enterprise Migrations][migrations]
+
+The [Enterprise Migrations API][migrations] lets you move a repository from GitHub to GitHub Enterprise.
+
+## [Source Imports][source_imports]
+
+The [Source Imports API][source_imports] lets you import a source repository to
+{{ site.data.variables.product.product_name }}.
+
+{% else %}
+
+The migration APIs are only available on github.com. To learn more about migration,
+read the [API documentation on github.com](https://developer.github.com/v3/migration/)
+or check out the [Enterprise Migration Guide](https://help.github.com/enterprise/admin/guides/migrations/).
+
+{% endif %}
+
+[migrations]: /v3/migration/migrations/
+[source_imports]: /v3/migration/source_imports/
diff --git a/content/v3/orgs/migrations.md b/content/v3/migration/migrations.md
similarity index 93%
rename from content/v3/orgs/migrations.md
rename to content/v3/migration/migrations.md
index c770feb331..be76e44e2e 100644
--- a/content/v3/orgs/migrations.md
+++ b/content/v3/migration/migrations.md
@@ -6,6 +6,8 @@ title: Migrations
{:toc}
+The Migrations API *is only available to [authenticated](https://developer.github.com/v3/#authentication) organization [owners](https://help.github.com/articles/permission-levels-for-an-organization/)*.
+
{% if page.version != 'dotcom' %}
{{#warning}}
diff --git a/content/v3/migration/source_imports.md b/content/v3/migration/source_imports.md
new file mode 100644
index 0000000000..044cc0079e
--- /dev/null
+++ b/content/v3/migration/source_imports.md
@@ -0,0 +1,321 @@
+---
+title: Source Imports | GitHub API
+---
+
+# Source Imports
+
+{:toc}
+
+{% if page.version != 'dotcom' %}
+
+{{#warning}}
+
+This API is not currently available on GitHub Enterprise.
+
+{{/warning}}
+
+{% endif %}
+
+{{#tip}}
+
+ The source import APIs are currently in public preview. During this period, the APIs may change in a backwards-incompatible way. To access the API during the preview period, you must provide a custom [media type](/v3/media) in the `Accept` header:
+
+ application/vnd.github.barred-rock-preview
+
+{{/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://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:
+
+```
++---------+ +--------+ +---------------------+
+| Tooling | | GitHub | | Original Repository |
++---------+ +--------+ +---------------------+
+ | | |
+ | Start import | |
+ |----------------------------->| |
+ | | |
+ | | Download source data |
+ | |--------------------------------------------->|
+ | | Begin streaming data |
+ | |<---------------------------------------------|
+ | | |
+ | Get import progress | |
+ |----------------------------->| |
+ | "status": "importing" | |
+ |<-----------------------------| |
+ | | |
+ | Get commit authors | |
+ |----------------------------->| |
+ | | |
+ | Map a commit author | |
+ |----------------------------->| |
+ | | |
+ | | |
+ | | Finish streaming data |
+ | |<---------------------------------------------|
+ | | |
+ | | Rewrite commits with mapped authors |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | | Update repository on GitHub |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | Map a commit author | |
+ |----------------------------->| |
+ | | Rewrite commits with mapped authors |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | | Update repository on GitHub |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | Get large files | |
+ |----------------------------->| |
+ | | |
+ | opt_in to Git LFS | |
+ |----------------------------->| |
+ | | Rewrite commits for large files |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | | Update repository on GitHub |
+ | |------+ |
+ | | | |
+ | |<-----+ |
+ | | |
+ | Get import progress | |
+ |----------------------------->| |
+ | "status": "complete" | |
+ |<-----------------------------| |
+ | | |
+ | | |
+```
+
+## Start an import
+
+Start a source import to a GitHub repository using GitHub Importer.
+
+ PUT /repos/:owner/:repo/import
+
+### Parameters
+
+Name | Type | Description
+-----|------|--------------
+`vcs_url`|`url`|**Required** The URL of the originating repository.
+`vcs`|`string`|The originating VCS type. Can be one of `subversion`, `git`, `mercurial`, or `tfvc`. Please be aware that without this parameter, the import job will take additional time to detect the VCS type before beginning the import. This detection step will be reflected in the response.
+`vcs_username`|`string`|If authentication is required, the username to provide to `vcs_url`.
+`vcs_password`|`string`|If authentication is required, the password to provide to `vcs_url`.
+`tfvc_project`|`string`|For a tfvc import, the name of the project that is being imported.
+
+#### Example
+
+<%= json \
+ :vcs => "subversion",
+ :vcs_url => "http://svn.mycompany.com/svn/myproject",
+ :vcs_username => "octocat",
+ :vcs_password => "secret"
+%>
+
+### Response
+
+<%= headers 201, :Location => "https://api.github.com/repos/spraints/socm/import" %>
+<%= json :source_import %>
+
+## Get import progress
+
+View the progress of an import.
+
+ GET /repos/:owner/:repo/import
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_complete %>
+
+### Import `status`
+
+This section includes details about the possible values of the `status` field of the Import Progress response.
+
+An import that does not have errors will progress through these steps:
+
+* `detecting` - the "detection" step of the import is in progress because the request did not include a `vcs` parameter. The import is identifying the type of source control present at the URL.
+* `importing` - the "raw" step of the import is in progress. This is where commit data is fetched from the original repository. The import progress response will include `commit_count` (the total number of raw commits that will be imported) and `percent` (0 - 100, the current progress through the import).
+* `mapping` - the "rewrite" step of the import is in progress. This is where SVN branches are converted to Git branches, and where author updates are applied. The import progress response does not include progress information.
+* `pushing` - the "push" step of the import is in progress. This is where the importer updates the repository on GitHub. The import progress response will include `push_percent`, which is the percent value reported by `git push` when it is "Writing objects".
+* `complete` - the import is complete, and the repository is ready on GitHub.
+
+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. 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. 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
+
+This section includes details about Git LFS related fields that may be present in the Import Progress response.
+
+* `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 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
+
+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
+
+### Parameters for updating authentication
+
+Name | Type | Description
+-----|------|--------------
+`vcs_username`|`string`|The username to provide to the originating repository.
+`vcs_password`|`string`|The password to provide to the originating repository.
+
+### Example
+
+<%= json \
+ :vcs_username => "octocat",
+ :vcs_password => "secret"
+%>
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_update_auth %>
+
+### Parameters for updating project choice
+
+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": "project1",
+ "human_name": "project1 (tfs)"
+%>
+
+### Response
+
+<%= 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 `.
+
+This API method and the "Map a commit author" method allow you to provide correct Git author information.
+
+ GET /repos/:owner/:repo/import/authors
+
+### Parameters
+
+Name | Type | Description
+-----|------|------------
+`since`|`string`|Only authors found after this id are returned. Provide the highest author ID you've seen so far. New authors may be added to the list at any point while the importer is performing the `raw` step.
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_authors %>
+
+## Map a commit author
+
+Update an author's identity for the import. Your application can continue updating authors any time before you push new commits to the repository.
+
+ PATCH /repos/:owner/:repo/import/authors/:author_id
+
+### Parameters
+
+Name | Type | Description
+-----|------|--------------
+`email`|`string`|The new Git author email.
+`name`|`string`|The new Git author name.
+
+### Example
+
+<%= json \
+ :email => "hubot@github.com",
+ :name => "Hubot the Robot"
+%>
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_author %>
+
+## Set Git LFS preference
+
+You can import repositories from Subversion, Mercurial, and TFS that include files larger than 100MB. This ability is powered by [Git LFS](https://git-lfs.github.com). You can learn more about our LFS feature and working with large files [on our help site](https://help.github.com/articles/versioning-large-files/).
+
+ PATCH /:owner/:name/import/lfs
+
+### Parameters
+
+Name | Type | Description
+-----|------|--------------
+`use_lfs`|`string`|**Required** Can be one of `opt_in` (large files will be stored using Git LFS) or `opt_out` (large files will be removed during the import).
+
+### Example
+
+<%= json \
+ :use_lfs => "opt_in"
+%>
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_complete %>
+
+## Get large files
+
+List files larger than 100MB found during the import
+
+ GET /:owner/:name/import/large_files
+
+### Response
+
+<%= headers 200 %>
+<%= json :source_import_large_files %>
+
+## Cancel an import
+
+Stop an import for a repository.
+
+ DELETE /repos/:owner/:repo/import
+
+### Response
+
+<%= headers 204 %>
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/oauth.md b/content/v3/oauth.md
index 8e3135820d..1555d954d7 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,9 +34,10 @@ 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 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.
+`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`|`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
@@ -56,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
@@ -78,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
@@ -182,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.
@@ -198,13 +212,16 @@ Name | Description
`read:public_key`| List and view details for public keys.
`write:public_key`| Create, list, and view details for public keys.
`admin:public_key`| Fully manage public keys.
+{% if page.version == 'dotcom' %}`read:gpg_key`| List and view details for GPG keys.{% endif %}
+{% if page.version == 'dotcom' %}`write:gpg_key`| Create, list, and view details for GPG keys.{% endif %}
+{% 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
@@ -315,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
diff --git a/content/v3/oauth_authorizations.md b/content/v3/oauth_authorizations.md
index 1e415e2908..785a6f0e9a 100644
--- a/content/v3/oauth_authorizations.md
+++ b/content/v3/oauth_authorizations.md
@@ -2,14 +2,25 @@
title: Authorizations
---
-# OAuth Authorizations API
+{% if page.version == 'dotcom' or page.version > 2.6 %}
-{:toc}
+{{#tip}}
-You can use this API to manage your OAuth applications. You can only access this API via [Basic Authentication](/v3/auth#basic-authentication) using your username and password, not tokens.
+
-Make sure you understand how to [work with two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if you or your users have two-factor authentication enabled.
+ APIs for managing OAuth grants 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-04-21-oauth-authorizations-grants-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.damage-preview
+{{/tip}}
+
+{% endif %}
+
+
Deprecation Notice
@@ -51,6 +62,48 @@ Make sure you understand how to [work with two-factor authentication](/v3/auth/#
+# OAuth Authorizations API
+
+{:toc}
+
+You can use this API to manage the access OAuth applications have to your account. You can only access this API via [Basic Authentication](/v3/auth#basic-authentication) using your username and password, not tokens.
+
+Make sure you understand how to [work with two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if you or your users have two-factor authentication enabled.
+
+{% if page.version == 'dotcom' or page.version > 2.6 %}
+
+## List your grants
+
+You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the [list your authorizations](/v3/oauth_authorizations/#list-your-authorizations) API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on [the application authorizations settings screen within GitHub][authorized-application-listing]. The `scopes` returned are the union of scopes authorized for the application. For example, if an application has one token with `repo` scope and another token with `user` scope, the grant will return `["repo", "user"]`.
+
+ GET /applications/grants
+
+### Response
+
+<%= headers 200, :pagination => default_pagination_rels %>
+<%= json(:oauth_authorization) { |h| [h] } %>
+
+## Get a single grant
+
+ GET /applications/grants/:id
+
+### Response
+
+<%= headers 200 %>
+<%= json(:oauth_authorization) %>
+
+## Delete a grant
+
+Deleting an OAuth application's grant will also delete all OAuth tokens associated with the application for your user. Once deleted, the application has no access to your account and is no longer listed on [the application authorizations settings screen within GitHub][authorized-application-listing].
+
+ DELETE /applications/grants/:id
+
+### Response
+
+<%= headers 204 %>
+
+{% endif %}
+
## List your authorizations
GET /authorizations
@@ -267,4 +320,5 @@ links that might be of help:
[app-listing]: https://github.com/settings/developers
[tokens-listing]: https://github.com/settings/tokens
+[authorized-application-listing]: https://github.com/settings/applications#authorized
[basics auth guide]: /guides/basics-of-authentication/
diff --git a/content/v3/orgs.md b/content/v3/orgs.md
index 2a44ac3291..aa7419a031 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.
@@ -57,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
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/orgs/members.md b/content/v3/orgs/members.md
index a1f4f61af4..6f1b79abe4 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 %}
+{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %}
{{#tip}}
@@ -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.
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/orgs/teams.md b/content/v3/orgs/teams.md
index 65de0f30d3..07a233bea9 100644
--- a/content/v3/orgs/teams.md
+++ b/content/v3/orgs/teams.md
@@ -51,8 +51,27 @@ Name | Type | Description
`name`|`string` | **Required**. The name of the team.
`description`|`string` | The description of the team.
`repo_names`|`array` of `strings` | The full name (e.g., "organization-name/repository-name") of repositories to add the team to.
-`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`
**This parameter requires a custom media type to be specified. Please see more in the alert below.**
+`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.3 and page.version < 2.6 %}
+
+{{#tip}}
+
+We're currently offering a preview period allowing applications to opt in to the Organization Permissions API. Please see the [blog post](/changes/2015-06-24-api-enhancements-for-working-with-organization-permissions/) 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.ironman-preview+json
+```
+
+**Warning:** If you specify the `privacy` attribute on an organization that hasn't had [improved organization permissions](https://github.com/blog/2020-improved-organization-permissions) enabled yet, you will get a `422` error response.
+
+{{/tip}}
+
+{% endif %}
+
#### Example
<%= json \
@@ -107,9 +126,10 @@ Name | Type | Description
-----|------|--------------
`name`|`string` | **Required**. The name of the team.
`description`|`string` | The description of the team.
-`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 == 2.4 %}**This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+`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.3 and page.version < 2.6 %}
{{#tip}}
@@ -125,6 +145,8 @@ application/vnd.github.ironman-preview+json
{{/tip}}
+{% endif %}
+
#### Example
<%= json \
@@ -500,7 +522,7 @@ Name | Type | Description
{% endif %}
-{% if page.version != 'dotcom' and page.version == 2.4 %}
+{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %}
{{#tip}}
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
index bc7bd0eec0..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
@@ -187,9 +191,26 @@ Note: The response includes a maximum of 250 commits. If you are working with a
Name | Type | Description
-----|------|-------------
+{% if page.version == 'dotcom' or page.version >= 2.6 %}`commit_title`|`string`| Title for the automatic commit message.{% endif %}
`commit_message`|`string`| Extra detail to append to automatic commit message.
`sha`|`string`| SHA that pull request head must match to allow merge
+{% if page.version == 'dotcom' or page.version >= 2.6 %}`squash`|`boolean`| Commit a single commit to the head branch.{% endif %}
+
+{% if page.version == 'dotcom' or page.version >= 2.6 %}
+
+{{#tip}}
+
+The `commit_title` and `squash` parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the [blog post](/changes/2016-04-01-squash-api-preview) 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.polaris-preview+json
+```
+
+{{/tip}}
+
+{% endif %}
### Response if merge was successful
@@ -216,7 +237,7 @@ Name | Type | Description
:documentation_url => "https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-button"
%>
-### Labels, assignees, and milestones
+## Labels, assignees, and milestones
Every pull request is an issue, but not every issue is a pull request. For this reason, "shared" actions for both features, like manipulating assignees, labels and milestones, are provided within [the Issues API](/v3/issues).
diff --git a/content/v3/pulls/comments.md b/content/v3/pulls/comments.md
index e2362319b6..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
@@ -66,6 +129,13 @@ Name | Type | Description
`path`|`string` | **Required**. The relative path of the file to comment on.
`position`|`integer` | **Required**. The line index in the diff to comment on.
+{{#tip}}
+
+When passing the `commit_id`, use the SHA of the latest commit in the pull request or your comment may appear as "outdated" if the specified `position` has been modified in a subsequent commit.
+
+To comment on a specific line in a file, you will need to first determine the position in the diff. GitHub offers a `application/vnd.github.v3.diff` media type which you can use in a preceding request to view the pull request's diff. The diff needs to be [interpreted](https://en.wikipedia.org/wiki/Diff_utility#Unified_format) to translate from the *line in the file* to a *position in the diff*. The `position` value is the number of lines down from the first "@@" hunk header in the file you would like to comment on. The line just below the "@@" line is position 1, the next line is position 2, and so on. The position in the file's diff continues to increase through lines of whitespace and additional hunks until a new file is reached.
+
+{{/tip}}
#### Example
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/reactions.md b/content/v3/reactions.md
new file mode 100644
index 0000000000..d8effc8a38
--- /dev/null
+++ b/content/v3/reactions.md
@@ -0,0 +1,208 @@
+---
+title: Reactions
+---
+
+{% if page.version == 'dotcom' or page.version >= 2.7 %}
+
+# 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.md b/content/v3/repos.md
index 10562eb1eb..2e8b726228 100644
--- a/content/v3/repos.md
+++ b/content/v3/repos.md
@@ -250,118 +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) %>
-
-## 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"]
- }
- }
-%>
-
## 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..e620efd95c
--- /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 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:
+
+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/content/v3/repos/collaborators.md b/content/v3/repos/collaborators.md
index 8686fcc56c..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.4 %}
-
### Alternative response with extra repository information
{{#tip}}
@@ -65,12 +65,23 @@ application/vnd.github.ironman-preview+json
Name | Type | Description
-----|------|--------------
-`permission`|`string` | The permission to grant the collaborator. **Only valid on organization-owned repositories.** Can be one of:
* `pull` - can pull, but not push to or administer this repository.
* `push` - can pull and push, but not administer this repository.
* `admin` - can pull, push and administer this repository.
Default: `pull`
+`permission`|`string` | The permission to grant the collaborator. **Only valid on organization-owned repositories.** Can be one of:
* `pull` - can pull, but not push to or administer this repository.
* `push` - can pull and push, but not administer this repository.
* `admin` - can pull, push and administer this repository.
Default: `push`
<%= 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.4 %}
+{% if page.version != 'dotcom' and page.version > 2.3 and page.version < 2.6 %}
{{#tip}}
@@ -98,6 +109,11 @@ application/vnd.github.ironman-preview+json
<%= headers 204 %>
+### Response with preview media type
+
+<%= headers 201 %>
+<%= json(:repository_invitation) %>
+
## Remove user as a collaborator
DELETE /repos/:owner/:repo/collaborators/:username
diff --git a/content/v3/repos/comments.md b/content/v3/repos/comments.md
index 66e29b1f6a..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
@@ -46,7 +88,7 @@ Name | Type | Description
#### Example
<%= json \
- :body => 'Nice change',
+ :body => 'Great stuff',
:path => 'file1.txt',
:position => 4,
:line => nil
@@ -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
@@ -86,7 +149,7 @@ Name | Type | Description
### Response
<%= headers 200 %>
-<%= json :commit_comment %>
+<%= json(:commit_comment) { |h| h.merge('body' => 'Nice change') } %>
## Delete a commit comment
diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md
index 128c3997f7..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
@@ -43,6 +41,27 @@ patch formats.
<%= headers 200 %>
<%= json(:full_commit) %>
+## Get the SHA-1 of a commit reference
+
+Users with read access can get the SHA-1 of a commit reference:
+
+ GET /repos/:owner/:repo/commits/:ref
+
+To access the API you must provide a custom [media type](/v3/media) in the `Accept` header:
+
+ application/vnd.github.VERSION.sha
+
+To check if a remote reference's SHA-1 is the same as your local reference's SHA-1, make a `GET` request and provide the current SHA-1 for the local reference as the ETag.
+
+### Response
+
+The SHA-1 of the commit reference.
+
+<%= headers 200 %>
+
+814412cfbd631109df337e16c807207e78c0d24e
+
+
## Compare two commits
GET /repos/:owner/:repo/compare/:base...:head
@@ -64,3 +83,59 @@ Pass the appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-
The response will include a comparison of up to 250 commits. If you are working with a larger commit range, you can use the [Commit List API](/v3/repos/commits/#list-commits-on-a-repository) to enumerate all commits in the range.
For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long to generate. You can typically resolve this error by using a smaller commit range.
+
+{% if page.version == 'dotcom' %}
+
+## Commit signature verification
+
+{{#tip}}
+
+Commit response objects including signature verification data are currently available for developers to preview.
+During the preview period, the object formats may change without advance notice.
+Please see the [blog post](/changes/2016-04-04-git-signing-api-preview) for full details.
+
+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
+
+{{/tip}}
+
+ GET /repos/:owner/:repo/commits/:sha
+
+### Response
+
+<%= 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 below.
+`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/repos/deployments.md b/content/v3/repos/deployments.md
index ebb1b6d45f..34e2574621 100644
--- a/content/v3/repos/deployments.md
+++ b/content/v3/repos/deployments.md
@@ -6,7 +6,7 @@ title: Deployments
{:toc}
-Deployments are a request for a specific ref(branch,sha,tag) to be deployed.
+Deployments are a request for a specific ref (branch, SHA, tag) to be deployed.
GitHub then dispatches deployment events that external services can listen for
and act on. This enables developers and organizations to build loosely-coupled
tooling around deployments, without having to worry about implementation
@@ -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
@@ -78,8 +78,8 @@ Simple filtering of deployments is available via query parameters:
Name | Type | Description
-----|------|--------------
-`sha`|`string` | The short or long sha that was recorded at creation time. Default: `none`
-`ref`|`string` | The name of the ref. This can be a branch, tag, or sha. Default: `none`
+`sha`|`string` | The SHA that was recorded at creation time. Default: `none`
+`ref`|`string` | The name of the ref. This can be a branch, tag, or SHA. Default: `none`
`task`|`string` | The name of the task for the deployment. e.g. `deploy` or `deploy:migrations`. Default: `none`
`environment`|`string` | The name of the environment that was deployed to. e.g. `staging` or `production`. Default: `none`
@@ -92,7 +92,7 @@ Name | Type | Description
Deployments offer a few configurable parameters with sane defaults.
-The `ref` parameter can be any named branch, tag, or sha. At GitHub we often
+The `ref` parameter can be any named branch, tag, or SHA. At GitHub we often
deploy branches and verify them before we merge a pull request.
The `environment` parameter allows deployments to be issued to different
@@ -131,13 +131,30 @@ Users with `repo` or `repo_deployment` scopes can create a deployment for a give
Name | Type | Description
-----|------|--------------
-`ref`|`string`| **Required**. The ref to deploy. This can be a branch, tag, or sha.
+`ref`|`string`| **Required**. The ref to deploy. This can be a branch, tag, or SHA.
`task`|`string`| Optional parameter to specify a task to execute, e.g. `deploy` or `deploy:migrations`. Default: `deploy`
`auto_merge`|`boolean`| Optional parameter to merge the default branch into the requested ref if it is behind the default branch. Default: `true`
`required_contexts`|`Array`| Optional array of status contexts verified against commit status checks. If this parameter is omitted from the parameters then all unique contexts will be verified before a deployment is created. To bypass checking entirely pass an empty array. Defaults to all unique contexts.
`payload`|`string` | Optional JSON payload with extra information about the deployment. Default: `""`
`environment`|`string` | Optional name for the target deployment environment (e.g., production, staging, qa). Default: `"production"`
`description`|`string` | Optional short description. Default: `""`
+{% if page.version == 'dotcom' || page.version > 2.6 %} `transient_environment` | `boolean` | Optionally specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: `false` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+{% if page.version == 'dotcom' || page.version > 2.6 %} `production_environment` | `boolean` | Optionally specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `"production"` and `false` otherwise. **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+
+{% if page.version == 'dotcom' || page.version > 2.6 %}
+{{#tip}}
+
+The new `transient_environment` and `production_environment` parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the [blog post][blog-post] 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.ant-man-preview+json
+```
+
+{{/tip}}
+
+{% endif %}
#### Simple Example
@@ -150,6 +167,8 @@ chat networks.
:description => "Deploying my sweet branch"
%>
+### Successful response
+
<%= headers 201, :Location => get_resource(:deployment)['url'] %>
<%= json :deployment %>
@@ -165,9 +184,25 @@ A more advanced example specifying required commit statuses and bypassing auto-m
:required_contexts => ["ci/janky", "security/brakeman"]
%>
+### Successful response
+
<%= headers 201, :Location => get_resource(:deployment)['url'] %>
<%= json :deployment %>
+### Merge conflict response
+
+This error happens when the `auto_merge` option is enabled and when the default branch (in this case `master`), can't be merged into the branch that's being deployed (in this case `topic-branch`), due to merge conflicts.
+
+<%= headers 409 %>
+<%= json({ :message => "Conflict merging master into topic-branch" }) %>
+
+### Failed commit status checks
+
+This error happens when the `required_contexts` parameter indicates that one or more contexts need to have a `success` status for the commit to be deployed, but one or more of the required contexts do not have a state of `success`.
+
+<%= headers 409 %>
+<%= json({ :message => "Conflict: Commit status checks failed for topic-branch." }) %>
+
## Update a Deployment
Once a deployment is created, it cannot be updated. Information relating to the
@@ -203,9 +238,28 @@ Users with push access can create deployment statuses for a given deployment:
Name | Type | Description
-----|------|--------------
-`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, or `failure`.
+`state`|`string` | **Required**. The state of the status. Can be one of `pending`, `success`, `error`, {% if page.version == 'dotcom' || page.version > 2.6 %} `inactive`, {% endif %}or `failure` **The `inactive` state requires a custom media type to be specified. Please see more in the alert below.**.
`target_url`|`string` | The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Default: `""`
+{% if page.version == 'dotcom' || page.version > 2.6 %}`log_url`|`string` | This is functionally equivalent to `target_url`. We will continue accept `target_url` to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Default: `""` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
`description`|`string` | A short description of the status. Maximum length of 140 characters. Default: `""`
+{% if page.version == 'dotcom' || page.version > 2.6 %}`environment_url`|`string`| Optionally set the URL for accessing your environment. Default: `""` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+{% if page.version == 'dotcom' || page.version > 2.6 %}`auto_inactive`|`boolean`| Optional parameter to add a new `inactive` status to all non-transient, non-production environment deployments with the same repository and environment name as the created status's deployment. Default: `true` **This parameter requires a custom media type to be specified. Please see more in the alert below.**{% endif %}
+
+{% if page.version == 'dotcom' || page.version > 2.6 %}
+
+{{#tip}}
+
+The new `inactive` state, rename of the `target_url` parameter to `log_url` and new `environment_url` and `auto_inactive` parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the [blog post][blog-post] 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.ant-man-preview+json
+```
+
+{{/tip}}
+
+{% endif %}
#### Example
@@ -219,3 +273,5 @@ Name | Type | Description
<%= headers 201, :Location => get_resource(:deployment_status)['url'] %>
<%= json :deployment_status %>
+
+[blog-post]: /changes/2016-04-06-deployment-and-deployment-status-enhancements
diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md
index d82fa9d90c..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
@@ -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/v3/repos/invitations.md b/content/v3/repos/invitations.md
new file mode 100644
index 0000000000..50469923aa
--- /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 /user/repository_invitations/:invitation_id
+
+### Response
+
+<%= headers 204 %>
+
+
+
+## Decline a repository invitation
+
+ DELETE /user/repository_invitations/:invitation_id
+
+### Response
+
+<%= headers 204 %>
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/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/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}}
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/content/v3/search.md b/content/v3/search.md
index 561b6d444b..bfdefdd175 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
@@ -93,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
@@ -182,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
@@ -231,7 +235,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)
@@ -285,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
@@ -357,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/content/v3/troubleshooting.md b/content/v3/troubleshooting.md
index f49a24e158..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.
@@ -29,6 +29,8 @@ It's important to *not* try and guess the format of the pagination URL. Not ever
API call uses the same structure. Instead, extract the pagination information from
[the Link Header](/v3/#pagination), which is sent with every request.
+{% if page.version == 'dotcom' %}
+
## Can I get my rate limits bumped?
The {{ site.data.variables.product.product_name }} API has a pretty lenient quota for rate limits, for your enjoyment and
@@ -41,4 +43,6 @@ In certain exceptional cases, we may temporarily bump your rate limit higher. Yo
should be prepared to answer technical questions about your goal and your planned usage of the API. We may still choose not to bump your limit if we feel that you can achieve your wildest
dreams with the current rate limit (but don't worry, we'll help you out).
+{% endif %}
+
[oap-guide]: /changes/2015-01-19-an-integrators-guide-to-organization-application-policies/
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
diff --git a/content/v3/users/administration.md b/content/v3/users/administration.md
index 9fad54eb71..f918e2f38c 100644
--- a/content/v3/users/administration.md
+++ b/content/v3/users/administration.md
@@ -127,7 +127,7 @@ You can demote any user account except your own.
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync with Active Directory LDAP servers](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap), this API is disabled and will return a `403` response. Users managed by an external account cannot be suspended via the API.
+If your GitHub Enterprise appliance has [LDAP Sync with Active Directory LDAP servers](https://help.github.com/enterprise/admin/guides/user-management/using-ldap), this API is disabled and will return a `403` response. Users managed by an external account cannot be suspended via the API.
{{/warning}}
@@ -145,7 +145,7 @@ You can suspend any user account except your own.
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync with Active Directory LDAP servers](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap), this API is disabled and will return a `403` response. Users managed by an external account cannot be unsuspended via the API.
+If your GitHub Enterprise appliance has [LDAP Sync with Active Directory LDAP servers](https://help.github.com/enterprise/admin/guides/user-management/using-ldap), this API is disabled and will return a `403` response. Users managed by an external account cannot be unsuspended via the API.
{{/warning}}
diff --git a/content/v3/users/emails.md b/content/v3/users/emails.md
index e91ab346c2..0de8cb90b6 100644
--- a/content/v3/users/emails.md
+++ b/content/v3/users/emails.md
@@ -26,7 +26,7 @@ This endpoint is accessible with the user:email scope.
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap) and the option to synchronize emails enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to add an email address via the API with these options enabled.
+If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/admin/guides/user-management/using-ldap) and the option to synchronize emails enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to add an email address via the API with these options enabled.
{{/warning}}
@@ -62,7 +62,7 @@ You can post a single email address or an array of addresses:
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap) and the option to synchronize emails enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to remove an email address via the API with these options enabled.
+If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/admin/guides/user-management/using-ldap) and the option to synchronize emails enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to remove an email address via the API with these options enabled.
{{/warning}}
diff --git a/content/v3/users/gpg_keys.md b/content/v3/users/gpg_keys.md
new file mode 100644
index 0000000000..448737dc56
--- /dev/null
+++ b/content/v3/users/gpg_keys.md
@@ -0,0 +1,78 @@
+---
+title: User GPG Keys
+---
+
+{% if page.version == 'dotcom' %}
+
+# GPG Keys
+
+{{#tip}}
+
+
+
+ APIs for managing user GPG keys 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-04-04-git-signing-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.cryptographer-preview
+
+{{/tip}}
+
+{:toc}
+
+## List your GPG keys
+
+ GET /user/gpg_keys
+
+Lists the current user's GPG keys. Requires that you are authenticated via
+Basic Auth or via OAuth with at least `read:gpg_key`
+[scope](/v3/oauth/#scopes).
+
+### Response
+
+<%= headers 200, :pagination => default_pagination_rels %>
+<%= json(:gpg_key) { |h| [h] } %>
+
+## Get a single GPG key
+
+View extended details for a single GPG key. Requires that you are
+authenticated via Basic Auth or via OAuth with at least `read:gpg_key`
+[scope](/v3/oauth/#scopes).
+
+ GET /user/gpg_keys/:id
+
+### Response
+
+<%= headers 200 %>
+<%= json :gpg_key %>
+
+## Create a GPG key
+
+Creates a GPG key. Requires that you are authenticated via Basic Auth,
+or OAuth with at least `write:gpg_key` [scope](/v3/oauth/#scopes).
+
+ POST /user/gpg_keys
+
+### Input
+
+<%= json :armored_public_key => "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----" %>
+
+### Response
+
+<%= headers 201, :Location => get_resource(:gpg_key)['url'] %>
+<%= json :gpg_key %>
+
+## Delete a GPG key
+
+Removes a GPG key. Requires that you are authenticated via Basic Auth
+or via OAuth with at least `admin:gpg_key` [scope](/v3/oauth/#scopes).
+
+ DELETE /user/gpg_keys/:id
+
+### Response
+
+<%= headers 204 %>
+
+{% endif %}
diff --git a/content/v3/users/keys.md b/content/v3/users/keys.md
index db532953d6..25378d75f4 100644
--- a/content/v3/users/keys.md
+++ b/content/v3/users/keys.md
@@ -53,7 +53,7 @@ or OAuth with at least `write:public_key` [scope](/v3/oauth/#scopes).
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap) and the option to synchronize SSH keys enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to add an SSH key address via the API with these options enabled.
+If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/admin/guides/user-management/using-ldap) and the option to synchronize SSH keys enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to add an SSH key address via the API with these options enabled.
{{/warning}}
@@ -85,7 +85,7 @@ or via OAuth with at least `admin:public_key` [scope](/v3/oauth/#scopes).
{{#warning}}
-If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap) and the option to synchronize SSH keys enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to remove an SSH key address via the API with these options enabled.
+If your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/admin/guides/user-management/using-ldap) and the option to synchronize SSH keys enabled, this API is disabled and will return a `403` response. Users managed in LDAP won't be able to remove an SSH key address via the API with these options enabled.
{{/warning}}
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)
diff --git a/content/webhooks/index.md b/content/webhooks/index.md
index 84fea5159d..03fc42d1ca 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 an Issue or Pull Request is [commented](/v3/issues/comments/) on.
-[`issues`][event-types-issues] | Any time an Issue is assigned, unassigned, labeled, unlabeled, opened, closed, or reopened.
-[`member`][event-types-member] | Any time a User is added as a collaborator to a non-Organization Repository.
+[`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 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 is created on a portion of the unified diff](/v3/pulls/comments) of a pull request (the Files Changed tab).
-[`pull_request`][event-types-pull_request] | Any time a Pull Request is assigned, unassigned, labeled, unlabeled, opened, 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. **Organization hooks only**.
+[`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.
@@ -96,9 +96,9 @@ several special headers:
Header | Description
-------|-------------|
-`X-Github-Event`| Name of the [event][events-section] that triggered this delivery.
+`X-GitHub-Event`| Name of the [event][events-section] that triggered this delivery.
`X-Hub-Signature`| HMAC hex digest of the payload, using [the hook's `secret`][repo-hooks-create] as the key (if configured).
-`X-Github-Delivery`| Unique ID for this delivery.
+`X-GitHub-Delivery`| Unique ID for this delivery.
Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
@@ -112,7 +112,7 @@ Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615
-> X-Github-Event: issues
+> X-GitHub-Event: issues
> {
> "action": "opened",
@@ -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
diff --git a/data/variables/product.yml b/data/variables/product.yml
index 864c55b430..221100b3ca 100644
--- a/data/variables/product.yml
+++ b/data/variables/product.yml
@@ -1,15 +1,15 @@
api_url_pre:
{% if page.version == 'dotcom' %}
- 'api.github.com'
+ 'https://api.github.com'
{% else %}
- 'http(s)://[hostname]/api/v3/'
+ 'http(s)://[hostname]/api/v3'
{% endif %}
api_url_code:
{% if page.version == 'dotcom' %}
- 'api.github.com'
+ 'https://api.github.com'
{% else %}
- 'http(s)://[hostname]/api/v3/'
+ 'http(s)://[hostname]/api/v3'
{% endif %}
product_name:
diff --git a/layouts/includes/pagination_bar.html b/layouts/includes/pagination_bar.html
index d20c1f367c..8a0c13ade1 100644
--- a/layouts/includes/pagination_bar.html
+++ b/layouts/includes/pagination_bar.html
@@ -1,4 +1,4 @@
-
+<%# @count_gap refers to the minimum number of sibling pages to show %>
<% @count_gap = 2; @i = 1; @total_pages = total_pages; %>