Merge branch 'master' into 18256-secret-token-docs

17 files changed, 402 insertions, 187 deletions

diff --git a/doc/README.md b/doc/README.md
index d28ad499d3a..fc51ea911b9 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -54,7 +54,5 @@
 
 ## Contributor documentation
 
-- [Documentation styleguide](development/doc_styleguide.md) Use this styleguide if you are
-  contributing to documentation.
-- [Development](development/README.md) Explains the architecture and the guidelines for shell commands.
+- [Development](development/README.md) All styleguides and explanations how to contribute.
 - [Legal](legal/README.md) Contributor license agreements.
diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md
new file mode 100644
index 00000000000..64353f7282b
--- /dev/null
+++ b/doc/administration/build_artifacts.md
@@ -0,0 +1,90 @@
+# Build artifacts administration
+
+>**Notes:**
+>- Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
+>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
+   changed to `ZIP`.
+>- This is the administration documentation. For the user guide see
+   [user/project/builds/artifacts.md](../user/project/builds/artifacts.md).
+
+Artifacts is a list of files and directories which are attached to a build
+after it completes successfully. This feature is enabled by default in all
+GitLab installations. Keep reading if you want to know how to disable it.
+
+## Disabling build artifacts
+
+To disable artifacts site-wide, follow the steps below.
+
+---
+
+**In Omnibus installations:**
+
+1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
+
+    ```ruby
+    gitlab_rails['artifacts_enabled'] = false
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**In installations from source:**
+
+1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
+
+    ```yaml
+    artifacts:
+      enabled: false
+    ```
+
+1. Save the file and [restart GitLab][] for the changes to take effect.
+
+## Storing build artifacts
+
+After a successful build, GitLab Runner uploads an archive containing the build
+artifacts to GitLab.
+
+To change the location where the artifacts are stored, follow the steps below.
+
+---
+
+**In Omnibus installations:**
+
+_The artifacts are stored by default in
+`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
+
+1. To change the storage path for example to `/mnt/storage/artifacts`, edit
+   `/etc/gitlab/gitlab.rb` and add the following line:
+
+    ```ruby
+    gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**In installations from source:**
+
+_The artifacts are stored by default in
+`/home/git/gitlab/shared/artifacts`._
+
+1. To change the storage path for example to `/mnt/storage/artifacts`, edit
+   `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
+
+    ```yaml
+    artifacts:
+      enabled: true
+      path: /mnt/storage/artifacts
+    ```
+
+1. Save the file and [restart GitLab][] for the changes to take effect.
+
+## Set the maximum file size of the artifacts
+
+Provided the artifacts are enabled, you can change the maximum file size of the
+artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration#maximum-artifacts-size).
+
+[reconfigure gitlab]: restart_gitlab.md "How to restart GitLab"
+[restart gitlab]: restart_gitlab.md "How to restart GitLab"
diff --git a/doc/ci/README.md b/doc/ci/README.md
index 0833027f91d..10ce4ac8940 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -14,7 +14,7 @@
 - [Use variables in your `.gitlab-ci.yml`](variables/README.md)
 - [Use SSH keys in your build environment](ssh_keys/README.md)
 - [Trigger builds through the API](triggers/README.md)
-- [Build artifacts](build_artifacts/README.md)
+- [Build artifacts](../user/project/builds/artifacts.md)
 - [User permissions](../user/permissions.md#gitlab-ci)
 - [API](../api/ci/README.md)
 - [CI services (linked docker containers)](services/README.md)
diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md
index 9553bb11e9d..05605f10fb4 100644
--- a/doc/ci/build_artifacts/README.md
+++ b/doc/ci/build_artifacts/README.md
@@ -1,175 +1,4 @@
-# Introduction to build artifacts
+This document was moved to:
 
-Artifacts is a list of files and directories which are attached to a build
-after it completes successfully.  This feature is enabled by default in all GitLab installations.
-
-_If you are searching for ways to use artifacts, jump to
-[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._
-
-Since GitLab 8.2 and [GitLab Runner] 0.7.0, build artifacts that are created by
-GitLab Runner are uploaded to GitLab and are downloadable as a single archive
-(`tar.gz`) using the GitLab UI.
-
-Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
-changed to `ZIP`, and it is now possible to browse its contents, with the added
-ability of downloading the files separately.
-
-**Note:**
-The artifacts browser will be available only for new artifacts that are sent
-to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
-browse old artifacts already uploaded to GitLab.
-
-## Disabling build artifacts
-
-To disable artifacts site-wide, follow the steps below.
-
----
-
-**In Omnibus installations:**
-
-1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
-
-    ```ruby
-    gitlab_rails['artifacts_enabled'] = false
-    ```
-
-1. Save the file and [reconfigure GitLab][] for the changes to take effect.
-
----
-
-**In installations from source:**
-
-1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
-
-    ```yaml
-    artifacts:
-      enabled: false
-    ```
-
-1. Save the file and [restart GitLab][] for the changes to take effect.
-
-## Defining artifacts in `.gitlab-ci.yml`
-
-A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
-the following:
-
-```yaml
-pdf:
-  script: xelatex mycv.tex
-  artifacts:
-    paths:
-    - mycv.pdf
-```
-
-A job named `pdf` calls the `xelatex` command in order to build a pdf file from
-the latex source file `mycv.tex`. We then define the `artifacts` paths which in
-turn are defined with the `paths` keyword. All paths to files and directories
-are relative to the repository that was cloned during the build.
-
-For more examples on artifacts, follow the
-[separate artifacts yaml documentation](../yaml/README.md#artifacts).
-
-## Storing build artifacts
-
-After a successful build, GitLab Runner uploads an archive containing the build
-artifacts to GitLab.
-
-To change the location where the artifacts are stored, follow the steps below.
-
----
-
-**In Omnibus installations:**
-
-_The artifacts are stored by default in
-`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
-
-1. To change the storage path for example to `/mnt/storage/artifacts`, edit
-   `/etc/gitlab/gitlab.rb` and add the following line:
-
-    ```ruby
-    gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
-    ```
-
-1. Save the file and [reconfigure GitLab][] for the changes to take effect.
-
----
-
-**In installations from source:**
-
-_The artifacts are stored by default in
-`/home/git/gitlab/shared/artifacts`._
-
-1. To change the storage path for example to `/mnt/storage/artifacts`, edit
-   `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
-
-    ```yaml
-    artifacts:
-      enabled: true
-      path: /mnt/storage/artifacts
-    ```
-
-1. Save the file and [restart GitLab][] for the changes to take effect.
-
-## Browsing build artifacts
-
-When GitLab receives an artifacts archive, an archive metadata file is also
-generated. This metadata file describes all the entries that are located in the
-artifacts archive itself. The metadata file is in a binary format, with
-additional GZIP compression.
-
-GitLab does not extract the artifacts archive in order to save space, memory
-and disk I/O. It instead inspects the metadata file which contains all the
-relevant information. This is especially important when there is a lot of
-artifacts, or an archive is a very large file.
-
----
-
-After a successful build, if you visit the build's specific page, you can see
-that there are two buttons.
-
-One is for downloading the artifacts archive and the other for browsing its
-contents.
-
-![Build artifacts browser button](img/build_artifacts_browser_button.png)
-
----
-
-The archive browser shows the name and the actual file size of each file in the
-archive. If your artifacts contained directories, then you are also able to
-browse inside them.
-
-Below you can see an image of three different file formats, as well as two
-directories.
-
-![Build artifacts browser](img/build_artifacts_browser.png)
-
----
-
-## Downloading build artifacts
-
-If you need to download the whole archive, there are buttons in various places
-inside GitLab that make that possible.
-
-1. While on the builds page, you can see the download icon for each build's
-   artifacts archive in the right corner
-
-1. While inside a specific build, you are presented with a download button
-   along with the one that browses the archive
-
-1. And finally, when browsing an archive you can see the download button at
-   the top right corner
-
----
-
-Note that GitLab does not extract the entire artifacts archive to send just a
-single file to the user.
-
-When clicking on a specific file, [GitLab Workhorse] extracts it from the
-archive and the download begins.
-
-This implementation saves space, memory and disk I/O.
-
-[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner "GitLab Runner repository"
-[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
-[restart gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
-[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
+- [user/project/builds/artifacts.md](../../user/project/builds/artifacts.md) - user guide
+- [administration/build_artifacts.md](../../administration/build_artifacts.md) - administrator guide
diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser.png b/doc/ci/build_artifacts/img/build_artifacts_browser.png
deleted file mode 100644
index 59cf2b8746b..00000000000
--- a/doc/ci/build_artifacts/img/build_artifacts_browser.png
+++ /dev/null
diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser_button.png b/doc/ci/build_artifacts/img/build_artifacts_browser_button.png
deleted file mode 100644
index 7801c2e6fa6..00000000000
--- a/doc/ci/build_artifacts/img/build_artifacts_browser_button.png
+++ /dev/null
diff --git a/doc/development/README.md b/doc/development/README.md
index c5d5af43864..7b5f7ff8ad3 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -1,18 +1,38 @@
 # Development
 
+## Outside of docs
+
+- [CONTRIBUTING.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md) main contributing guide
+- [PROCESS.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md) contributing process
+- [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit) to install a development version
+
+## Styleguides
+
+- [Documentation styleguide](development/doc_styleguide.md) Use this styleguide if you are
+  contributing to documentation.
+- [Migration Style Guide](migration_style_guide.md) for creating safe migrations
+- [Testing standards and style guidelines](testing.md)
+- [UI guide](ui_guide.md) for building GitLab with existing css styles and elements
+- [SQL guidelines](sql.md) for SQL guidelines
+
+
+## Process
+
+- [Code review guidelines](code_review.md) for reviewing code and having code reviewed.
+
+## Backend howtos
+
 - [Architecture](architecture.md) of GitLab
 - [CI setup](ci_setup.md) for testing GitLab
-- [Code review guidelines](code_review.md) for reviewing code and having code
-  reviewed.
 - [Gotchas](gotchas.md) to avoid
 - [How to dump production data to staging](db_dump.md)
 - [Instrumentation](instrumentation.md)
-- [Licensing](licensing.md) for ensuring license compliance
-- [Migration Style Guide](migration_style_guide.md) for creating safe migrations
 - [Performance guidelines](performance.md)
 - [Rake tasks](rake_tasks.md) for development
 - [Shell commands](shell_commands.md) in the GitLab codebase
 - [Sidekiq debugging](sidekiq_debugging.md)
-- [SQL guidelines](sql.md) for SQL guidelines
-- [Testing standards and style guidelines](testing.md)
-- [UI guide](ui_guide.md) for building GitLab with existing css styles and elements
+- [What requires downtime?](what_requires_downtime.md)
+
+## Compliance
+
+- [Licensing](licensing.md) for ensuring license compliance
diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md
index 9d7fe7440d2..159d5ce286d 100644
--- a/doc/development/gotchas.md
+++ b/doc/development/gotchas.md
@@ -41,10 +41,10 @@ Rubocop](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/.rubocop.yml#L9
 
 [Exception]: http://stackoverflow.com/q/10048173/223897
 
-## Don't use inline CoffeeScript in views
+## Don't use inline CoffeeScript/JavaScript in views
 
 Using the inline `:coffee` or `:coffeescript` Haml filters comes with a
-performance overhead.
+performance overhead. Using inline JavaScript is not a good way to structure your code and should be avoided.
 
 _**Note:** We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/hamlit.rb)
 in an initializer._
@@ -52,6 +52,7 @@ in an initializer._
 ### Further reading
 
 - Pull Request: [Replace CoffeeScript block into JavaScript in Views](https://git.io/vztMu)
+- Stack Overflow: [Why you should not write inline JavaScript](http://programmers.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting)
 - Stack Overflow: [Performance implications of using :coffescript filter inside HAML templates?](http://stackoverflow.com/a/17571242/223897)
 
 ## ID-based CSS selectors need to be a bit more specific
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md
new file mode 100644
index 00000000000..abd693cf72d
--- /dev/null
+++ b/doc/development/what_requires_downtime.md
@@ -0,0 +1,153 @@
+# What requires downtime?
+
+When working with a database certain operations can be performed without taking
+GitLab offline, others do require a downtime period. This guide describes
+various operations and their impact.
+
+## Adding Columns
+
+On PostgreSQL you can safely add a new column to an existing table as long as it
+does **not** have a default value. For example, this query would not require
+downtime:
+
+```sql
+ALTER TABLE projects ADD COLUMN random_value int;
+```
+
+Add a column _with_ a default however does require downtime. For example,
+consider this query:
+
+```sql
+ALTER TABLE projects ADD COLUMN random_value int DEFAULT 42;
+```
+
+This requires updating every single row in the `projects` table so that
+`random_value` is set to `42` by default. This requires updating all rows and
+indexes in a table. This in turn acquires enough locks on the table for it to
+effectively block any other queries.
+
+As of MySQL 5.6 adding a column to a table is still quite an expensive
+operation, even when using `ALGORITHM=INPLACE` and `LOCK=NONE`. This means
+downtime _may_ be required when modifying large tables as otherwise the
+operation could potentially take hours to complete.
+
+## Dropping Columns
+
+On PostgreSQL you can safely remove an existing column without the need for
+downtime. When you drop a column in PostgreSQL it's not immediately removed,
+instead it is simply disabled. The data is removed on the next vacuum run.
+
+On MySQL this operation requires downtime.
+
+While database wise dropping a column may be fine on PostgreSQL this operation
+still requires downtime because the application code may still be using the
+column that was removed. For example, consider the following migration:
+
+```ruby
+class MyMigration < ActiveRecord::Migration
+  def change
+    remove_column :projects, :dummy
+  end
+end
+```
+
+Now imagine that the GitLab instance is running and actively uses the `dummy`
+column. If we were to run the migration this would result in the GitLab instance
+producing errors whenever it tries to use the `dummy` column.
+
+As a result of the above downtime _is_ required when removing a column, even
+when using PostgreSQL.
+
+## Changing Column Constraints
+
+Generally changing column constraints requires checking all rows in the table to
+see if they meet the new constraint, unless a constraint is _removed_. For
+example, changing a column that previously allowed NULL values to not allow NULL
+values requires the database to verify all existing rows.
+
+The specific behaviour varies a bit between databases but in general the safest
+approach is to assume changing constraints requires downtime.
+
+## Changing Column Types
+
+This operation requires downtime.
+
+## Adding Indexes
+
+Adding indexes is an expensive process that blocks INSERT and UPDATE queries for
+the duration. When using PostgreSQL one can work arounds this by using the
+`CONCURRENTLY` option:
+
+```sql
+CREATE INDEX CONCURRENTLY index_name ON projects (column_name);
+```
+
+Migrations can take advantage of this by using the method
+`add_concurrent_index`. For example:
+
+```ruby
+class MyMigration < ActiveRecord::Migration
+  def change
+    add_concurrent_index :projects, :column_name
+  end
+end
+```
+
+When running this on PostgreSQL the `CONCURRENTLY` option mentioned above is
+used. On MySQL this method produces a regular `CREATE INDEX` query.
+
+MySQL doesn't really have a workaround for this. Supposedly it _can_ create
+indexes without the need for downtime but only for variable width columns. The
+details on this are a bit sketchy. Since it's better to be safe than sorry one
+should assume that adding indexes requires downtime on MySQL.
+
+## Dropping Indexes
+
+Dropping an index does not require downtime on both PostgreSQL and MySQL.
+
+## Adding Tables
+
+This operation is safe as there's no code using the table just yet.
+
+## Dropping Tables
+
+This operation requires downtime as application code may still be using the
+table.
+
+## Adding Foreign Keys
+
+Adding foreign keys acquires an exclusive lock on both the source and target
+tables in PostgreSQL. This requires downtime as otherwise the entire application
+grinds to a halt for the duration of the operation.
+
+On MySQL this operation also requires downtime _unless_ foreign key checks are
+disabled. Because this means checks aren't enforced this is not ideal, as such
+one should assume MySQL also requires downtime.
+
+## Removing Foreign Keys
+
+This operation should not require downtime on both PostgreSQL and MySQL.
+
+## Updating Data
+
+Updating data should generally be safe. The exception to this is data that's
+being migrated from one version to another while the application still produces
+data in the old version.
+
+For example, imagine the application writes the string `'dog'` to a column but
+it really is meant to write `'cat'` instead. One might think that the following
+migration is all that is needed to solve this problem:
+
+```ruby
+class MyMigration < ActiveRecord::Migration
+  def up
+    execute("UPDATE some_table SET column = 'cat' WHERE column = 'dog';")
+  end
+end
+```
+
+Unfortunately this is not enough. Because the application is still running and
+using the old value this may result in the table still containing rows where
+`column` is set to `dog`, even after the migration finished.
+
+In these cases downtime _is_ required, even for rarely updated tables.
diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md
new file mode 100644
index 00000000000..34e2e557f89
--- /dev/null
+++ b/doc/user/admin_area/settings/continuous_integration.md
@@ -0,0 +1,20 @@
+# Continuous integration Admin settings
+
+## Maximum artifacts size
+
+The maximum size of the [build artifacts][art-yml] can be set in the Admin area
+of your GitLab instance. The value is in MB and the default is 100MB. Note that
+this setting is set for each build.
+
+1. Go to **Admin area > Settings** (`/admin/application_settings`).
+
+    ![Admin area settings button](img/admin_area_settings_button.png)
+
+1. Change the value of the maximum artifacts size (in MB):
+
+    ![Admin area maximum artifacts size](img/admin_area_maximum_artifacts_size.png)
+
+1. Hit **Save** for the changes to take effect.
+
+
+[art-yml]: ../../../administration/build_artifacts.md
diff --git a/doc/user/admin_area/settings/img/admin_area_maximum_artifacts_size.png b/doc/user/admin_area/settings/img/admin_area_maximum_artifacts_size.png
new file mode 100644
index 00000000000..53f7e76033e
--- /dev/null
+++ b/doc/user/admin_area/settings/img/admin_area_maximum_artifacts_size.png
diff --git a/doc/user/admin_area/settings/img/admin_area_settings_button.png b/doc/user/admin_area/settings/img/admin_area_settings_button.png
new file mode 100644
index 00000000000..509708b627f
--- /dev/null
+++ b/doc/user/admin_area/settings/img/admin_area_settings_button.png
diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md
new file mode 100644
index 00000000000..c93ae1c369c
--- /dev/null
+++ b/doc/user/project/builds/artifacts.md
@@ -0,0 +1,104 @@
+# Introduction to build artifacts
+
+>**Notes:**
+>- Since GitLab 8.2 and GitLab Runner 0.7.0, build artifacts that are created by
+   GitLab Runner are uploaded to GitLab and are downloadable as a single archive
+   (`tar.gz`) using the GitLab UI.
+>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
+   changed to `ZIP`, and it is now possible to browse its contents, with the added
+   ability of downloading the files separately.
+>- The artifacts browser will be available only for new artifacts that are sent
+   to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
+   browse old artifacts already uploaded to GitLab.
+>- This is the user documentation. For the administration guide see
+   [administration/build_artifacts.md](../../../administration/build_artifacts.md).
+
+Artifacts is a list of files and directories which are attached to a build
+after it completes successfully.  This feature is enabled by default in all GitLab installations.
+
+## Defining artifacts in `.gitlab-ci.yml`
+
+A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
+the following:
+
+```yaml
+pdf:
+  script: xelatex mycv.tex
+  artifacts:
+    paths:
+    - mycv.pdf
+```
+
+A job named `pdf` calls the `xelatex` command in order to build a pdf file from
+the latex source file `mycv.tex`. We then define the `artifacts` paths which in
+turn are defined with the `paths` keyword. All paths to files and directories
+are relative to the repository that was cloned during the build.
+
+For more examples on artifacts, follow the artifacts reference in
+[`.gitlab-ci.yml` documentation](../../../ci/yaml/README.md#artifacts).
+
+## Browsing build artifacts
+
+When GitLab receives an artifacts archive, an archive metadata file is also
+generated. This metadata file describes all the entries that are located in the
+artifacts archive itself. The metadata file is in a binary format, with
+additional GZIP compression.
+
+GitLab does not extract the artifacts archive in order to save space, memory
+and disk I/O. It instead inspects the metadata file which contains all the
+relevant information. This is especially important when there is a lot of
+artifacts, or an archive is a very large file.
+
+---
+
+After a build finishes, if you visit the build's specific page, you can see
+that there are two buttons. One is for downloading the artifacts archive and
+the other for browsing its contents.
+
+![Build artifacts browser button](img/build_artifacts_browser_button.png)
+
+---
+
+The archive browser shows the name and the actual file size of each file in the
+archive. If your artifacts contained directories, then you are also able to
+browse inside them.
+
+Below you can see how browsing looks like. In this case we have browsed inside
+the archive and at this point there is one directory and one HTML file.
+
+![Build artifacts browser](img/build_artifacts_browser.png)
+
+---
+
+## Downloading build artifacts
+
+>**Note:**
+GitLab does not extract the entire artifacts archive to send just a single file
+to the user. When clicking on a specific file, [GitLab Workhorse] extracts it
+from the archive and the download begins. This implementation saves space,
+memory and disk I/O.
+
+If you need to download the whole archive, there are buttons in various places
+inside GitLab that make that possible.
+
+1. While on the pipelines page, you can see the download icon for each build's
+   artifacts archive in the right corner:
+
+    ![Build artifacts in Pipelines page](img/build_artifacts_pipelines_page.png)
+
+1. While on the builds page, you can see the download icon for each build's
+   artifacts archive in the right corner:
+
+    ![Build artifacts in Builds page](img/build_artifacts_builds_page.png)
+
+1. While inside a specific build, you are presented with a download button
+   along with the one that browses the archive:
+
+    ![Build artifacts browser button](img/build_artifacts_browser_button.png)
+
+1. And finally, when browsing an archive you can see the download button at
+   the top right corner:
+
+    ![Build artifacts browser](img/build_artifacts_browser.png)
+
+[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
diff --git a/doc/user/project/builds/img/build_artifacts_browser.png b/doc/user/project/builds/img/build_artifacts_browser.png
new file mode 100644
index 00000000000..d95e2800c0f
--- /dev/null
+++ b/doc/user/project/builds/img/build_artifacts_browser.png
diff --git a/doc/user/project/builds/img/build_artifacts_browser_button.png b/doc/user/project/builds/img/build_artifacts_browser_button.png
new file mode 100644
index 00000000000..463540634e3
--- /dev/null
+++ b/doc/user/project/builds/img/build_artifacts_browser_button.png
diff --git a/doc/user/project/builds/img/build_artifacts_builds_page.png b/doc/user/project/builds/img/build_artifacts_builds_page.png
new file mode 100644
index 00000000000..db78386ba7b
--- /dev/null
+++ b/doc/user/project/builds/img/build_artifacts_builds_page.png
diff --git a/doc/user/project/builds/img/build_artifacts_pipelines_page.png b/doc/user/project/builds/img/build_artifacts_pipelines_page.png
new file mode 100644
index 00000000000..6c2d1a4bdc7
--- /dev/null
+++ b/doc/user/project/builds/img/build_artifacts_pipelines_page.png