Merge branch 'master' into config-reference-updated-0923

Author: teesloane

.circleci/config.yml

@@ -110,7 +110,7 @@ jobs:
           command: |
             cd src-api; rm -r build; rm source/index.html.md
             curl https://circleci.com/api/v2/openapi.json > openapi.json
-            node node_modules/widdershins/widdershins.js --search false --language_tabs 'shell:Curl' 'ruby:Ruby' 'python:Python' 'javascript:Javascript' 'go: Go' --summary openapi.json -o source/index.html.md
+            node node_modules/widdershins/widdershins.js --environment ../widdershins.apiv2.yml --summary openapi.json -o source/index.html.md
             bundle exec middleman build --clean
             cp -R build/* ../jekyll/_api/v2
 
@@ -128,7 +128,7 @@ jobs:
             ./scripts/build_pdfs.sh
       - run:
           name: Test with HTMLproofer
-          command: bundle exec htmlproofer jekyll/_site --allow-hash-href --check-favicon --check-html --disable-external --file-ignore "/docs/ja/2.0/aws-prereq/,/docs/ja/2.0/ops/,/docs/ja/2.0/about-circleci/,/docs/ja/2.0/demo-apps/,/docs/ja/2.0/google-auth/,/docs/ja/2.0/orb-concepts/,/docs/ja/2.0/tutorials/" --empty-alt-ignore | tee $JOB_RESULTS_PATH/htmlproofer-results.txt
+          command: bundle exec htmlproofer jekyll/_site --allow-hash-href --check-favicon --check-html --disable-external --file-ignore "/docs/ja/2.0/customizations/,/docs/ja/2.0/aws-prereq/,/docs/ja/2.0/ops/,/docs/ja/2.0/about-circleci/,/docs/ja/2.0/demo-apps/,/docs/ja/2.0/google-auth/,/docs/ja/2.0/orb-concepts/,/docs/ja/2.0/tutorials/" --empty-alt-ignore | tee $JOB_RESULTS_PATH/htmlproofer-results.txt
       - store_artifacts:
           path: release/tmp/
       - store_artifacts:

pull_request_template.md renamed to .github/pull_request_template.md

@@ -6,7 +6,7 @@ gem 'jekyll', "3.8.6"
 gem 'html-proofer'
 gem "rack", ">= 2.0.6"
 gem 'asciidoctor'
-gem 'asciidoctor-pdf', '~> 1.5.0.beta.2'
+gem 'asciidoctor-pdf', '~> 1.5.0.beta.5'
 gem 'pygments.rb', '~> 1.1.2'
 
 group :jekyll_plugins do

Gemfile

@@ -17,7 +17,7 @@ GEM
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
     asciidoctor (2.0.10)
-    asciidoctor-pdf (1.5.0.beta.2)
+    asciidoctor-pdf (1.5.0.beta.5)
       asciidoctor (>= 1.5.3, < 3.0.0)
       concurrent-ruby (~> 1.1.0)
       prawn (~> 2.2.0)
@@ -180,7 +180,7 @@ PLATFORMS
 
 DEPENDENCIES
   asciidoctor
-  asciidoctor-pdf (~> 1.5.0.beta.2)
+  asciidoctor-pdf (~> 1.5.0.beta.5)
   html-proofer
   jekyll (= 3.8.6)
   jekyll-algolia (~> 1.0)

Gemfile.lock

@@ -1,11 +1,11 @@
 # Local Development Instructions
 
 
-There are two ways to work on CircleCI docs locally: with Docker and with Ruby/Bundler.
+There are two ways to work on CircleCI docs locally: with Docker and with [Ruby](https://www.ruby-lang.org/en/)/[Bundler](http://bundler.io/).
 
 ## 1. Local Development with Docker (recommended)
 
-1. Install Docker for you platform: <https://docs.docker.com/engine/installation/>
+1. Install Docker for your platform: <https://docs.docker.com/engine/installation/>
 2. Clone the CircleCI docs repo: `git clone https://github.com/circleci/circleci-docs.git`
 3. Download this file: https://circleci.com/docs/assets/app.bundle-576b5ac91166f5b87d5f6254b647c9182e3468eeea4717c8cdc7ff7304cac0c9.js
 4. Rename the file from Step 3 to `app.bundle.js` and save it in the `jekyll/assets/js` directory.
@@ -28,7 +28,7 @@ You're welcome to use [Bundler](http://bundler.io/) to install these gems.
 
 ## Building js assets
 
-Our js assets are compiled by webpack and put into a place that the jekyll build can find them.
+Our js assets are compiled by webpack and put into a place where the jekyll build can find them.
 
 Anytime you are working on js be sure to run:
 
@@ -53,13 +53,13 @@ For more info on how to use Jekyll, check out [their docs](https://jekyllrb.com/
 
 ## Editing Docs Locally
 
-The docs site includes Bootstrap 3 JS and CSS, so you'll have access to all of its [reusable components](https://v4-alpha.getbootstrap.com/components/alerts/).
+The docs site includes Bootstrap 3, JS, and CSS, so you'll have access to all of its [reusable components](https://v4-alpha.getbootstrap.com/components/alerts/).
 
 All docs live in folders named after the version of CircleCI. The only two you need to worry about are `jekyll/_cci1` and `jekyll/_cci2`. These correspond to CircleCI Classic and CircleCI 2.0, respectively.
 
 1. Create a branch and switch to it:
 
-    `git checkout -b <branch-name`
+    `git checkout -b <branch-name>`
 
 2. Add or modify Markdown files in these directories according to our [style guide](CONTRIBUTING#style-guide).
 

README-local-development.md

@@ -1,6 +1,6 @@
 # CircleCI Documentation [![CircleCI Build Status](https://circleci.com/gh/circleci/circleci-docs.svg?style=shield)](https://circleci.com/gh/circleci/circleci-docs) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/circleci/circleci-docs/master/LICENSE) [![CircleCi Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com)
 
-This is the public repository for <https://circleci.com/docs/>, a static website generated by [Jekyll](https://jekyllrb.com/). If you find any errors in our docs or have suggestions, please follow our [Contributing Guide](CONTRIBUTING.md) to submit an issue or pull request.
+This is the public repository for [CircleCI Docs](https://circleci.com/docs/), a static website generated by [Jekyll](https://jekyllrb.com/). If you find any errors in our docs or have suggestions, please follow our [Contributing Guide](CONTRIBUTING.md) to submit an issue or pull request.
 
 For minor changes like typos, you can click **Suggest an edit to this page**, located at the bottom of each article. This will take you to the source file on GitHub, where you can submit a pull request for your change through the UI.
 

README.md

@@ -27,7 +27,7 @@ echo "This is 2.0 config."
 ````
 
 After the string `codetab` you'll see the integer `1`.
-This is how tabbed code blocks are group.
+This is how tabbed code blocks are grouped.
 Everything with `1` appears together in a group.
 Everything with `2` will appear in a separate group of tabs, and so on.
 

WIDGETS.md

@@ -6,5 +6,5 @@ services:
     volumes:
       - ".:/srv/jekyll"
     ports:
-      - 4000:4000
-      - 35729:35729
+      - 127.0.0.1:4000:4000
+      - 127.0.0.1:35729:35729

docker-compose.yml

@@ -1,5 +1,5 @@
 = INSTALLATION GUIDE: A guide for installing and upgrading CircleCI Server on AWS.
-Docs Team
+[email protected]
 :title-page-background-image: image:pdf-header.png[]
 :imagesdir: ../assets/img/docs/
 :doctype: book

jekyll/_cci2/CircleCI-Server-AWS-Installation-Guide-v2-17.pdf

@@ -1,5 +1,5 @@
 = OPERATIONS GUIDE: A guide for administrators of CircleCI Server installations on AWS and private infrastructure.
-Docs Team
+[email protected]
 :media: screen
 :title-page-background-image: image:pdf-header.png[]
 :imagesdir: ../assets/img/docs/

jekyll/_cci2/CircleCI-Server-AWS-Installation-Guide.pdf

@@ -7,10 +7,9 @@ categories: [configuring-jobs]
 order: 80
 ---
 
-
 This document describes how to trigger jobs using the CircleCI API.
 
-**Note:** Triggering jobs from the API is **not** supported with v2.1.
+**Note:** You cannot currently trigger jobs that use 2.1 config from the API.
 
 * TOC
 {:toc}

jekyll/_cci2/CircleCI-Server-Operations-Guide-v2-17.pdf

@@ -5,48 +5,62 @@
 :toc: macro
 :toc-title:
 
-This document describes how to enable, configure, and test CircleCI to authenticate users with OpenLDAP or Active Directory credentials.
-
-NOTE: LDAP is not supported with existing installations, only clean installations may use LDAP.
+This document describes the various ways users of your CircleCI Server installation can get access and authenticate their accounts. Currently OAuth and LDAP are supported as authentication methods.
 
 toc::[]
 
-== Prerequisites
+== OAuth with Github/GHE
+
+The default method for user account authentication in CircleCI Server is through GitHub.com/GitHub Enterprise OAuth.
+
+Once your installation is up and running, you can simply provide users with a link to access the application - for example `<your-circleci-hostname>.com` – and from there they will be prompted to set up an account by running through the GitHub/GitHub Enterprise OAuth flow and then redirected to the CircleCI login screen.
+
+.CircleCI Server Login Screen
+image::server_login.png[Server Login]
+
+== LDAP
+As an alternative to the OAuth/GitHub option described above, you can choose LDAP authentication. This section describes how to enable, configure, and test CircleCI to authenticate users with OpenLDAP or Active Directory credentials.
+
+CAUTION: Enabling LDAP will mean it is the **only** way for users to authenticate their account for your installation. Turning on LDAP Authentication is **not recommended for existing installations that previously had users authenticating with GitHub**. Please contact your account team if you need to switch to LDAP for an existing installation.
+
+=== Prerequisites
+
+* Install and configure your OpenLDAP server or Active Directory.
+* GitHub Enterprise or GitHub.com must be configured and be the source of organizations and projects to which users have access.
+* Install a new instance of CircleCI Server with no existing users.
+
+NOTE: After setting up LDAP, all users must log in to CircleCI with their LDAP credentials. After logging in, each user will then click the Connect button on the Accounts page to connect and authenticate their GitHub account.
 
-* Install and configure your LDAP server and Active Directory.
-* GitHub Enterprise must be configured and is the source of organizations and projects to which users have access.
-* Install a new instance of CircleCI 2.0 with no existing users.
-* Contact https://support.circleci.com[CircleCI support] and file a feature request for CircleCI Server.
-// still required?
+=== Configure LDAP Authentication
 
-NOTE: After completing this configuration, all users must log in to CircleCI with their LDAP credentials. After logging in to CircleCI, each user will then click the Connect button on the Accounts page to connect and authenticate their GitHub account.
+Below is an example configuration to give an idea of the information types required. The example shows OpenLDAP in use but settings will be comparable to what is required when using Active Directory:
 
-== Configure LDAP Authentication
+.LDAP Config Example
+image::LDAP_example.png[LDAP Example]
 
 This section provides the steps to configure LDAP in the CircleCI Server Management Console:
 
 . Verify access over the LDAP/AD ports to your LDAP/AD servers.
-. Log in as administrator to the Management Console for your newly installed CircleCI 2.0 instance.
-. Navigate to the Settings page and check the Enable LDAP-only Authentication button. Select either OpenLDAP or Active Directory.
-+
-.Enable LDAP
-image::LDAP.png[Enable LDAP]
+. Log in as administrator to the Management Console for your newly installed CircleCI instance.
+. Navigate to the Settings page (for example `<your-circleci-hostname>.com:8800`) and scroll down to check the Enable LDAP-only Authentication button. Select either OpenLDAP or Active Directory.
 . Fill in your LDAP instance Hostname and port number.
 . Select the encryption type (plain text is not recommended).
-. Fill in the Search user field with the LDAP admin username using the format `cn=<admin>,dc=<example>,dc=<org>` replacing `admin`, `example`, and `org` with appropriate values for your datacenter.
-. Fill in the Search password field with the LDAP admin password.
-. Fill in the User search DN field with an approrpiate value using the format `ou=<users>` replacing `users` with the value used in your LDAP instance.
-. Fill in the Username field with an approriate unique identifier used for your users, for example, `mail`.
-. Fill in the Group Membership field with an appropriate value. By default, the value is `uniqueMember` for OpenLDAP and `member` for Active Directory. This field will list member `dn` for a group.
-. Fill in the Group Object Class field with an approrpiate value. By default, the value is `groupOfUniqueNames` for OpenLDAP and `group` for Active Directory. The value of the `objectClass` field indicates a `dn` is a group.
-. (Optional) Fill in the Test username and Test password fields with a test email and password for an LDAP user you want to test.
+. Fill in the Search user field with the Fully Distinguished Name for a user who is authorized to perform search queries over a LDAP database. Example:  `cn=<admin>,dc=<example>,dc=<org>`.
+. Fill in the Search password field with the LDAP password for a user from the previous step.
+. Fill in the Base DN field with a Distinguished Name for a point in the directory from where CircleCI will be looking for users/groups. Example: `ou=company,dc=example,dc=org`
+. Fill in the User search DN field with a Relative Distinguished Name for a point in a directory where CircleCI will find users. Should be relative to the Base DN provided above. Example: `ou=users`.
+. Fill in the Username field with a name of an attribute that will be used as a source of usernames for Logging In. Example: `uid` (in this case users will have to use their UID for logging in) or `mail` (in this case users will be using emails for logging in).
+. Fill in the Email field with the name of an attribute that will be used as a source of a user email. Example: `mail`
+. Fill in the Group Membership field with a name of an attribute that will be used for user membership in a particular group. Example: `uniqueMember`.
+. Fill in the Group Object Class field with a name of an Object Class that will identify DN as a group. Example: `groupOfUniqueNames`
+. (Optional) Fill in the Test username and Test password fields with a test email and password for an LDAP user you want to test - this is a 3rd party infrastructure and this test option is not always reliable.
 . Save the settings.
 
 A user who logs in will be redirected to the Accounts page of the CircleCI application with a Connect button that they must use to connect their GitHub account. After they click Connect, an LDAP section with their user information (for example, their email) on the page will appear and they will be directed to authenticate their GitHub account. After authenticating their GitHub account users are directed to the **Job page** to use CircleCI.
 
 NOTE: A user who has authenticated with LDAP and is then removed from LDAP/AD will be able to access CircleCI as long as they stay logged in (because of cookies). As soon as the user logs out or the cookie expires, they will not be able to log back in. A users' ability to see projects or to run builds is defined by their GitHub permissions. Therefore, if GitHub permissions are synced with LDAP/AD permissions, a removed LDAP/AD user will automatically lose authorization to view or access CircleCI as well.
 
-== Troubleshooting
+=== Troubleshooting
 
 Troubleshoot LDAP server settings with LDAP search as follows:
 

jekyll/_cci2/CircleCI-Server-Operations-Guide.pdf

@@ -192,7 +192,7 @@ image::storage.png[]
 +
 NOTE: Due to an issue with our third party tooling, Replicated, the Test SMTP Authentication button is not currently working
 
-. Configure VM service if you plan to use https://circleci.com/docs/2.0/building-docker-images/[Remote Docker] or `machine` executor features. We recommend using an IAM instance profile for authentication, as described in the <<aws-prereq#planning,planning>> section of this document. With this section completed, instances will automatically be provisioned to execute jobs in Remote Docker or use the `machine` executor.
+. Configure VM service if you plan to use https://circleci.com/docs/2.0/building-docker-images/[Remote Docker] or `machine` executor features. We recommend using an IAM instance profile for authentication, as described in the <<aws-prereq#planning,planning>> section of this document. With this section completed, instances will automatically be provisioned to execute jobs in Remote Docker or use the `machine` executor. For more information on VM Service and creating custom AMIs for remote Docker and `machine` executor jobs, see our https://circleci.com/docs/2.0/vm-service/#section=server-administration[VM service guide].
 +
 .Configure VM Service
 image::vmprovider.png[]
@@ -201,10 +201,12 @@ You can preallocate instances to always be up and running, reducing the time tak
 +
 CAUTION: If Docker Layer Caching (DLC) is to be used VM preallocation must be set to `0` – on-demand – for both Remote Docker and `machine` executor.
 
-. If you wish to use AWS Cloudwatch or Datadog for collating metrics for your installation, set this up here. For more infomration see our https://circleci.com/docs/2.0/monitoring/[Monitoring guidance]:
+. If you wish to use AWS Cloudwatch or Datadog for collating metrics for your installation, set this up here. For more information see our https://circleci.com/docs/2.0/monitoring/[Monitoring guidance]:
 +
 .Metrics
 image::metrics_setup.png[]
++
+You can also customize the metrics received through Telegraf. For more on this see our https://circleci.com/docs/2.0/monitoring/#custom-metrics[Custom Metics] guide.
 
 . Artifacts persist data after a job is completed, and may be used for longer-term storage of your build process outputs. By default, CircleCI Server only allows approved types to be served. This is to protect users from uploading, and potentially executing malicious content. The **Artifacts** setting allows you to override this protection. For more information on safe/unsafe types see our https://circleci.com/docs/2.0/build-artifacts/[Build Artifacts guidance].
 

jekyll/_cci2/_aws-install.adoc

@@ -79,7 +79,7 @@ jobs:
       # CircleCI maintains a library of pre-built images
       # documented at https://circleci.com/docs/2.0/circleci-images/
       # the working dir is github repo that you need to fork to become owner.
-    working_directory: ~/nightwatch-saple-for-circleci
+    working_directory: ~/nightwatch-sample-for-circleci
     steps:
       - checkout
 
@@ -97,7 +97,7 @@ jobs:
       # Download and cache dependencies
       - restore_cache:
           keys:
-            - v1-dependencies-{{ checksum "package.json" }}
+            - v1-dependencies-{{ checksum "package-lock.json" }}
             # fallback to using the latest cache if no exact match is found
       - run: npm install
       # run tests!
@@ -157,14 +157,14 @@ build:
 # Download and cache dependencies
 #    - restore_cache:
 #        keys:
-#          - v1-dependencies-{{ checksum "package.json" }}       	
+#          - v1-dependencies-{{ checksum "package-lock.json" }}       	
         # fallback to using the latest cache if no exact match is found
    	
         - run: npm install
 #      - save_cache:
 #        paths:
 #      - node_modules
-#        key: v1-dependencies-{{ checksum "package.json" }}
+#        key: v1-dependencies-{{ checksum "package-lock.json" }}
 
     # run tests!
       - run: node_modules/.bin/nightwatch -e chrome