diff --git a/doc/ci/README.md b/doc/ci/README.md index 5a1cb5319c6..c7a29e269b5 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -3,6 +3,7 @@ ### CI User documentation - [Get started with GitLab CI](quick_start/README.md) +- [CI/CD Definitions](definitions/README.md) - [CI examples for various languages](examples/README.md) - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) - [Environments and deployments](environments.md) diff --git a/doc/ci/definitions/README.md b/doc/ci/definitions/README.md new file mode 100644 index 00000000000..4ec5eee5757 --- /dev/null +++ b/doc/ci/definitions/README.md @@ -0,0 +1,52 @@ +## CI/CD Definitions + +### Pipelines + +A pipeline is a group of [builds] that get executed in [stages] (batches). All of +the builds in a stage are executed in parallel (if there are enough concurrent +[runners]), and if they all succeed, the pipeline moves on to the next stage. If +one of the builds fails, the next stage is not (usually) executed. + +### Builds + +Builds are runs of [jobs]. Not to be confused with a `build` stage. + +### Jobs + +Jobs are the basic work unit of CI/CD. Jobs are used to create [builds], which are +then picked up by [Runners] and executed within the environment of the Runner. +Each job is run independently from each other. + +### Runners + +A runner is an isolated (virtual) machine that picks up builds through the +coordinator API of GitLab CI. 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. + +### Stages + +Stages allow [jobs] to be grouped into parallel and sequential [builds]. Builds +of the same stage are executed in parallel and builds of the next stage are run +after the jobs from the previous stage complete successfully. Stages allow for +flexible multi-stage [pipelines]. By default [pipelines] have `build`, `test` +and `deploy` stages, but these can be defined in `.gitlab-ci.yml`. If a job +doesn't specify a stage, the job is assigned to the test stage. + +### Environments + +Environments are places where code gets deployed, such as staging or production. +CI/CD [Pipelines] usually have one or more deploy stages with [jobs] that do +[deployments] to an environment. + +### Deployments + +Deployments are created when [jobs] deploy versions of code to [environments]. + +[pipelines]: #pipelines +[builds]: #builds +[runners]: #runners +[jobs]: #jobs +[stages]: #stages +[environments]: #environments +[deployments]: #deployments diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 386b8e29fcf..07fbefa0416 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -4,41 +4,40 @@ is fully integrated into GitLab itself and is [enabled] by default on all projects. -The TL;DR version of how GitLab CI works is the following. - ---- - GitLab offers a [continuous integration][ci] service. If you [add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, and configure your GitLab project to use a [Runner], then each merge request or -push triggers a build. +push triggers your CI [pipeline]. The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it -runs three [stages]: `build`, `test`, and `deploy`. +runs a pipeline with three [stages]: `build`, `test`, and `deploy`. If everything runs OK (no non-zero return values), you'll get a nice green checkmark associated with the pushed commit or merge request. This makes it -easy to see whether a merge request will cause any of the tests to fail before +easy to see whether a merge request caused any of the tests to fail before you even look at the code. -Most projects only use GitLab's CI service to run the test suite so that +Most projects use GitLab's CI service to run the test suite so that developers get immediate feedback if they broke something. +There's a growing trend to use continuous delivery and continuous deployment to +automatically deploy tested code to staging and production environments. + So in brief, the steps needed to have a working CI can be summed up to: 1. Add `.gitlab-ci.yml` to the root directory of your repository 1. Configure a Runner -From there on, on every push to your Git repository, the build will be -automagically started by the Runner and will appear under the project's -`/builds` page. +From there on, on every push to your Git repository, the Runner will +automagically start the pipeline and the pipeline will appear under the +project's `/pipelines` page. --- This guide assumes that you: - have a working GitLab instance of version 8.0 or higher or are using - [GitLab.com](https://gitlab.com/users/sign_in) + [GitLab.com](https://gitlab.com) - have a project in GitLab that you would like to use CI for Let's break it down to pieces and work on solving the GitLab CI puzzle. @@ -238,3 +237,4 @@ CI with various languages. [runner]: ../runners/README.md [enabled]: ../enable_or_disable_ci.md [stages]: ../yaml/README.md#stages +[pipeline]: ../definitions/README.md#pipelines diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index d0fbcbe9988..b134b5cd5d3 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -54,7 +54,7 @@ of your repository and contains definitions of how your project should be built. The YAML file defines a set of jobs with constraints stating when they should be run. The jobs are defined as top-level elements with a name and always have -to contain the `script` clause: +to contain at least the `script` clause: ```yaml job1: @@ -165,7 +165,7 @@ stages: There are also two edge cases worth mentioning: -1. If no `stages` is defined in `.gitlab-ci.yml`, then by default the `build`, +1. If no `stages` are defined in `.gitlab-ci.yml`, then by default the `build`, `test` and `deploy` are allowed to be used as job's stage by default. 2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.