Add more info on artifacts expiry datedocs/expiring-artifacts

2 files changed, 53 insertions, 9 deletions

diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md
index 7b0610ae414..5599435564e 100644
--- a/doc/administration/job_artifacts.md
+++ b/doc/administration/job_artifacts.md
@@ -82,6 +82,42 @@ _The artifacts are stored by default in
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
+## Expiring artifacts
+
+If an expiry date is used for the artifacts, they are marked for deletion
+right after that date passes. Artifacts are cleaned up by the
+`expire_build_artifacts_worker` cron job which is run by Sidekiq every hour at
+50 minutes (`50 * * * *`).
+
+To change the default schedule on which the artifacts are expired, follow the
+steps below.
+
+---
+
+**In Omnibus installations:**
+
+1. Edit `/etc/gitlab/gitlab.rb` and comment out or add the following line
+
+    ```ruby
+    gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *"
+    ```
+
+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
+    expire_build_artifacts_worker:
+      cron: "50 * * * *"
+    ```
+
+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
diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md
index 151ee4728ad..c4475d9866b 100644
--- a/doc/user/project/pipelines/job_artifacts.md
+++ b/doc/user/project/pipelines/job_artifacts.md
@@ -12,7 +12,7 @@
    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/job_artifacts.md](../../../administration/job_artifacts.md).
+   [administration/job_artifacts](../../../administration/job_artifacts.md).
 
 Artifacts is a list of files and directories which are attached to a job
 after it completes successfully. This feature is enabled by default in all
@@ -29,25 +29,31 @@ pdf:
   artifacts:
     paths:
     - mycv.pdf
+    expire_in: 1 week
 ```
 
 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.
+are relative to the repository that was cloned during the build. These uploaded
+artifacts will be kept in GitLab for 1 week as defined by the `expire_in`
+definition. You have the option to keep the artifacts from expiring via the
+[web interface](#browsing-job-artifacts). If you don't define an expiry date,
+the artifacts will be kept forever.
 
-For more examples on artifacts, follow the artifacts reference in
-[`.gitlab-ci.yml` documentation](../../../ci/yaml/README.md#artifacts).
+For more examples on artifacts, follow the [artifacts reference in
+`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts).
 
 ## Browsing job artifacts
 
 >**Note:**
-With GitLab 9.2, PDFs, images, videos and other formats can be previewed directly
-in the job artifacts browser without the need to download them.
+With GitLab 9.2, PDFs, images, videos and other formats can be previewed
+directly in the job artifacts browser without the need to download them.
 
-After a job finishes, if you visit the job'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.
+After a job finishes, if you visit the job's specific page, there are three
+buttons. You can download the artifacts archive or browse its contents, whereas
+the **Keep** button appears only if you have set an [expiry date] to the
+artifacts in case you changed your mind and want to keep them.
 
 ![Job artifacts browser button](img/job_artifacts_browser_button.png)
 
@@ -145,3 +151,5 @@ information in the UI.
 
 ![Latest artifacts button](img/job_latest_artifacts_browser.png)
 
+
+[expiry date]: ../../../ci/yaml/README.md#artifacts-expire_in