Merge branch 'add-security-on-protected-branches' into 'master'

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

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.

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**