Sync changes from upstream repository

Hubot · Hubot · commit 1fd0e52106cd · 2015-01-20T17:09:12.000Z
diff --git a/Rules b/Rules
@@ -30,6 +30,7 @@ compile '/v3/*' do
   filter :search
   filter :erb
   filter :kramdown, :toc_levels => [2]
+  filter :enterprise_purge_filter
   filter :tip_filter
   filter :colorize_syntax,
     :colorizers => {:javascript => :rouge}
diff --git a/content/v3/enterprise.md b/content/v3/enterprise.md
@@ -2,18 +2,12 @@
 title: Enterprise | GitHub API
 ---
 
-# Enterprise
+# Enterprise <%= fetch_content(:latest_enterprise_version) %>
 
 * TOC
 {:toc}
 
-GitHub Enterprise supports the same powerful API available on GitHub.com as well as its own set of API endpoints:
-
-- Use the [Admin Stats][] API to get usage statistics
-- Use the [License][] API to get license information
-- Use the [Search Indexing][] API to queue up search indexing jobs
-- Use the [Management Console][] API to perform common administrative tasks
-- Use the [User Administration][] API to promote, demote, suspend, and unsuspend users
+[GitHub Enterprise](https://enterprise.github.com/) supports the same powerful API available on GitHub.com as well as its own set of API endpoints. You can find a list of these endpoints on the sidebar, with the exception of the [User Administration][] API, which is within its own section.
 
 ## Endpoint URLs
 
@@ -33,21 +27,20 @@ http(s)://<em>hostname</em>/
 
 Your Enterprise installation's API endpoints accept [the same authentication methods](http://developer.github.com/v3/#authentication) as the GitHub.com API. Specifically, you can authenticate yourself with **[OAuth tokens][]** (which can be created using the [Authorizations API][]) or **[basic authentication][]**.
 
-The [Admin Stats][], [License][], [Search Indexing][], and [User Administration][] API endpoints are only accessible to GitHub Enterprise site administrators. The [Management Console][] API endpoints are only accessible via the [Management Console password][].
+Every Enterprise API endpoint is only accessible to GitHub Enterprise site administrators, with the exception of the [Management Console][] API, which is only accessible via the [Management Console password][].
 
 [Authorizations API]: /v3/oauth_authorizations/#create-a-new-authorization
 [OAuth tokens]: /v3/oauth/
 [basic authentication]: /v3/#basic-authentication
-[Admin Stats]: admin_stats/
-[License]: license/
-[Search Indexing]: search_indexing/
-[Management Console]: management_console/
+[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/
 
 ## Past Releases
 
-Documentation for the API that's bundled with your GitHub Enterprise appliance is available for the past two releases:
+The latest release for GitHub Enterprise is <%= fetch_content(:latest_enterprise_version) %>. The GitHub APIs available to this release are located at <https://developer.github.com/enterprise/<%= fetch_content(:latest_enterprise_version) %>/>.
+
+Documentation for the API that's bundled with your GitHub Enterprise appliance is available for past releases:
 
 * [API documentation for 2.0](https://developer.github.com/enterprise/2.0/)
 * [API documentation for 11.10.340](https://developer.github.com/enterprise/11.10.340/)
diff --git a/content/v3/enterprise/ldap.md b/content/v3/enterprise/ldap.md
@@ -0,0 +1,88 @@
+---
+title: LDAP
+---
+
+# LDAP
+
+* TOC
+{:toc}
+
+You can use the LDAP API to update account relationships between a GitHub Enterprise user and its linked LDAP entry or queue a new synchronization.
+
+With the LDAP mapping endpoints, you're able to update the Distinguished Name (DN) that a user maps to. Note that the LDAP sync endpoints are only effective if your GitHub Enterprise appliance has [LDAP Sync enabled](https://help.github.com/enterprise/2.1/admin/guides/user-management/using-ldap).
+
+## Update LDAP mapping for a user
+
+    PATCH /admin/ldap/user/:username/mapping
+
+### Body parameters
+
+Pass a JSON payload with the new LDAP Distinguished Name.
+
+#### Example
+
+    #!javascript
+    {
+      "uid": "asdf",
+      "ou": "users",
+      "dc": "github",
+      "dc": "com"
+    }
+
+### Response
+
+<%= headers 200 %>
+<%= json :ldap_user_update %>
+
+## Sync LDAP mapping for a user
+
+{{#tip}}
+
+Note that this API call does not automatically initiate an LDAP sync. Rather, if a `201` is returned, the sync job is queued successfully, and is performed when the instance is ready.
+
+{{/tip}}
+
+    POST /admin/ldap/user/:username/sync
+
+### Response
+
+<%= headers 201 %>
+<%= json :ldap_sync_confirm %>
+
+## Update LDAP mapping for a team
+
+    PATCH /admin/ldap/teams/:team_id/mapping
+
+### Body parameters
+
+Pass a JSON payload with the new LDAP Distinguished Name.
+
+#### Example
+
+    #!javascript
+    {
+      "cn": "Enterprise Ops",
+      "ou": "teams",
+      "dc": "github",
+      "dc": "co"
+    }
+
+### Response
+
+<%= headers 200 %>
+<%= json :ldap_team_update %>
+
+## Sync LDAP mapping for a team
+
+{{#tip}}
+
+Note that this API call does not automatically initiate an LDAP sync. Rather, if a `201` is returned, the sync job is queued successfully, and is performed when the instance is ready.
+
+{{/tip}}
+
+    POST /admin/ldap/user/:teamname/sync
+
+### Response
+
+<%= headers 201 %>
+<%= json :ldap_sync_confirm %>
diff --git a/content/v3/users/administration.md b/content/v3/users/administration.md
@@ -37,6 +37,12 @@ You can demote any user account except your own.
 
 ## Suspend a user
 
+{{#warning}}
+
+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}}
+
     PUT /users/:username/suspended
 
 You can suspend any user account except your own.
@@ -49,6 +55,12 @@ You can suspend any user account except your own.
 
 ## Unsuspend a user
 
+{{#warning}}
+
+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}}
+
     DELETE /users/:username/suspended
 
 ### Response
diff --git a/content/v3/users/emails.md b/content/v3/users/emails.md
@@ -23,6 +23,16 @@ This endpoint is accessible with the user:email scope.
 
 ## Add email address(es)
 
+{{#enterprise-only}}
+
+{{#warning}}
+
+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}}
+
+{{/enterprise-only}}
+
     POST /user/emails
 
 ### Input
@@ -49,6 +59,16 @@ You can post a single email address or an array of addresses:
 
 ## Delete email address(es)
 
+{{#enterprise-only}}
+
+{{#warning}}
+
+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}}
+
+{{/enterprise-only}}
+
     DELETE /user/emails
 
 ### Input
diff --git a/content/v3/users/keys.md b/content/v3/users/keys.md
@@ -50,6 +50,16 @@ authenticated via Basic Auth or via OAuth with at least `read:public_key`
 Creates a public key. Requires that you are authenticated via Basic Auth,
 or OAuth with at least `write:public_key` [scope](/v3/oauth/#scopes).
 
+{{#enterprise-only}}
+
+{{#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.
+
+{{/warning}}
+
+{{/enterprise-only}}
+
     POST /user/keys
 
 ### Input
@@ -72,6 +82,16 @@ instead.
 Removes a public key. Requires that you are authenticated via Basic Auth
 or via OAuth with at least `admin:public_key` [scope](/v3/oauth/#scopes).
 
+{{#enterprise-only}}
+
+{{#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.
+
+{{/warning}}
+
+{{/enterprise-only}}
+
     DELETE /user/keys/:id
 
 ### Response
diff --git a/layouts/sidebar.html b/layouts/sidebar.html
@@ -112,12 +112,13 @@ <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></
         </ul>
       </li>
       <li class="js-topic">
-        <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></a><a href="/v3/enterprise/">Enterprise</a></h3>
+        <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></a><a href="/v3/enterprise/">Enterprise <%= fetch_content(:latest_enterprise_version) %></a></h3>
         <ul class="js-guides">
           <li><a href="/v3/enterprise/admin_stats/">Admin Stats</a></li>
           <li><a href="/v3/enterprise/license/">License</a></li>
           <li><a href="/v3/enterprise/search_indexing/">Search Indexing</a></li>
           <li><a href="/v3/enterprise/management_console/">Management Console</a></li>
+          <li><a href="/v3/enterprise/ldap/">LDAP</a></li>
         </ul>
       </li>
     </ul>
diff --git a/lib/enterprise-purge.rb b/lib/enterprise-purge.rb
@@ -0,0 +1,19 @@
+class EnterprisePurgeFilter < Nanoc::Filter
+  identifier :enterprise_purge_filter
+  type :text
+
+  ENTERPRISE_START_STRING = '{{#enterprise-only}}'
+  ENTERPRISE_END_STRING = '{{/enterprise-only}}'
+
+  # if we're running in Dotcom mode, we'll be lazy and just hide the content.
+  # otherwise, when running script/enterprise-cutter, we'll bring these sections back
+  def run(content, params={})
+    start_replacement = '<div class="enterprise-only">'
+    end_replacement = '</div>'
+
+    content = content.gsub(%r{<p>#{ENTERPRISE_START_STRING}</p>}, start_replacement)
+    content = content.gsub(%r{<p>#{ENTERPRISE_END_STRING}</p>}, end_replacement)
+
+    content
+  end
+end
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -7,6 +7,7 @@
 module GitHub
   module Resources
     module Helpers
+
       STATUSES ||= {
         200 => '200 OK',
         201 => '201 Created',
@@ -117,6 +118,7 @@ def webhook_payload(event_name)
       end
 
       CONTENT ||= {
+        'LATEST_ENTERPRISE_VERSION' => '2.1',
         "PUT_CONTENT_LENGTH" => "Note that you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see \"[HTTP verbs](/v3/#http-verbs).\"",
         "ORG_HOOK_CONFIG_HASH" =>
         '''
@@ -2261,6 +2263,18 @@ def fetch_content(key)
         "pretty-print" => "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
       }
     ]
+
+    LDAP_USER_UPDATE ||= {
+      'ldap_dn' => 'uid=asdf,ou=users,dc=github,dc=com'
+    }.merge(USER)
+
+    LDAP_TEAM_UPDATE ||= {
+      'ldap_dn' => 'cn=Enterprise Ops,ou=teams,dc=github,dc=com'
+    }.merge(TEAM)
+
+    LDAP_SYNC_CONFIRM ||= {
+      'status' => 'queued'
+    }
   end
 end
 
diff --git a/script/enterprise-backport b/script/enterprise-backport
@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+# Occasionally, a change made to the latest version of the Enterprise API documentation
+# will need to be backported to the previous verison. This script takes the latest content
+# for /enterprise and moves it into the appropriate version folder.
+
+Dir.glob('tasks/*.rake').each { |r| load r }
+
+if ARGV.length != 1
+  error = '''Error: Run the script like this: bundle exec script/enterprise-backport [VERSION]
+e.g. bundle exec script/enterprise-cutter 2.0
+'''
+  abort error
+end
+
+version = ARGV[0].dup # like, 11.10.340
+
+BRANCH_NAME = "backport-docs-for-#{version}"
+
+setup
+
+temp_dir = Dir.mktmpdir
+begin
+  %x(git checkout `git rev-list -n 1 --before="#{date}" gh-pages`)
+  `cp -r v3/enterprise #{temp_dir}`
+  `git checkout #{BRANCH_NAME}`
+  `cp -r #{temp_dir}/* enterprise/#{version}`
+
+  rewrite_content("enterprise/#{version}")
+
+  `git add enterprise`
+  `git commit -m "Added enterprise-#{version} backported files"`
+ensure
+  FileUtils.remove_entry_secure temp_dir
+end
diff --git a/script/enterprise-cutter b/script/enterprise-cutter
diff --git a/static/css/documentation.css b/static/css/documentation.css
diff --git a/static/search-index.json b/static/search-index.json
diff --git a/tasks/enterprise.rake b/tasks/enterprise.rake
