From 9f14acfb767180afe79c2a7dc37543d2aa5a3063 Mon Sep 17 00:00:00 2001
From: Christian Godenschwager <christian.godenschwager@fau.de>
Date: Thu, 2 Feb 2017 13:54:07 +0000
Subject: [PATCH] Added documentation for permalinks to most recent build
 artifacts

- Documented how to download single files from most recent artifacts
- Documented how to browse most recent artifacts
---
 changelogs/unreleased/artifactsdoc.yml      |  4 +++
 doc/user/project/pipelines/job_artifacts.md | 31 +++++++++++++++++++--
 2 files changed, 32 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/unreleased/artifactsdoc.yml

diff --git a/changelogs/unreleased/artifactsdoc.yml b/changelogs/unreleased/artifactsdoc.yml
new file mode 100644
index 00000000000..4ef32d5256f
--- /dev/null
+++ b/changelogs/unreleased/artifactsdoc.yml
@@ -0,0 +1,4 @@
+---
+title: Added documentation for permalinks to most recent build artifacts.
+merge_request: 8934
+author: Christian Godenschwager
diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md
index f85f4bf8e1e..5ce99843301 100644
--- a/doc/user/project/pipelines/job_artifacts.md
+++ b/doc/user/project/pipelines/job_artifacts.md
@@ -90,18 +90,43 @@ inside GitLab that make that possible.
 It is possible to download the latest artifacts of a job via a well known URL
 so you can use it for scripting purposes.
 
-The structure of the URL is the following:
+The structure of the URL to download the whole artifacts archive is the following:
 
 ```
 https://example.com/<namespace>/<project>/builds/artifacts/<ref>/download?job=<job_name>
 ```
 
-For example, to download the latest artifacts of the job named `rspec 6 20` of
+To download a single file from the artifacts use the following URL:
+
+```
+https://example.com/<namespace>/<project>/builds/artifacts/<ref>/file/<path_to_file>?job=<job_name>
+```
+
+For example, to download the latest artifacts of the job named `coverage` of
 the `master` branch of the `gitlab-ce` project that belongs to the `gitlab-org`
 namespace, the URL would be:
 
 ```
-https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/download?job=rspec+6+20
+https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/download?job=coverage
+```
+
+To download the file `coverage/index.html` from the same
+artifacts use the following URL:
+
+```
+https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/file/coverage/index.html?job=coverage
+```
+
+There is also a URL to browse the latest job artifacts:
+
+```
+https://example.com/<namespace>/<project>/builds/artifacts/<ref>/browse?job=<job_name>
+```
+
+For example:
+
+```
+https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/browse?job=coverage
 ```
 
 The latest builds are also exposed in the UI in various places. Specifically,