From 48dbeaa6baf5150fee1082ccac2578831a3539e4 Mon Sep 17 00:00:00 2001
From: Fabio Busatto <fabio@gitlab.com>
Date: Thu, 7 Sep 2017 11:23:02 +0000
Subject: Add Security on protected branches

---
 doc/ci/pipelines.md                    | 24 ++++++++++++++++++++++++
 doc/user/permissions.md                |  8 ++++++++
 doc/user/project/protected_branches.md |  8 ++++++++
 3 files changed, 40 insertions(+)

diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index 5a2b61fb0cb..ac4a9b0ed27 100644
--- a/doc/ci/pipelines.md
+++ b/doc/ci/pipelines.md
@@ -222,6 +222,30 @@ total running time should be:
 Pipeline status and test coverage report badges are available. You can find their
 respective link in the [Pipelines settings] page.
 
+## Security on protected branches
+
+A strict security model is enforced when pipelines are executed on
+[protected branches](../user/project/protected_branches.md).
+
+The following actions are allowed on protected branches only if the user is
+[allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
+on that specific branch:
+- run **manual pipelines** (using Web UI or Pipelines API)
+- run **scheduled pipelines**
+- run pipelines using **triggers**
+- trigger **manual actions** on existing pipelines
+- **retry/cancel** existing jobs (using Web UI or Pipelines API)
+
+**Secret variables** marked as **protected** are accessible only to jobs that
+run on protected branches, avoiding untrusted users to get unintended access to
+sensitive information like deployment credentials and tokens.
+
+**Runners** marked as **protected** can run jobs only on protected
+branches, avoiding untrusted code to be executed on the protected runner and
+preserving deployment keys and other credentials from being unintentionally
+accessed. In order to ensure that jobs intended to be executed on protected
+runners will not use regular runners, they must be tagged accordingly.
+
 [jobs]: #jobs
 [jobs-yaml]: yaml/README.md#jobs
 [manual]: yaml/README.md#manual
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index bd0a58c4cca..0c17905aa8c 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -230,6 +230,14 @@ users:
 GitLab 8.12 has a completely redesigned job permissions system. To learn more,
 read through the documentation on the [new CI/CD permissions model](project/new_ci_build_permissions_model.md#new-ci-job-permissions-model).
 
+## Running pipelines on protected branches
+
+The permission to merge or push to protected branches is used to define if a user can
+run CI/CD pipelines and execute actions on jobs that are related to those branches.
+
+See [Security on protected branches](../ci/pipelines.md#security-on-protected-branches)
+for details about the pipelines security model.
+
 ## LDAP users permissions
 
 Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user.
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 0570d9f471f..0cbb0c878c2 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -115,6 +115,14 @@ Deleting a protected branch is only allowed via the web interface, not via Git.
 This means that you can't accidentally delete a protected branch from your
 command line or a Git client application.
 
+## Running pipelines on protected branches
+
+The permission to merge or push to protected branches is used to define if a user can
+run CI/CD pipelines and execute actions on jobs that are related to those branches.
+
+See [Security on protected branches](../../ci/pipelines.md#security-on-protected-branches)
+for details about the pipelines security model.
+
 ## Changelog
 
 **9.2**
-- 
cgit v1.2.3