Move document on CI build permissions to new location

3 files changed, 16 insertions, 16 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index a52277e582a..cce77c655b6 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -20,3 +20,4 @@
 - [Access dependent projects](dependent_projects/README.md)
 - [API](../api/ci/README.md)
 - [CI services (linked docker containers)](services/README.md)
+- [**New CI build permissions model**](../user/project/new_ci_build_permissions_model.md)
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index d1156127a00..76e7a100545 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -143,13 +143,11 @@ instance and project. In addition, all admins can use the admin interface under
 
 > Changed in GitLab 8.12.
 
-GitLab 8.12 has completely redesigned build permission system.
-You can find all discussion and all our concerns when choosing the current approach:
-https://gitlab.com/gitlab-org/gitlab-ce/issues/18994
+GitLab 8.12 has a completely redesigned build permission system.
+Read all about the [new model and its implications][new-mod].
 
-### Build privileges
-
-This table shows granted privileges for builds triggered by specific types of users:
+This table shows granted privileges for builds triggered by specific types of
+users:
 
 | Action                                      | Guest, Reporter | Developer   | Master   | Admin  |
 |---------------------------------------------|-----------------|-------------|----------|--------|
@@ -168,4 +166,5 @@ This table shows granted privileges for builds triggered by specific types of us
 
 [^3]: Only if user is not external one.
 [^4]: Only if user is a member of the project.
-
+[ce-18994]: https://gitlab.com/gitlab-org/gitlab-ce/issues/18994
+[new-mod]: project/new_ci_build_permissions_model.md
diff --git a/doc/ci/dependent_projects/README.md b/doc/user/project/new_ci_build_permissions_model.md
index 3e91f82e2d4..29677fee421 100644
--- a/doc/ci/dependent_projects/README.md
+++ b/doc/user/project/new_ci_build_permissions_model.md
@@ -1,8 +1,8 @@
-# New CI build permission model
+# New CI build permissions model
 
 > Introduced in GitLab 8.12.
 
-GitLab 8.12 has a completely redesigned build permission system. You can find
+GitLab 8.12 has a completely redesigned [build permissions] system. You can find
 all discussion and all our concerns when choosing the current approach in issue
 [#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994).
 
@@ -107,13 +107,12 @@ to checkout project sources.
 The project's Runner's token was a token that you could find under the
 project's **Settings > CI/CD Pipelines** and was limited to access only that
 project.
+It could be used for registering new specific Runners assigned to the project
+and to checkout project sources.
+It could also be used with the GitLab Container Registry for that project,
+allowing pulling and pushing Docker images from within the CI build.
 
-The project's Runner's token was used for registering new specific Runners
-assigned to project and to checkout project sources.
-
-The project Runners token could also be used with the GitLab Container Registry
-for that project, allowing pulling and pushing Docker images from within the
-CI build.
+---
 
 GitLab would create a special checkout URL like:
 
@@ -128,7 +127,7 @@ commands to interact with GitLab Container Registry. For example:
 docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com
 ```
 
-Using single token had multiple security implications
+Using single token had multiple security implications:
 
 - The token would be readable to anyone who had developer access to a project
   that could run CI builds, allowing the developer to register any specific
@@ -279,3 +278,4 @@ test:
 ```
 
 [git-scm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[build permissions]: ../permissions.md#builds-permissions