start with runner documenation

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/runners/README.md b/doc/runners/README.md
new file mode 100644
index 0000000..af3c45f
--- /dev/null
+++ b/doc/runners/README.md
@@ -0,0 +1,67 @@
+# Runners
+
+In GitLab CI, Runners run your [jobs](jobs/README.md).
+A runner is an isolated (virtual) machine that gets activated by the coordinator.
+
+A runner can be specific to a certain project or serve any project
+in GitLab CI. A runner that serves all projects is called a shared runner.
+
+## Shared vs. Specific Runners
+
+A runner that is specific only runs for the specified project. A shared runner
+can run jobs for every project that has enable the option
+`Allow shared runners`.
+
+**Shared runners** are useful for jobs that have similar requirements,
+between multiple projects. Rather than having multiple runners idling for
+many projects, you can have a single or a small number of runners that handle
+multiple projects. This makes it easier to maintain and update runners.
+
+**Specific runners** are useful for jobs that have special requirements or for
+projects with a very demand. If a job has certain requirements, you can set
+up the specific runner with this in mind, while not having to do this for all
+runners. For example, if you want to deploy a certain project, you can setup
+a specific runner to have the right credentials for this.
+
+Projects with high demand of CI activity can also benefit from using specific runners.
+By having dedicated runners you are guarenteed that the runner is not being held
+up by another project's jobs.
+
+Specific runners do not get shared with forked projects automatically.
+A fork does copy the CI settings (jobs, allow shared, etc) of the cloned repository.
+
+## Using Shared Runners Effectively
+
+If you are planning to use shared runners, there are several things you
+should keep in consideration.
+
+### Use Tags
+
+You must setup a runner to be able to run all the different types of jobs
+that it may encounter on the projects it's shared over. This would be
+problematic for large amounts of projects, if it wasn't for tags.
+
+By tagging a Runner for the types of jobs it can handle, you can make sure
+shared runners will only run the jobs they are equipped to run.
+
+For instance, at GitLab we have runners tagged with "rails" if they contain
+the appropriate dependencies to run Rails test suites.
+
+### Be Careful with Sensitive Information
+
+If you can run a build on a runner, you can get access to any code it runs
+and get the token of the runner. With shared runners, this means that anyone
+that runs jobs on the runner, can access anyone else's code that runs on the runner.
+
+In addition, because you can get access to the runner token, it is possible
+to create a clone of a runner and submit false builds, for example.
+
+The above is easily avoided by restricting the usage of shared runners
+on large public GitLab instances and controlling access to your GitLab instance.
+
+### Forks
+
+Whenever a project is forked, it copies the settings of the jobs that relate
+to it. This means that if you have shared runners setup for a project and
+someone forks that project, the shared runners will also serve jobs of this
+project.