Add definitions and tweak some docs. Partially fixes #17733
This commit is contained in:
parent
032e398374
commit
a0fefc2ad2
4 changed files with 67 additions and 14 deletions
|
@ -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)
|
||||
|
|
52
doc/ci/definitions/README.md
Normal file
52
doc/ci/definitions/README.md
Normal file
|
@ -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
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in a new issue