Add basic documentation for build artifacts

3 files changed, 52 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index 7d4f84857e0..d75c1fbfe79 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -30,6 +30,7 @@
 - [User permissions](ci/permissions/README.md)
 - [API](ci/api/README.md)
 - [Triggering builds through the API](ci/triggers/README.md)
+- [Build artifacts](ci/artifacts/README.md)
 
 ### CI Languages
 
diff --git a/doc/ci/README.md b/doc/ci/README.md
index 4cdd2e1ad33..19d08721467 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -12,6 +12,7 @@
 * [Using Variables](variables/README.md)
 * [Using SSH keys](ssh_keys/README.md)
 * [Triggering builds through the API](triggers/README.md)
+* [Build artifacts](artifacts/README.md)
 
 ### Languages
 
diff --git a/doc/ci/artifacts/README.md b/doc/ci/artifacts/README.md
new file mode 100644
index 00000000000..1166304f33c
--- /dev/null
+++ b/doc/ci/artifacts/README.md
@@ -0,0 +1,50 @@
+# Build artifacts
+
+Since version 8.2 of GitLab and version 0.7.0 of GitLab Runner, build artifacts
+created by GitLab Runner are uploaded to GitLab, and then you can download
+artifacts archive using GitLab UI.
+
+Since version 8.4 of GitLab and version 1.0 of GitLab Runner artifacts are
+compressed using ZIP format and it is possible to browse content of such an
+archive using GitLab UI, and then download a single file from inside it.
+
+## Artifacts in .gitlab-ci.yml
+
+Please look into `.gitlab-ci.yml` [documentation](../yaml/README.md).
+
+## Artifacts archive format
+
+Prior to version 8.4 of GitLab and 1.0 of GitLab Runner, build artifacts were
+compressed using `tar.gz` format.
+
+Since then, we use a ZIP format.
+
+## How build artifacts are stored
+
+After a successful build, GitLab Runner uploads an archive containing build
+artifacts to GitLab. This archive is not extracted after that, so its save a
+storage space.
+
+## How do we access content of an artifacts archive
+
+When GitLab receives an artifacts archive, archive metadata file is being
+generated. Metadata file describes all entries that are located in artifacts
+archive. This file is in a binary format, with additional GZIP compression.
+
+It is possible then to browse artifacts using GitLab UI and artifacts browser.
+
+TODO IMG
+
+GitLab does not extract artifacts archive to make it possible to browse it. We
+use artifacts metadata file instead that contains are relevant information.
+This is especially important when there is a lot of artifacts, or an archive is
+a very large file.
+
+## How do we make files downloadable
+
+When user clicks a regular file, then download of this particular file starts.
+GitLab does not extract entire artifacts archive to send a single file to user.
+
+Instead of extracting entire file, only one file is being extracted. It is not
+necessary to extract large archive, just to download a small file that is
+inside.