From 1fd0e52106cddd88cabd04c263c48253896422bb Mon Sep 17 00:00:00 2001 From: Hubot Date: Tue, 20 Jan 2015 17:09:12 +0000 Subject: [PATCH] Sync changes from upstream repository --- Rules | 1 + content/v3/enterprise.md | 21 +++---- content/v3/enterprise/ldap.md | 88 ++++++++++++++++++++++++++++++ content/v3/users/administration.md | 12 ++++ content/v3/users/emails.md | 20 +++++++ content/v3/users/keys.md | 20 +++++++ layouts/sidebar.html | 3 +- lib/enterprise-purge.rb | 19 +++++++ lib/resources.rb | 14 +++++ script/enterprise-backport | 35 ++++++++++++ script/enterprise-cutter | 69 +++++++++-------------- static/css/documentation.css | 4 ++ static/search-index.json | 10 ++-- tasks/enterprise.rake | 44 +++++++++++++++ 14 files changed, 296 insertions(+), 64 deletions(-) create mode 100644 content/v3/enterprise/ldap.md create mode 100644 lib/enterprise-purge.rb create mode 100644 script/enterprise-backport create mode 100644 tasks/enterprise.rake diff --git a/Rules b/Rules index 77513398a0..0cc0bba096 100755 --- 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 index 94ea6b3291..a2ff5c249e 100644 --- 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)://hostname/ 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 />. + +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 new file mode 100644 index 0000000000..2a246af407 --- /dev/null +++ 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 index 59ee92791a..86a99a1d3f 100644 --- 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 index c35b6e8e19..2737161455 100644 --- 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 index b930dafcf0..bad4b33b2f 100644 --- 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 index ecfb9e44eb..73a58509d8 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -112,12 +112,13 @@

  • Enterprise

    +

    Enterprise <%= fetch_content(:latest_enterprise_version) %>

    • diff --git a/lib/enterprise-purge.rb b/lib/enterprise-purge.rb new file mode 100644 index 0000000000..9ffcb372b5 --- /dev/null +++ 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 = '
    ' + end_replacement = '
    ' + + content = content.gsub(%r{

    #{ENTERPRISE_START_STRING}

    }, start_replacement) + content = content.gsub(%r{

    #{ENTERPRISE_END_STRING}

    }, end_replacement) + + content + end +end diff --git a/lib/resources.rb b/lib/resources.rb index d13b327dda..a989447cd7 100644 --- 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 new file mode 100644 index 0000000000..0a58dca900 --- /dev/null +++ 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 index ce5dc780a0..111b7c428d 100755 --- a/script/enterprise-cutter +++ b/script/enterprise-cutter @@ -1,18 +1,27 @@ #!/usr/bin/env ruby +# When releasing a new Enterprise version, the set of GitHub APIs available to that +# verison do not match the set of documentation generally available on developer.github.com. +# That's because the content on developer.github.com represents everything available to DotCom +# users; since Enterprise is a "managed" product, it's cut off of DotCom at a certain +# time, and the APIs remain frozen (until an organization upgrades their instance). +# +# This script takes two arguments: a date and a version number. Given a date, it +# fetches the state of the site at that moment in time. It then copies all of that +# content into a new folder called *enterprise/*. Thus, we're able to preserve +# the state of the API documentation for a given version at a given time. + require 'fileutils' require 'tmpdir' require 'nokogiri' -ERROR_MESSAGE = """ -Error: Run the script like this: bundle exec script/enterprise-cutter [DATE] [VERSION] -e.g. bundle exec script/enterprise-cutter 2014-07-08 11.10.340 -""" +Dir.glob('tasks/*.rake').each { |r| load r } -if ARGV.length == 0 - abort "\n#{ERROR_MESSAGE}\n\n" -elsif ARGV.length > 2 - abort "\n#{ERROR_MESSAGE}\n\n" +if ARGV.length != 2 + error = '''Error: Run the script like this: bundle exec script/enterprise-cutter [DATE] [VERSION] +e.g. bundle exec script/enterprise-cutter 2014-07-08 11.10.340 +''' + abort error end date = ARGV[0].dup # yyyy-mm-dd, like, 2014-07-08 @@ -20,50 +29,22 @@ version = ARGV[1].dup # like, 11.10.340 BRANCH_NAME = "add-#{version}-docs" -%x(git checkout gh-pages) -%x(git pull origin gh-pages) - -%x(git checkout -b #{BRANCH_NAME}) +setup temp_dir = Dir.mktmpdir begin %x(git checkout `git rev-list -n 1 --before="#{date}" gh-pages`) - %x(cp -r * #{temp_dir}) - %x(git checkout #{BRANCH_NAME}) - version.sub!(/enterprise-/, '') + `cp -r * #{temp_dir}` + `git checkout #{BRANCH_NAME}` FileUtils.mkdir_p("enterprise/#{version}") - %x(cp -r #{temp_dir}/* enterprise/#{version}) - - # we need to point links not to the root, but to the enterprise version root - # for assets and links - Dir.glob("enterprise/#{version}/**/*.html") do |html_file| - doc = Nokogiri::HTML(File.read(html_file)) - doc.css('a').each do |a| - a['href'] = "/enterprise/#{version}#{a['href']}" if a['href'] =~ /^\// - end - doc.css('link').each do |link| - link['href'] = "/enterprise/#{version}#{link['href']}" if link['href'] =~ /^\// - end - doc.css('script').each do |script| - script['src'] = "/enterprise/#{version}#{script['src']}" if script['src'] =~ /^\// - end - doc.css('img').each do |img| - img['src'] = "/enterprise/#{version}#{img['src']}" if img['src'] =~ /^\// - end - doc.search('//*[@class="not-enterprise"]').remove - File.open(html_file, 'w') { |file| file.write(doc.to_html) } - end + `cp -r #{temp_dir}/* enterprise/#{version}` - Dir.glob("enterprise/#{version}/**/*.css") do |css_file| - contents = File.read(css_file) - contents.gsub!(/url\(\/shared/, "url(/enterprise/#{version}/shared") - File.open(css_file, 'w') { |file| file.write(contents) } - end + rewrite_content("enterprise/#{version}") - %x(git add enterprise) - %x(git commit -m "Added enterprise-#{version} files") + `git add enterprise` + `git commit -m "Added enterprise-#{version} files"` ensure FileUtils.remove_entry_secure temp_dir end -puts "\n\nOkay! Feel free to `git push #{BRANCH_NAME}` if you like." +puts "\n\nOkay! Feel free to `git push #{BRANCH_NAME}` if you like." \ No newline at end of file diff --git a/static/css/documentation.css b/static/css/documentation.css index 78e4819a61..b858fd6d86 100644 --- a/static/css/documentation.css +++ b/static/css/documentation.css @@ -21,6 +21,10 @@ h1 { font-weight: normal; } +body:not(.enterprise) .enterprise-only { + display: none; +} + .content h1 { font-weight: 300; -webkit-backface-visibility: hidden; diff --git a/static/search-index.json b/static/search-index.json index f5a779f727..bdf05d988d 100644 --- a/static/search-index.json +++ b/static/search-index.json @@ -58,27 +58,27 @@ { "url": "/v3/enterprise/", "title": "Enterprise", - "section": "API/Enterprise" + "section": "API/Enterprise " }, { "url": "/v3/enterprise/admin_stats/", "title": "Admin Stats", - "section": "API/Enterprise" + "section": "API/Enterprise " }, { "url": "/v3/enterprise/license/", "title": "License", - "section": "API/Enterprise" + "section": "API/Enterprise " }, { "url": "/v3/enterprise/management_console/", "title": "Management Console", - "section": "API/Enterprise" + "section": "API/Enterprise " }, { "url": "/v3/enterprise/search_indexing/", "title": "Search Indexing", - "section": "API/Enterprise" + "section": "API/Enterprise " }, { "url": "/v3/gists/", diff --git a/tasks/enterprise.rake b/tasks/enterprise.rake new file mode 100644 index 0000000000..4f439df007 --- /dev/null +++ b/tasks/enterprise.rake @@ -0,0 +1,44 @@ +def setup + `git checkout gh-pages` + `git pull origin gh-pages` + + `git checkout -b #{BRANCH_NAME}` +end + +# we need to point links not to the root, but to the enterprise version root +# for assets and links +def rewrite(path) + Dir.glob("#{path}/**/*.html") do |html_file| + doc = Nokogiri::HTML(File.read(html_file)) + + # add '.enterprise' to `@class` in `body` + body = doc.search('body').first + classes = body.get_attribute('class').to_s.split(' ') + body.set_attribute('class', classes.push('enterprise').uniq.join(' ')) + + doc.css('a').each do |a| + a['href'] = "/enterprise/#{version}#{a['href']}" if a['href'] =~ /^\// + end + + doc.css('link').each do |link| + link['href'] = "/enterprise/#{version}#{link['href']}" if link['href'] =~ /^\// + end + + doc.css('script').each do |script| + script['src'] = "/enterprise/#{version}#{script['src']}" if script['src'] =~ /^\// + end + + doc.css('img').each do |img| + img['src'] = "/enterprise/#{version}#{img['src']}" if img['src'] =~ /^\// + end + + doc.search('//*[@class="not-enterprise"]').remove + File.open(html_file, 'w') { |file| file.write(doc.to_html) } + end + + Dir.glob("#{path}/**/*.css") do |css_file| + contents = File.read(css_file) + contents.gsub!(/url\(\/shared/, "url(/enterprise/#{version}/shared") + File.open(css_file, 'w') { |file| file.write(contents) } + end +end