From a0fefc2ad22ed2392bcba5acb02a0a95b73cbba8 Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Tue, 14 Jun 2016 17:58:20 -0700 Subject: Add definitions and tweak some docs. Partially fixes #17733 --- doc/ci/README.md | 1 + doc/ci/definitions/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++ doc/ci/quick_start/README.md | 24 ++++++++++---------- doc/ci/yaml/README.md | 4 ++-- 4 files changed, 67 insertions(+), 14 deletions(-) create mode 100644 doc/ci/definitions/README.md (limited to 'doc/ci') 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. -- cgit v1.2.1 From a1c2b168377869da8f3393c9a8f18a85633c3d57 Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Tue, 14 Jun 2016 18:12:39 -0700 Subject: Add pipeline image --- doc/ci/quick_start/README.md | 42 +++++++++++++++------------- doc/ci/quick_start/img/pipelines_status.png | Bin 0 -> 89387 bytes 2 files changed, 23 insertions(+), 19 deletions(-) create mode 100644 doc/ci/quick_start/img/pipelines_status.png (limited to 'doc/ci') diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 07fbefa0416..c32b69aad8b 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -9,8 +9,9 @@ GitLab offers a [continuous integration][ci] service. If you and configure your GitLab project to use a [Runner], then each merge request or push triggers your CI [pipeline]. -The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it -runs a pipeline with three [stages]: `build`, `test`, and `deploy`. +The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs +a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to +use all three stages; stages with no jobs are simply ignored. 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 @@ -56,15 +57,14 @@ On any push to your repository, GitLab will look for the `.gitlab-ci.yml` file and start builds on _Runners_ according to the contents of the file, for that commit. -Because `.gitlab-ci.yml` is in the repository, it is version controlled, -old versions still build successfully, forks can easily make use of CI, -branches can have separate builds and you have a single source of truth for CI. -You can read more about the reasons why we are using `.gitlab-ci.yml` -[in our blog about it][blog-ci]. +Because `.gitlab-ci.yml` is in the repository and is version controlled, old +versions still build successfully, forks can easily make use of CI, branches can +have different pipelines and jobs, and you have a single source of truth for CI. +You can read more about the reasons why we are using `.gitlab-ci.yml` [in our +blog about it][blog-ci]. **Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file -so you have to pay extra attention to the indentation. Always use spaces, not -tabs. +so you have to pay extra attention to indentation. Always use spaces, not tabs. ### Creating a simple `.gitlab-ci.yml` file @@ -107,7 +107,7 @@ If you want to check whether your `.gitlab-ci.yml` file is valid, there is a Lint tool under the page `/ci/lint` of your GitLab instance. You can also find the link under **Settings > CI settings** in your project. -For more information and a complete `.gitlab-ci.yml` syntax, please check +For more information and a complete `.gitlab-ci.yml` syntax, please read [the documentation on .gitlab-ci.yml](../yaml/README.md). ### Push `.gitlab-ci.yml` to GitLab @@ -121,7 +121,8 @@ git commit -m "Add .gitlab-ci.yml" git push origin master ``` -Now if you go to the **Builds** page you will see that the builds are pending. +Now if you go to the **Pipelines** page you will see that the pipeline is +pending. You can also go to the **Commits** page and notice the little clock icon next to the commit SHA. @@ -137,15 +138,14 @@ Notice that there are two jobs pending which are named after what we wrote in `.gitlab-ci.yml`. The red triangle indicates that there is no Runner configured yet for these builds. -The next step is to configure a Runner so that it picks the pending jobs. +The next step is to configure a Runner so that it picks the pending builds. ## Configuring a Runner -In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`. -A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker -container or even a cluster of containers. GitLab and the Runners communicate -through an API, so the only needed requirement is that the machine on which the -Runner is configured to have Internet access. +In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`. A Runner +can be a virtual machine, a VPS, a bare-metal machine, a docker container or +even a cluster of containers. GitLab and the Runners communicate through an API, +so the only requirement is that the Runner's machine has Internet access. A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects it's called a _Shared Runner_. @@ -187,12 +187,16 @@ To enable **Shared Runners** you have to go to your project's [Read more on Shared Runners](../runners/README.md). -## Seeing the status of your build +## Seeing the status of your pipeline and builds After configuring the Runner successfully, you should see the status of your last commit change from _pending_ to either _running_, _success_ or _failed_. -You can view all builds, by going to the **Builds** page in your project. +You can view all pipelines by going to the **Pipelines** page in your project. + +![Commit status](img/pipelines_status.png) + +Or you can view all builds, by going to the **Pipelines > Builds** page. ![Commit status](img/builds_status.png) diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png new file mode 100644 index 00000000000..6bc97bb739c Binary files /dev/null and b/doc/ci/quick_start/img/pipelines_status.png differ -- cgit v1.2.1 From edfe2e2db98e1a5541d5d683ac3a686d24a9c429 Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Tue, 14 Jun 2016 20:34:35 -0700 Subject: Add CD --- doc/ci/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/README.md b/doc/ci/README.md index c7a29e269b5..7abce85c8d8 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,6 +1,6 @@ ## GitLab CI Documentation -### CI User documentation +### CI/CD User documentation - [Get started with GitLab CI](quick_start/README.md) - [CI/CD Definitions](definitions/README.md) -- cgit v1.2.1 From 41af86bc86a3bab9c83729ff76776fc137b350ef Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Mon, 20 Jun 2016 15:07:38 -0700 Subject: Move Pipelines and Builds definitions to their own page --- doc/ci/README.md | 4 ++-- doc/ci/definitions/README.md | 52 -------------------------------------------- doc/ci/environments.md | 2 +- 3 files changed, 3 insertions(+), 55 deletions(-) delete mode 100644 doc/ci/definitions/README.md (limited to 'doc/ci') diff --git a/doc/ci/README.md b/doc/ci/README.md index 7abce85c8d8..f8d02af31ab 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,11 +1,11 @@ ## GitLab CI Documentation -### CI/CD User documentation +### 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) +- [Pipelines](pipelines.md) - [Environments and deployments](environments.md) - [Learn how `.gitlab-ci.yml` works](yaml/README.md) - [Configure a Runner, the application that runs your builds](runners/README.md) diff --git a/doc/ci/definitions/README.md b/doc/ci/definitions/README.md deleted file mode 100644 index 4ec5eee5757..00000000000 --- a/doc/ci/definitions/README.md +++ /dev/null @@ -1,52 +0,0 @@ -## 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/environments.md b/doc/ci/environments.md index 040379bb381..d85b8a34ced 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -52,7 +52,7 @@ Clicking on an environment will show the history of deployments. Only deploys that happen after your `.gitlab-ci.yml` is properly configured will show up in the environments and deployments lists. -[Pipelines]: quick_start/README.md +[Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs [environments]: #environments [deployments]: #deployments -- cgit v1.2.1 From a03cadcdbf3024ec59234a07a9b87884de5cc7dc Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Mon, 20 Jun 2016 15:10:11 -0700 Subject: Move Pipelines and Builds definitions to their own page --- doc/ci/pipelines.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 doc/ci/pipelines.md (limited to 'doc/ci') diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md new file mode 100644 index 00000000000..48a9f994759 --- /dev/null +++ b/doc/ci/pipelines.md @@ -0,0 +1,38 @@ +# Introduction to pipelines and builds + +>**Note:** +Introduced in GitLab 8.8. + +## 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 individual runs of [jobs]. Not to be confused with a `build` job or +`build` stage. + +## Defining pipelines + +Pipelines are defined in `.gitlab-ci.yml` by specifying [jobs] that run in +[stages]. + +See full [documentation](yaml/README.md#jobs). + +## Seeing pipeline status + +You can find the current and historical pipeline runs under **Pipelines** for your +project. + +## Seeing build status + +Clicking on a pipeline will show the builds that were run for that pipeline. + +[builds]: #builds +[jobs]: yaml/README.md#jobs +[stages]: yaml/README.md#stages +[runners]: runners/README.md -- cgit v1.2.1 From 0582c085554a8649f3c9daa0dde611e3a851db3e Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Mon, 20 Jun 2016 15:12:04 -0700 Subject: Add 'and builds' --- doc/ci/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/README.md b/doc/ci/README.md index f8d02af31ab..3dd4e2bc230 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -5,7 +5,7 @@ - [Get started with GitLab CI](quick_start/README.md) - [CI examples for various languages](examples/README.md) - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) -- [Pipelines](pipelines.md) +- [Pipelines and builds](pipelines.md) - [Environments and deployments](environments.md) - [Learn how `.gitlab-ci.yml` works](yaml/README.md) - [Configure a Runner, the application that runs your builds](runners/README.md) -- cgit v1.2.1 From 82b32c286ab519b94d6b5d5467b05b43b9b31fc9 Mon Sep 17 00:00:00 2001 From: Mark Pundsack Date: Tue, 21 Jun 2016 22:15:21 -0700 Subject: Fix link --- doc/ci/quick_start/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index c32b69aad8b..7fa1a478f34 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -241,4 +241,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 +[pipeline]: ../pipelines.md -- cgit v1.2.1