Merge branch 'master' into rm_duplicate_cache_ci_docs

9 files changed, 581 insertions, 36 deletions

diff --git a/doc/api/builds.md b/doc/api/builds.md
index d3ce72e59fc..4c0a47d1ea0 100644
--- a/doc/api/builds.md
+++ b/doc/api/builds.md
@@ -33,7 +33,6 @@ Example of response
         },
         "coverage": null,
         "created_at": "2015-12-24T15:51:21.802Z",
-        "download_url": null,
         "artifacts_file": {
           "filename": "artifacts.zip",
           "size": 1000
@@ -75,7 +74,6 @@ Example of response
         },
         "coverage": null,
         "created_at": "2015-12-24T15:51:21.727Z",
-        "download_url": null,
         "artifacts_file": null,
         "finished_at": "2015-12-24T17:54:24.921Z",
         "id": 6,
@@ -139,7 +137,6 @@ Example of response
         },
         "coverage": null,
         "created_at": "2016-01-11T10:13:33.506Z",
-        "download_url": null,
         "artifacts_file": null,
         "finished_at": "2016-01-11T10:14:09.526Z",
         "id": 69,
@@ -164,7 +161,6 @@ Example of response
         },
         "coverage": null,
         "created_at": "2015-12-24T15:51:21.957Z",
-        "download_url": null,
         "artifacts_file": null,
         "finished_at": "2015-12-24T17:54:33.913Z",
         "id": 9,
@@ -226,7 +222,6 @@ Example of response
     },
     "coverage": null,
     "created_at": "2015-12-24T15:51:21.880Z",
-    "download_url": null,
     "artifacts_file": null,
     "finished_at": "2015-12-24T17:54:31.198Z",
     "id": 8,
@@ -315,7 +310,6 @@ Example of response
     },
     "coverage": null,
     "created_at": "2016-01-11T10:13:33.506Z",
-    "download_url": null,
     "artifacts_file": null,
     "finished_at": "2016-01-11T10:14:09.526Z",
     "id": 69,
@@ -362,7 +356,6 @@ Example of response
     },
     "coverage": null,
     "created_at": "2016-01-11T10:13:33.506Z",
-    "download_url": null,
     "artifacts_file": null,
     "finished_at": null,
     "id": 69,
diff --git a/doc/ci/deployment/README.md b/doc/ci/deployment/README.md
index ffd841ca9e7..7d91ce6710f 100644
--- a/doc/ci/deployment/README.md
+++ b/doc/ci/deployment/README.md
@@ -89,7 +89,7 @@ We also use two secure variables:
 In GitLab CI 7.12 a new feature was introduced: Secure Variables.
 Secure Variables can added by going to `Project > Variables > Add Variable`. 
 **This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
-The variables that are defined in the project settings are send along with the build script to the runner.
+The variables that are defined in the project settings are sent along with the build script to the runner.
 The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml.
 It is also important that secret's value is hidden in the build log.
 
diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
index c1bb47e4291..f5645d586ae 100644
--- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
+++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -1,5 +1,5 @@
 ## Test and Deploy a ruby application
-This example will guide you how to run tests in your Ruby application and deploy it automatiacally as Heroku application.
+This example will guide you how to run tests in your Ruby application and deploy it automatically as Heroku application.
 
 You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all).
 
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 4dd5fe1f764..a9b79bbdb1b 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -116,7 +116,8 @@ Alias for [stages](#stages).
 
 ### variables
 
-_**Note:** Introduced in GitLab Runner v0.5.0._
+>**Note:**
+Introduced in GitLab Runner v0.5.0.
 
 GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build
 environment. The variables are stored in the git repository and are meant to
@@ -278,13 +279,14 @@ job_name:
 | Keyword       | Required | Description |
 |---------------|----------|-------------|
 | script        | yes | Defines a shell script which is executed by runner |
-| stage         | no (default: `test`) | Defines a build stage |
+| stage         | no | Defines a build stage (default: `test`) |
 | type          | no | Alias for `stage` |
 | only          | no | Defines a list of git refs for which build is created |
 | except        | no | Defines a list of git refs for which build is not created |
 | tags          | no | Defines a list of tags which are used to select runner |
 | allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
 | when          | no | Define when to run build. Can be `on_success`, `on_failure` or `always` |
+| dependencies  | no | Define other builds that a build depends on so that you can pass artifacts between them|
 | artifacts     | no | Define list build artifacts |
 | cache         | no | Define list of files that should be cached between subsequent runs |
 
@@ -437,15 +439,18 @@ The above script will:
 
 ### artifacts
 
-_**Note:** Introduced in GitLab Runner v0.7.0 for non-Windows platforms._
-
-_**Note:** Limited Windows support was added in GitLab Runner v.1.0.0. 
-Currently not all executors are supported._ 
-
-_**Note:** Build artifacts are only collected for successful builds._
+>**Notes:**
+>
+> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
+> - Windows support was added in GitLab Runner v.1.0.0.
+> - Currently not all executors are supported.
+> - Build artifacts are only collected for successful builds.
 
 `artifacts` is used to specify list of files and directories which should be
-attached to build after success. Below are some examples.
+attached to build after success. To pass artifacts between different builds,
+see [dependencies](#dependencies).
+
+Below are some examples.
 
 Send all files in `binaries` and `.config`:
 
@@ -456,14 +461,14 @@ artifacts:
   - .config
 ```
 
-Send all git untracked files:
+Send all Git untracked files:
 
 ```yaml
 artifacts:
   untracked: true
 ```
 
-Send all git untracked files and files in `binaries`:
+Send all Git untracked files and files in `binaries`:
 
 ```yaml
 artifacts:
@@ -497,6 +502,275 @@ release-job:
 The artifacts will be sent to GitLab after a successful build and will
 be available for download in the GitLab UI.
 
+#### artifacts:name
+
+>**Note:**
+Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
+
+The `name` directive allows you to define the name of the created artifacts
+archive. That way, you can have a unique name of every archive which could be
+useful when you'd like to download the archive from GitLab. The `artifacts:name`
+variable can make use of any of the [predefined variables](../variables/README.md).
+
+---
+
+**Example configurations**
+
+To create an archive with a name of the current build:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_BUILD_NAME"
+```
+
+To create an archive with a name of the current branch or tag including only
+the files that are untracked by Git:
+
+```yaml
+job:
+   artifacts:
+     name: "$CI_BUILD_REF_NAME"
+     untracked: true
+```
+
+To create an archive with a name of the current build and the current branch or
+tag including only the files that are untracked by Git:
+
+```yaml
+job:
+  artifacts:
+    name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}"
+    untracked: true
+```
+
+To create an archive with a name of the current [stage](#stages) and branch name:
+
+```yaml
+job:
+  artifacts:
+    name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}"
+    untracked: true
+```
+
+---
+
+If you use **Windows Batch** to run your shell scripts you need to replace
+`$` with `%`:
+
+```yaml
+job:
+  artifacts:
+    name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%"
+    untracked: true
+```
+
+### dependencies
+
+>**Note:**
+Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
+This feature should be used in conjunction with [`artifacts`](#artifacts) and
+allows you to define the artifacts to pass between different builds.
+
+Note that `artifacts` from previous [stages](#stages) are passed by default.
+
+To use this feature, define `dependencies` in context of the job and pass
+a list of all previous builds from which the artifacts should be downloaded.
+You can only define builds from stages that are executed before the current one.
+An error will be shown if you define builds from the current stage or next ones.
+
+---
+
+In the following example, we define two jobs with artifacts, `build:osx` and
+`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx`
+will be downloaded and extracted in the context of the build. The same happens
+for `test:linux` and artifacts from `build:linux`.
+
+The job `deploy` will download artifacts from all previous builds because of
+the [stage](#stages) precedence:
+
+```yaml
+build:osx:
+  stage: build
+  script: make build:osx
+  artifacts:
+    paths:
+    - binaries/
+
+build:linux:
+  stage: build
+  script: make build:linux
+  artifacts:
+    paths:
+    - binaries/
+
+test:osx:
+  stage: test
+  script: make test:osx
+  dependencies:
+  - build:osx
+
+test:linux:
+  stage: test
+  script: make test:linux
+  dependencies:
+  - build:linux
+
+deploy:
+  stage: deploy
+  script: make deploy
+```
+
+## Hidden jobs
+
+>**Note:**
+Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
+Jobs that start with a dot (`.`) will be not processed by GitLab CI. You can
+use this feature to ignore jobs, or use the
+[special YAML features](#special-yaml-features) and transform the hidden jobs
+into templates.
+
+In the following example, `.job_name` will be ignored:
+
+```yaml
+.job_name:
+  script:
+    - rake spec
+```
+
+## Special YAML features
+
+It's possible to use special YAML features like anchors (`&`), aliases (`*`)
+and map merging (`<<`), which will allow you to greatly reduce the complexity
+of `.gitlab-ci.yml`.
+
+Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).
+
+### Anchors
+
+>**Note:**
+Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
+YAML also has a handy feature called 'anchors', which let you easily duplicate
+content across your document. Anchors can be used to duplicate/inherit
+properties, and is a perfect example to be used with [hidden jobs](#hidden-jobs)
+to provide templates for your jobs.
+
+The following example uses anchors and map merging. It will create two jobs,
+`test1` and `test2`, that will inherit the parameters of `.job_template`, each
+having their own custom `script` defined:
+
+```yaml
+.job_template: &job_definition  # Hidden job that defines an anchor named 'job_definition'
+  image: ruby:2.1
+  services:
+    - postgres
+    - redis
+
+test1:
+  <<: *job_definition           # Merge the contents of the 'job_definition' alias
+  script:
+    - test1 project
+
+test2:
+  <<: *job_definition           # Merge the contents of the 'job_definition' alias
+  script:
+    - test2 project
+```
+
+`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the
+given hash into the current one", and `*` includes the named anchor
+(`job_definition` again). The expanded version looks like this:
+
+```yaml
+.job_template:
+  image: ruby:2.1
+  services:
+    - postgres
+    - redis
+
+test1:
+  image: ruby:2.1
+  services:
+    - postgres
+    - redis
+  script:
+    - test1 project
+
+test2:
+  image: ruby:2.1
+  services:
+    - postgres
+    - redis
+  script:
+    - test2 project
+```
+
+Let's see another one example. This time we will use anchors to define two sets
+of services. This will create two jobs, `test:postgres` and `test:mysql`, that
+will share the `script` directive defined in `.job_template`, and the `services`
+directive defined in `.postgres_services` and `.mysql_services` respectively:
+
+```yaml
+.job_template: &job_definition
+  script:
+    - test project
+
+.postgres_services:
+  services: &postgres_definition
+    - postgres
+    - ruby
+
+.mysql_services:
+  services: &mysql_definition
+    - mysql
+    - ruby
+
+test:postgres:
+  << *job_definition
+  services: *postgres_definition
+
+test:mysql:
+  << *job_definition
+  services: *mysql_definition
+```
+
+The expanded version looks like this:
+
+```yaml
+.job_template:
+  script:
+    - test project
+
+.postgres_services:
+  services:
+    - postgres
+    - ruby
+
+.mysql_services:
+  services:
+    - mysql
+    - ruby
+
+test:postgres:
+  script:
+    - test project
+  services:
+    - postgres
+    - ruby
+
+test:mysql:
+  script:
+    - test project
+  services:
+    - mysql
+    - ruby
+```
+
+You can see that the hidden jobs are conveniently used as templates.
+
 ## Validate the .gitlab-ci.yml
 
 Each instance of GitLab CI has an embedded debug tool called Lint.
diff --git a/doc/development/scss_styleguide.md b/doc/development/scss_styleguide.md
new file mode 100644
index 00000000000..6c48c25448b
--- /dev/null
+++ b/doc/development/scss_styleguide.md
@@ -0,0 +1,194 @@
+# SCSS styleguide
+
+This style guide recommends best practices for SCSS to make styles easy to read,
+easy to maintain, and performant for the end-user.
+
+## Rules
+
+### Naming
+
+CSS classes should use the `lowercase-hyphenated` format rather than
+`snake_case` or `camelCase`.
+
+```scss
+// Bad
+.class_name {
+  color: #fff;
+}
+
+// Bad
+.className {
+  color: #fff;
+}
+
+// Good
+.class-name {
+  color: #fff;
+}
+```
+
+### Formatting
+
+You should always use a space before a brace, braces should be on the same
+line, each property should each get its own line, and there should be a space
+between the property and its value.
+
+```scss
+// Bad
+.container-item { 
+  width: 100px; height: 100px;
+  margin-top: 0;
+}
+
+// Bad
+.container-item
+{
+  width: 100px;
+  height: 100px;
+  margin-top: 0;
+}
+
+// Bad
+.container-item{
+  width:100px;
+  height:100px;
+  margin-top:0;
+}
+
+// Good
+.container-item {
+  width: 100px;
+  height: 100px;
+  margin-top: 0;
+}
+```
+
+Note that there is an exception for single-line rulesets, although these are 
+not typically recommended.
+
+```scss
+p { margin: 0; padding: 0; }
+```
+
+### Colors
+
+HEX (hexadecimal) colors short-form should use shortform where possible, and 
+should use lower case letters to differenciate between letters and numbers, e.
+g. `#E3E3E3` vs. `#e3e3e3`.
+
+```scss
+// Bad
+p {
+  color: #ffffff;
+}
+
+// Bad
+p {
+  color: #FFFFFF;
+}
+
+// Good
+p {
+  color: #fff;
+}
+```
+
+### Indentation
+
+Indentation should always use two spaces for each indentation level.
+
+```scss
+// Bad, four spaces
+p {
+    color: #f00;
+}
+
+// Good
+p {
+  color: #f00;
+}
+```
+
+### Semicolons
+
+Always include semicolons after every property. When the stylesheets are 
+minified, the semicolons will be removed automatically.
+
+```scss
+// Bad
+.container-item {
+  width: 100px;
+  height: 100px
+}
+
+// Good
+.container-item {
+  width: 100px;
+  height: 100px;
+}
+```
+
+### Shorthand
+
+The shorthand form should be used for properties that support it.
+
+```scss
+// Bad
+margin: 10px 15px 10px 15px;
+padding: 10px 10px 10px 10px;
+
+// Good
+margin: 10px 15px;
+padding: 10px;
+```
+
+### Zero Units
+
+Omit length units on zero values, they're unnecessary and not including them 
+is slightly more performant.
+
+```scss
+// Bad
+.item-with-padding {
+  padding: 0px;
+}
+
+// Good
+.item-with-padding {
+  padding: 0;
+}
+```
+
+### Selectors with a `js-` Prefix
+Do not use any selector prefixed with `js-` for styling purposes. These 
+selectors are intended for use only with JavaScript to allow for removal or 
+renaming without breaking styling.
+
+## Linting
+
+We use [SCSS Lint][scss-lint] to check for style guide conformity. It uses the 
+ruleset in `.scss-lint.yml`, which is located in the home directory of the 
+project.
+
+To check if any warnings will be produced by your changes, you can run `rake 
+scss_lint` in the GitLab directory. SCSS Lint will also run in GitLab CI to 
+catch any warnings.
+
+If the Rake task is throwing warnings you don't understand, SCSS Lint's 
+documentation includes [a full list of their linters][scss-lint-documentation].
+
+### Fixing issues
+
+If you want to automate changing a large portion of the codebase to conform to 
+the SCSS style guide, you can use [CSSComb][csscomb]. First install
+[Node][node] and [NPM][npm], then run `npm install csscomb -g` to install 
+CSSComb globally (system-wide). Run it in the GitLab directory with 
+`csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS.
+
+Note that this won't fix every problem, but it should fix a majority.
+
+[csscomb]: https://github.com/csscomb/csscomb.js
+[node]: https://github.com/nodejs/node
+[npm]: https://www.npmjs.com/
+[scss-lint]: https://github.com/brigade/scss-lint
+[scss-lint-documentation]: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 4f011397269..aa989417c4b 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -22,7 +22,7 @@ If the highest number stable branch is unclear please check the [GitLab Blog](ht
 
 This guide is long because it covers many cases and includes all commands you need, this is [one of the few installation scripts that actually works out of the box](https://twitter.com/robinvdvleuten/status/424163226532986880).
 
-This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [doc/install/requirements.md](./requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/).
+This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/).
 
 This is the official installation guide to set up a production server. To set up a **development installation** or for many other installation options please see [the installation section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#installation).
 
@@ -76,7 +76,7 @@ Make sure you have the right version of Git installed
     # Install Git
     sudo apt-get install -y git-core
 
-    # Make sure Git is version 1.7.10 or higher, for example 1.7.12 or 2.0.0
+    # Make sure Git is version 2.7.3 or higher
     git --version
 
 Is the system packaged Git too old? Remove it and compile from source.
@@ -89,8 +89,9 @@ Is the system packaged Git too old? Remove it and compile from source.
 
     # Download and compile from source
     cd /tmp
-    curl -L --progress https://www.kernel.org/pub/software/scm/git/git-2.4.3.tar.gz | tar xz
-    cd git-2.4.3/
+    curl -O --progress https://www.kernel.org/pub/software/scm/git/git-2.7.3.tar.gz
+    echo '30d067499b61caddedaf1a407b4947244f14d10842d100f7c7c6ea1c288280cd  git-2.7.3.tar.gz' | shasum -a256 -c - && tar -xzf git-2.7.3.tar.gz
+    cd git-2.7.3/
     ./configure
     make prefix=/usr/local all
 
@@ -143,7 +144,7 @@ use 64-bit Linux. You can find downloads for other platforms at the [Go download
 page](https://golang.org/dl).
 
     curl -O --progress https://storage.googleapis.com/golang/go1.5.3.linux-amd64.tar.gz
-    echo '43afe0c5017e502630b1aea4d44b8a7f059bf60d7f29dfd58db454d4e4e0ae53  go1.5.3.linux-amd64.tar.gz' | shasum -c - && \
+    echo '43afe0c5017e502630b1aea4d44b8a7f059bf60d7f29dfd58db454d4e4e0ae53  go1.5.3.linux-amd64.tar.gz' | shasum -a256 -c - && \
       sudo tar -C /usr/local -xzf go1.5.3.linux-amd64.tar.gz
     sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/
     rm go1.5.3.linux-amd64.tar.gz
@@ -160,19 +161,12 @@ We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](da
 
     # Install the database packages
     sudo apt-get install -y postgresql postgresql-client libpq-dev
-
-    # Login to PostgreSQL
-    sudo -u postgres psql -d template1
-
+    
     # Create a user for GitLab
-    # Do not type the 'template1=#', this is part of the prompt
-    template1=# CREATE USER git CREATEDB;
+    sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"
 
     # Create the GitLab production database & grant all privileges on database
-    template1=# CREATE DATABASE gitlabhq_production OWNER git;
-
-    # Quit the database session
-    template1=# \q
+    sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
 
     # Try connecting to the new database with the new user
     sudo -u git -H psql -d gitlabhq_production
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index d59b7f0e84d..03cb08dd1f1 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -22,7 +22,7 @@ For the installations options please see [the installation page on the GitLab we
 - FreeBSD
 
 On the above unsupported distributions is still possible to install GitLab yourself.
-Please see the [installation from source guide](https://github.com/gitlabhq/gitlabhq/blob/master/doc/install/installation.md) and the [unofficial installation guides](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Unofficial-Installation-Guides) on the public wiki for more information.
+Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information.
 
 ### Non-Unix operating systems such as Windows
 
diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md
new file mode 100644
index 00000000000..e5247082a89
--- /dev/null
+++ b/doc/integration/auth0.md
@@ -0,0 +1,89 @@
+# Auth0 OmniAuth Provider
+
+To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an
+application.
+
+1. Sign in to the [Auth0 Console](https://manage.auth0.com). If you need to
+create an account, you can do so at the same link.
+
+1. Select "New App/API".
+
+1. Provide the Application Name ('GitLab' works fine).
+
+1. Once created, you should see the Quick Start options. Disregard them and
+select 'Settings' above the Quick Start options.
+
+1. At the top of the Settings screen, you should see your Domain, Client ID and
+Client Secret. Take note of these as you'll need to put them in the
+configuration file. For example:
+    - Domain: `test1234.auth0.com`
+    - Client ID: `t6X8L2465bNePWLOvt9yi41i`
+    - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2`
+
+1. Fill in the Allowed Callback URLs:
+    - http://`YOUR_GITLAB_URL`/users/auth/auth0/callback (or)
+    - https://`YOUR_GITLAB_URL`/users/auth/auth0/callback
+
+1. Fill in the Allowed Origins (CORS):
+    - http://`YOUR_GITLAB_URL` (or)
+    - https://`YOUR_GITLAB_URL`
+
+1. On your GitLab server, open the configuration file.
+
+    For omnibus package:
+
+    ```sh
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For installations from source:
+
+    ```sh
+      cd /home/git/gitlab
+      sudo -u git -H editor config/gitlab.yml
+    ```
+
+1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+for initial settings.
+
+1. Add the provider configuration:
+
+    For omnibus package:
+
+    ```ruby
+      gitlab_rails['omniauth_providers'] = [
+        {
+          "name" => "auth0",
+          "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID'',
+                      client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
+                      namespace: 'YOUR_AUTH0_DOMAIN'
+                    }
+        }
+      ]
+    ```
+
+    For installations from source:
+
+    ```yaml
+      - { name: 'auth0',
+          args: {
+            client_id: 'YOUR_AUTH0_CLIENT_ID',
+            client_secret: 'YOUR_AUTH0_CLIENT_SECRET',
+            namespace: 'YOUR_AUTH0_DOMAIN'
+            }
+        }
+    ```
+
+1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page
+from step 5.
+
+1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console
+page from step 5.
+
+1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md)
+for the changes to take effect.
+
+On the sign in page there should now be an Auth0 icon below the regular sign in
+form. Click the icon to begin the authentication process. Auth0 will ask the
+user to sign in and authorize the GitLab application. If everything goes well
+the user will be returned to GitLab and will be signed in.
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index ba47cb16265..25f35988305 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -28,6 +28,7 @@ contains some settings that are common for all providers.
 - [SAML](saml.md)
 - [Crowd](crowd.md)
 - [Azure](azure.md)
+- [Auth0](auth0.md)
 
 ## Initial OmniAuth Configuration