Skip to content

G
gitlab-ce
Commit a084437b authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
1 Browse files
Options

Rename builds to jobs in docs 

[ci skip]
parent 6038355f
Show whitespace changes
Inline Side-by-side
Showing with 789 additions and 773 deletions
doc/administration/build_artifacts.md
View file @ a084437b
# Build artifacts administration This document was moved to [jobs_artifacts](jobs_artifacts.md).
>**Notes:**
>- Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
changed to `ZIP`.
>- This is the administration documentation. For the user guide see
[user/project/builds/artifacts.md](../user/project/builds/artifacts.md).
Artifacts is a list of files and directories which are attached to a build
after it completes successfully. This feature is enabled by default in all
GitLab installations. Keep reading if you want to know how to disable it.
## Disabling build artifacts
To disable artifacts site-wide, follow the steps below.
---
**In Omnibus installations:**
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
```ruby
gitlab_rails['artifacts_enabled'] = false
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
---
**In installations from source:**
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
```yaml
artifacts:
enabled: false
```
1. Save the file and [restart GitLab][] for the changes to take effect.
## Storing build artifacts
After a successful build, GitLab Runner uploads an archive containing the build
artifacts to GitLab.
To change the location where the artifacts are stored, follow the steps below.
---
**In Omnibus installations:**
_The artifacts are stored by default in
`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/etc/gitlab/gitlab.rb` and add the following line:
```ruby
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
---
**In installations from source:**
_The artifacts are stored by default in
`/home/git/gitlab/shared/artifacts`._
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
```yaml
artifacts:
enabled: true
path: /mnt/storage/artifacts
```
1. Save the file and [restart GitLab][] for the changes to take effect.
## Set the maximum file size of the artifacts
Provided the artifacts are enabled, you can change the maximum file size of the
artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size).
[reconfigure gitlab]: restart_gitlab.md "How to restart GitLab"
[restart gitlab]: restart_gitlab.md "How to restart GitLab"
## Storage statistics
You can see the total storage used for build artifacts on groups and projects
in the administration area, as well as through the [groups](../api/groups.md)
and [projects APIs](../api/projects.md).
doc/administration/job_artifacts.md 0 → 100644
View file @ a084437b
# Jobs artifacts administration
>**Notes:**
>- Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
>- Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
changed to `ZIP`.
>- Starting with GitLab 8.17, builds are renamed to jobs.
>- This is the administration documentation. For the user guide see
[pipelines/job_artifacts](../user/project/pipelines/job_artifacts.md).
Artifacts is a list of files and directories which are attached to a job
after it completes successfully. This feature is enabled by default in all
GitLab installations. Keep reading if you want to know how to disable it.
## Disabling job artifacts
To disable artifacts site-wide, follow the steps below.
---
**In Omnibus installations:**
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
```ruby
gitlab_rails['artifacts_enabled'] = false
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
---
**In installations from source:**
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
```yaml
artifacts:
enabled: false
```
1. Save the file and [restart GitLab][] for the changes to take effect.
## Storing job artifacts
After a successful job, GitLab Runner uploads an archive containing the job
artifacts to GitLab.
To change the location where the artifacts are stored, follow the steps below.
---
**In Omnibus installations:**
_The artifacts are stored by default in
`/var/opt/gitlab/gitlab-rails/shared/artifacts`._
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/etc/gitlab/gitlab.rb` and add the following line:
```ruby
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
---
**In installations from source:**
_The artifacts are stored by default in
`/home/git/gitlab/shared/artifacts`._
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
```yaml
artifacts:
enabled: true
path: /mnt/storage/artifacts
```
1. Save the file and [restart GitLab][] for the changes to take effect.
## Set the maximum file size of the artifacts
Provided the artifacts are enabled, you can change the maximum file size of the
artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size).
## Storage statistics
You can see the total storage used for job artifacts on groups and projects
in the administration area, as well as through the [groups](../api/groups.md)
and [projects APIs](../api/projects.md).
## Implementation details
When GitLab receives an artifacts archive, an archive metadata file is also
generated. This metadata file describes all the entries that are located in the
artifacts archive itself. The metadata file is in a binary format, with
additional GZIP compression.
GitLab does not extract the artifacts archive in order to save space, memory
and disk I/O. It instead inspects the metadata file which contains all the
relevant information. This is especially important when there is a lot of
artifacts, or an archive is a very large file.
When clicking on a specific file, [GitLab Workhorse] extracts it
from the archive and the download begins. This implementation saves space,
memory and disk I/O.
[reconfigure gitlab]: restart_gitlab.md "How to restart GitLab"
[restart gitlab]: restart_gitlab.md "How to restart GitLab"
[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
doc/ci/README.md
View file @ a084437b
...@@ -2,22 +2,22 @@ ...@@ -2,22 +2,22 @@
## CI User documentation ## CI User documentation
- [Get started with GitLab CI](quick_start/README.md) - [Getting started with GitLab CI](quick_start/README.md)
- [CI examples for various languages](examples/README.md) - [CI examples for various languages](examples/README.md)
- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
- [Pipelines and builds](pipelines.md) - [Pipelines and jobs](pipelines.md)
- [Environments and deployments](environments.md) - [Environments and deployments](environments.md)
- [Learn how `.gitlab-ci.yml` works](yaml/README.md) - [Learn how `.gitlab-ci.yml` works](yaml/README.md)
- [Configure a Runner, the application that runs your builds](runners/README.md) - [Configure a Runner, the application that runs your jobs](runners/README.md)
- [Use Docker images with GitLab Runner](docker/using_docker_images.md) - [Use Docker images with GitLab Runner](docker/using_docker_images.md)
- [Use CI to build Docker images](docker/using_docker_build.md) - [Use CI to build Docker images](docker/using_docker_build.md)
- [CI Variables](variables/README.md) - Learn how to use variables defined in - [CI Variables](variables/README.md) - Learn how to use variables defined in
your `.gitlab-ci.yml` or secured ones defined in your project's settings your `.gitlab-ci.yml` or secured ones defined in your project's settings
- [Use SSH keys in your build environment](ssh_keys/README.md) - [Use SSH keys in your build environment](ssh_keys/README.md)
- [Trigger builds through the API](triggers/README.md) - [Trigger jobs through the API](triggers/README.md)
- [Build artifacts](../user/project/builds/artifacts.md) - [Job artifacts](../user/project/pipelines/job_artifacts.md)
- [User permissions](../user/permissions.md#gitlab-ci) - [User permissions](../user/permissions.md#gitlab-ci)
- [Build permissions](../user/permissions.md#build-permissions) - [Jobs permissions](../user/permissions.md#jobs-permissions)
- [API](../api/ci/README.md) - [API](../api/ci/README.md)
- [CI services (linked docker containers)](services/README.md) - [CI services (linked docker containers)](services/README.md)
- [CI/CD pipelines settings](../user/project/pipelines/settings.md) - [CI/CD pipelines settings](../user/project/pipelines/settings.md)
...@@ -27,6 +27,6 @@ ...@@ -27,6 +27,6 @@
## Breaking changes ## Breaking changes
- [New CI build permissions model](../user/project/new_ci_build_permissions_model.md) - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md)
Read about what changed in GitLab 8.12 and how that affects your builds. Read about what changed in GitLab 8.12 and how that affects your jobs.
There's a new way to access your Git submodules and LFS objects in builds. There's a new way to access your Git submodules and LFS objects in jobs.
doc/ci/build_artifacts/README.md
View file @ a084437b
This document was moved to: This document was moved to [user/project/job_artifacts.md](../../user/project/job_artifacts.md).
- [user/project/builds/artifacts.md](../../user/project/builds/artifacts.md) - user guide
- [administration/build_artifacts.md](../../administration/build_artifacts.md) - administrator guide
doc/ci/docker/README.md
View file @ a084437b
# Docker integration # Docker integration
+ [Using Docker Images](using_docker_images.md) - [Using Docker Images](using_docker_images.md)
+ [Using Docker Build](using_docker_build.md) - [Using Docker Build](using_docker_build.md)
\ No newline at end of file
doc/ci/docker/using_docker_build.md
View file @ a084437b
...@@ -12,6 +12,7 @@ One of the new trends in Continuous Integration/Deployment is to: ...@@ -12,6 +12,7 @@ One of the new trends in Continuous Integration/Deployment is to:
1. deploy to a server from the pushed image. 1. deploy to a server from the pushed image.
It's also useful when your application already has the `Dockerfile` that can be used to create and test an image: It's also useful when your application already has the `Dockerfile` that can be used to create and test an image:
```bash ```bash
$ docker build -t my-image dockerfiles/ $ docker build -t my-image dockerfiles/
$ docker run my-docker-image /script/to/run/tests $ docker run my-docker-image /script/to/run/tests
...@@ -19,23 +20,23 @@ $ docker tag my-image my-registry:5000/my-image ...@@ -19,23 +20,23 @@ $ docker tag my-image my-registry:5000/my-image
$ docker push my-registry:5000/my-image $ docker push my-registry:5000/my-image
``` ```
This requires special configuration of GitLab Runner to enable `docker` support during builds. This requires special configuration of GitLab Runner to enable `docker` support during jobs.
## Runner Configuration ## Runner Configuration
There are three methods to enable the use of `docker build` and `docker run` during builds; each with their own tradeoffs. There are three methods to enable the use of `docker build` and `docker run` during jobs; each with their own tradeoffs.
### Use shell executor ### Use shell executor
The simplest approach is to install GitLab Runner in `shell` execution mode. The simplest approach is to install GitLab Runner in `shell` execution mode.
GitLab Runner then executes build scripts as the `gitlab-runner` user. GitLab Runner then executes job scripts as the `gitlab-runner` user.
1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation). 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation).
1. During GitLab Runner installation select `shell` as method of executing build scripts or use command: 1. During GitLab Runner installation select `shell` as method of executing job scripts or use command:
```bash ```bash
$ sudo gitlab-ci-multi-runner register -n \ sudo gitlab-ci-multi-runner register -n \
--url https://gitlab.com/ci \ --url https://gitlab.com/ci \
--registration-token REGISTRATION_TOKEN \ --registration-token REGISTRATION_TOKEN \
--executor shell \ --executor shell \
...@@ -50,16 +51,17 @@ GitLab Runner then executes build scripts as the `gitlab-runner` user. ...@@ -50,16 +51,17 @@ GitLab Runner then executes build scripts as the `gitlab-runner` user.
3. Add `gitlab-runner` user to `docker` group: 3. Add `gitlab-runner` user to `docker` group:
```bash ```bash
$ sudo usermod -aG docker gitlab-runner sudo usermod -aG docker gitlab-runner
``` ```
4. Verify that `gitlab-runner` has access to Docker: 4. Verify that `gitlab-runner` has access to Docker:
```bash ```bash
$ sudo -u gitlab-runner -H docker info sudo -u gitlab-runner -H docker info
``` ```
You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`: You can now verify that everything works by adding `docker info` to `.gitlab-ci.yml`:
```yaml ```yaml
before_script: before_script:
- docker info - docker info
...@@ -80,12 +82,12 @@ For more information please read [On Docker security: `docker` group considered ...@@ -80,12 +82,12 @@ For more information please read [On Docker security: `docker` group considered
The second approach is to use the special docker-in-docker (dind) The second approach is to use the special docker-in-docker (dind)
[Docker image](https://hub.docker.com/_/docker/) with all tools installed [Docker image](https://hub.docker.com/_/docker/) with all tools installed
(`docker` and `docker-compose`) and run the build script in context of that (`docker` and `docker-compose`) and run the job script in context of that
image in privileged mode. image in privileged mode.
In order to do that, follow the steps: In order to do that, follow the steps:
1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation). 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
1. Register GitLab Runner from the command line to use `docker` and `privileged` 1. Register GitLab Runner from the command line to use `docker` and `privileged`
mode: mode:
...@@ -155,10 +157,10 @@ not without its own challenges: ...@@ -155,10 +157,10 @@ not without its own challenges:
escalation which can lead to container breakout. For more information, check escalation which can lead to container breakout. For more information, check
out the official Docker documentation on out the official Docker documentation on
[Runtime privilege and Linux capabilities][docker-cap]. [Runtime privilege and Linux capabilities][docker-cap].
- Using docker-in-docker, each build is in a clean environment without the past - When using docker-in-docker, each job is in a clean environment without the past
history. Concurrent builds work fine because every build gets it's own history. Concurrent jobs work fine because every build gets it's own
instance of Docker engine so they won't conflict with each other. But this instance of Docker engine so they won't conflict with each other. But this
also means builds can be slower because there's no caching of layers. also means jobs can be slower because there's no caching of layers.
- By default, `docker:dind` uses `--storage-driver vfs` which is the slowest - By default, `docker:dind` uses `--storage-driver vfs` which is the slowest
form offered. To use a different driver, see form offered. To use a different driver, see
[Using the overlayfs driver](#using-the-overlayfs-driver). [Using the overlayfs driver](#using-the-overlayfs-driver).
...@@ -171,7 +173,7 @@ The third approach is to bind-mount `/var/run/docker.sock` into the container so ...@@ -171,7 +173,7 @@ The third approach is to bind-mount `/var/run/docker.sock` into the container so
In order to do that, follow the steps: In order to do that, follow the steps:
1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation). 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install).
1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
...@@ -187,7 +189,9 @@ In order to do that, follow the steps: ...@@ -187,7 +189,9 @@ In order to do that, follow the steps:
The above command will register a new Runner to use the special The above command will register a new Runner to use the special
`docker:latest` image which is provided by Docker. **Notice that it's using `docker:latest` image which is provided by Docker. **Notice that it's using
the Docker daemon of the Runner itself, and any containers spawned by docker commands will be siblings of the Runner rather than children of the runner.** This may have complications and limitations that are unsuitable for your workflow. the Docker daemon of the Runner itself, and any containers spawned by docker
commands will be siblings of the Runner rather than children of the runner.**
This may have complications and limitations that are unsuitable for your workflow.
The above command will create a `config.toml` entry similar to this: The above command will create a `config.toml` entry similar to this:
...@@ -206,7 +210,8 @@ In order to do that, follow the steps: ...@@ -206,7 +210,8 @@ In order to do that, follow the steps:
Insecure = false Insecure = false
``` ```
1. You can now use `docker` in the build script (note that you don't need to include the `docker:dind` service as when using the Docker in Docker executor): 1. You can now use `docker` in the build script (note that you don't need to
include the `docker:dind` service as when using the Docker in Docker executor):
```yaml ```yaml
image: docker:latest image: docker:latest
...@@ -221,18 +226,23 @@ In order to do that, follow the steps: ...@@ -221,18 +226,23 @@ In order to do that, follow the steps:
- docker run my-docker-image /script/to/run/tests - docker run my-docker-image /script/to/run/tests
``` ```
While the above method avoids using Docker in privileged mode, you should be aware of the following implications: While the above method avoids using Docker in privileged mode, you should be
* By sharing the docker daemon, you are effectively disabling all aware of the following implications:
the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For example, if a project - By sharing the docker daemon, you are effectively disabling all
ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner the security mechanisms of containers and exposing your host to privilege
containers. escalation which can lead to container breakout. For example, if a project
* Concurrent builds may not work; if your tests ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
create containers with specific names, they may conflict with each other. containers.
* Sharing files and directories from the source repo into containers may not - Concurrent jobs may not work; if your tests
work as expected since volume mounting is done in the context of the host create containers with specific names, they may conflict with each other.
machine, not the build container. - Sharing files and directories from the source repo into containers may not
e.g. `docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests` work as expected since volume mounting is done in the context of the host
machine, not the build container, e.g.:
```
docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
```
## Using the OverlayFS driver ## Using the OverlayFS driver
...@@ -299,7 +309,7 @@ push to the Registry connected to your project. Its password is provided in the ...@@ -299,7 +309,7 @@ push to the Registry connected to your project. Its password is provided in the
of your Docker images. of your Docker images.
Here's a more elaborate example that splits up the tasks into 4 pipeline stages, Here's a more elaborate example that splits up the tasks into 4 pipeline stages,
including two tests that run in parallel. The build is stored in the container including two tests that run in parallel. The `build` is stored in the container
registry and used by subsequent stages, downloading the image registry and used by subsequent stages, downloading the image
when needed. Changes to `master` also get tagged as `latest` and deployed using when needed. Changes to `master` also get tagged as `latest` and deployed using
an application-specific deploy script: an application-specific deploy script:
...@@ -360,17 +370,17 @@ deploy: ...@@ -360,17 +370,17 @@ deploy:
Some things you should be aware of when using the Container Registry: Some things you should be aware of when using the Container Registry:
- You must log in to the container registry before running commands. Putting - You must log in to the container registry before running commands. Putting
this in `before_script` will run it before each build job. this in `before_script` will run it before each job.
- Using `docker build --pull` makes sure that Docker fetches any changes to base - Using `docker build --pull` makes sure that Docker fetches any changes to base
images before building just in case your cache is stale. It takes slightly images before building just in case your cache is stale. It takes slightly
longer, but means you don’t get stuck without security patches to base images. longer, but means you don’t get stuck without security patches to base images.
- Doing an explicit `docker pull` before each `docker run` makes sure to fetch - Doing an explicit `docker pull` before each `docker run` makes sure to fetch
the latest image that was just built. This is especially important if you are the latest image that was just built. This is especially important if you are
using multiple runners that cache images locally. Using the git SHA in your using multiple runners that cache images locally. Using the git SHA in your
image tag makes this less necessary since each build will be unique and you image tag makes this less necessary since each job will be unique and you
shouldn't ever have a stale image, but it's still possible if you re-build a shouldn't ever have a stale image, but it's still possible if you re-build a
given commit after a dependency has changed. given commit after a dependency has changed.
- You don't want to build directly to `latest` in case there are multiple builds - You don't want to build directly to `latest` in case there are multiple jobs
happening simultaneously. happening simultaneously.
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
......
doc/ci/docker/using_docker_images.md
View file @ a084437b
...@@ -8,7 +8,7 @@ run applications in independent "containers" that are run within a single Linux ...@@ -8,7 +8,7 @@ run applications in independent "containers" that are run within a single Linux
instance. [Docker Hub][hub] has a rich database of pre-built images that can be instance. [Docker Hub][hub] has a rich database of pre-built images that can be
used to test and build your applications. used to test and build your applications.
Docker, when used with GitLab CI, runs each build in a separate and isolated Docker, when used with GitLab CI, runs each job in a separate and isolated
container using the predefined image that is set up in container using the predefined image that is set up in
[`.gitlab-ci.yml`](../yaml/README.md). [`.gitlab-ci.yml`](../yaml/README.md).
...@@ -45,12 +45,12 @@ can be found at [Docker Hub][hub]. For more information about images and Docker ...@@ -45,12 +45,12 @@ can be found at [Docker Hub][hub]. For more information about images and Docker
Hub please read the [Docker Fundamentals][] documentation. Hub please read the [Docker Fundamentals][] documentation.
In short, with `image` we refer to the docker image, which will be used to In short, with `image` we refer to the docker image, which will be used to
create a container on which your build will run. create a container on which your job will run.
## What is a service ## What is a service
The `services` keyword defines just another docker image that is run during The `services` keyword defines just another docker image that is run during
your build and is linked to the docker image that the `image` keyword defines. your job and is linked to the docker image that the `image` keyword defines.
This allows you to access the service image during build time. This allows you to access the service image during build time.
The service image can run any application, but the most common use case is to The service image can run any application, but the most common use case is to
...@@ -61,13 +61,13 @@ time the project is built. ...@@ -61,13 +61,13 @@ time the project is built.
You can see some widely used services examples in the relevant documentation of You can see some widely used services examples in the relevant documentation of
[CI services examples](../services/README.md). [CI services examples](../services/README.md).
### How services are linked to the build ### How services are linked to the job
To better understand how the container linking works, read To better understand how the container linking works, read
[Linking containers together][linking-containers]. [Linking containers together][linking-containers].
To summarize, if you add `mysql` as service to your application, the image will To summarize, if you add `mysql` as service to your application, the image will
then be used to create a container that is linked to the build container. then be used to create a container that is linked to the job container.
The service container for MySQL will be accessible under the hostname `mysql`. The service container for MySQL will be accessible under the hostname `mysql`.
So, in order to access your database service you have to connect to the host So, in order to access your database service you have to connect to the host
...@@ -133,7 +133,7 @@ Look for the `[runners.docker]` section: ...@@ -133,7 +133,7 @@ Look for the `[runners.docker]` section:
services = ["mysql:latest", "postgres:latest"] services = ["mysql:latest", "postgres:latest"]
``` ```
The image and services defined this way will be added to all builds run by The image and services defined this way will be added to all job run by
that runner. that runner.
## Define an image from a private Docker registry ## Define an image from a private Docker registry
...@@ -167,7 +167,7 @@ services: ...@@ -167,7 +167,7 @@ services:
- tutum/wordpress:latest - tutum/wordpress:latest
``` ```
When the build is run, `tutum/wordpress` will be started and you will have When the job is run, `tutum/wordpress` will be started and you will have
access to it from your build container under the hostname `tutum__wordpress`. access to it from your build container under the hostname `tutum__wordpress`.
The alias hostname for the service is made from the image name following these The alias hostname for the service is made from the image name following these
...@@ -202,21 +202,21 @@ See the specific documentation for ...@@ -202,21 +202,21 @@ See the specific documentation for
## How Docker integration works ## How Docker integration works
Below is a high level overview of the steps performed by docker during build Below is a high level overview of the steps performed by docker during job
time. time.
1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`. 1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`.
1. Create cache container to store all volumes as defined in `config.toml` and 1. Create cache container to store all volumes as defined in `config.toml` and
`Dockerfile` of build image (`ruby:2.1` as in above example). `Dockerfile` of build image (`ruby:2.1` as in above example).
1. Create build container and link any service container to build container. 1. Create build container and link any service container to build container.
1. Start build container and send build script to the container. 1. Start build container and send job script to the container.
1. Run build script. 1. Run job script.
1. Checkout code in: `/builds/group-name/project-name/`. 1. Checkout code in: `/builds/group-name/project-name/`.
1. Run any step defined in `.gitlab-ci.yml`. 1. Run any step defined in `.gitlab-ci.yml`.
1. Check exit status of build script. 1. Check exit status of build script.
1. Remove build container and all created service containers. 1. Remove build container and all created service containers.
## How to debug a build locally ## How to debug a job locally
*Note: The following commands are run without root privileges. You should be *Note: The following commands are run without root privileges. You should be
able to run docker with your regular user account.* able to run docker with your regular user account.*
......
doc/ci/enable_or_disable_ci.md
View file @ a084437b
...@@ -12,7 +12,7 @@ API. ...@@ -12,7 +12,7 @@ API.
--- ---
GitLab CI is exposed via the `/pipelines` and `/builds` pages of a project. GitLab CI is exposed via the `/pipelines` and `/builds` pages of a project.
Disabling GitLab CI in a project does not delete any previous builds. Disabling GitLab CI in a project does not delete any previous jobs.
In fact, the `/pipelines` and `/builds` pages can still be accessed, although In fact, the `/pipelines` and `/builds` pages can still be accessed, although
it's hidden from the left sidebar menu. it's hidden from the left sidebar menu.
......
doc/ci/environments.md
View file @ a084437b
...@@ -75,7 +75,7 @@ We have defined 3 [stages](yaml/README.md#stages): ...@@ -75,7 +75,7 @@ We have defined 3 [stages](yaml/README.md#stages):
- deploy - deploy
The jobs assigned to these stages will run in this order. If a job fails, then The jobs assigned to these stages will run in this order. If a job fails, then
the builds that are assigned to the next stage won't run, rendering the pipeline the jobs that are assigned to the next stage won't run, rendering the pipeline
as failed. In our case, the `test` job will run first, then the `build` and as failed. In our case, the `test` job will run first, then the `build` and
lastly the `deploy_staging`. With this, we ensure that first the tests pass, lastly the `deploy_staging`. With this, we ensure that first the tests pass,
then our app is able to be built successfully, and lastly we deploy to the then our app is able to be built successfully, and lastly we deploy to the
...@@ -119,7 +119,7 @@ There's a bunch of information there, specifically you can see: ...@@ -119,7 +119,7 @@ There's a bunch of information there, specifically you can see:
- The environment's name with a link to its deployments - The environment's name with a link to its deployments
- The last deployment ID number and who performed it - The last deployment ID number and who performed it
- The build ID of the last deployment with its respective job name - The job ID of the last deployment with its respective job name
- The commit information of the last deployment such as who committed, to what - The commit information of the last deployment such as who committed, to what
branch and the Git SHA of the commit branch and the Git SHA of the commit
- The exact time the last deployment was performed - The exact time the last deployment was performed
...@@ -219,9 +219,9 @@ deploy_prod: ...@@ -219,9 +219,9 @@ deploy_prod:
The `when: manual` action exposes a play button in GitLab's UI and the The `when: manual` action exposes a play button in GitLab's UI and the
`deploy_prod` job will only be triggered if and when we click that play button. `deploy_prod` job will only be triggered if and when we click that play button.
You can find it in the pipeline, build, environment, and deployment views. You can find it in the pipeline, job, environment, and deployment views.
| Pipelines | Single pipeline | Environments | Deployments | Builds | | Pipelines | Single pipeline | Environments | Deployments | jobs |
| --------- | ----------------| ------------ | ----------- | -------| | --------- | ----------------| ------------ | ----------- | -------|
| ![Pipelines manual action](img/environments_manual_action_pipelines.png) | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) | ![Environments manual action](img/environments_manual_action_environments.png) | ![Deployments manual action](img/environments_manual_action_deployments.png) | ![Builds manual action](img/environments_manual_action_builds.png) | | ![Pipelines manual action](img/environments_manual_action_pipelines.png) | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) | ![Environments manual action](img/environments_manual_action_environments.png) | ![Deployments manual action](img/environments_manual_action_deployments.png) | ![Builds manual action](img/environments_manual_action_builds.png) |
...@@ -419,7 +419,7 @@ Behind the scenes: ...@@ -419,7 +419,7 @@ Behind the scenes:
- GitLab Runner picks up the changes and starts running the jobs - GitLab Runner picks up the changes and starts running the jobs
- The jobs run sequentially as defined in `stages` - The jobs run sequentially as defined in `stages`
- First, the tests pass - First, the tests pass
- Then, the build begins and successfully also passes - Then, the job begins and successfully also passes
- Lastly, the app is deployed to an environment with a name specific to the - Lastly, the app is deployed to an environment with a name specific to the
branch branch
......
doc/ci/examples/deployment/README.md
View file @ a084437b
...@@ -91,7 +91,7 @@ Secure Variables can added by going to `Project > Variables > Add Variable`. ...@@ -91,7 +91,7 @@ Secure Variables can added by going to `Project > Variables > Add Variable`.
**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.** **This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
The variables that are defined in the project settings are sent along with the build script to the runner. The variables that are defined in the project settings are sent along with the build script to the runner.
The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml. The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml.
It is also important that secret's value is hidden in the build log. It is also important that secret's value is hidden in the job log.
You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners): You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners):
1. `$SECRET_VARIABLE` - use it for non-Windows runners 1. `$SECRET_VARIABLE` - use it for non-Windows runners
......
doc/ci/examples/deployment/composer-npm-deploy.md
View file @ a084437b
...@@ -65,7 +65,7 @@ In order, this means that: ...@@ -65,7 +65,7 @@ In order, this means that:
1. We check if the `ssh-agent` is available and we install it if it's not; 1. We check if the `ssh-agent` is available and we install it if it's not;
2. We create the `~/.ssh` folder; 2. We create the `~/.ssh` folder;
3. We make sure we're running bash; 3. We make sure we're running bash;
4. We disable host checking (we don't ask for user accept when we first connect to a server; and since every build will equal a first connect, we kind of need this) 4. We disable host checking (we don't ask for user accept when we first connect to a server; and since every job will equal a first connect, we kind of need this)
And this is basically all you need in the `before_script` section. And this is basically all you need in the `before_script` section.
......
doc/ci/examples/php.md
View file @ a084437b
...@@ -15,10 +15,10 @@ This will allow us to test PHP projects against different versions of PHP. ...@@ -15,10 +15,10 @@ This will allow us to test PHP projects against different versions of PHP.
However, not everything is plug 'n' play, you still need to configure some However, not everything is plug 'n' play, you still need to configure some
things manually. things manually.
As with every build, you need to create a valid `.gitlab-ci.yml` describing the As with every job, you need to create a valid `.gitlab-ci.yml` describing the
build environment. build environment.
Let's first specify the PHP image that will be used for the build process Let's first specify the PHP image that will be used for the job process
(you can read more about what an image means in the Runner's lingo reading (you can read more about what an image means in the Runner's lingo reading
about [Using Docker images](../docker/using_docker_images.md#what-is-image)). about [Using Docker images](../docker/using_docker_images.md#what-is-image)).
...@@ -58,8 +58,8 @@ docker-php-ext-install pdo_mysql ...@@ -58,8 +58,8 @@ docker-php-ext-install pdo_mysql
``` ```
You might wonder what `docker-php-ext-install` is. In short, it is a script You might wonder what `docker-php-ext-install` is. In short, it is a script
provided by the official php docker image that you can use to easilly install provided by the official php docker image that you can use to easily install
extensions. For more information read the the documentation at extensions. For more information read the documentation at
<https://hub.docker.com/r/_/php/>. <https://hub.docker.com/r/_/php/>.
Now that we created the script that contains all prerequisites for our build Now that we created the script that contains all prerequisites for our build
...@@ -142,7 +142,7 @@ Of course, `my_php.ini` must be present in the root directory of your repository ...@@ -142,7 +142,7 @@ Of course, `my_php.ini` must be present in the root directory of your repository
## Test PHP projects using the Shell executor ## Test PHP projects using the Shell executor
The shell executor runs your builds in a terminal session on your server. The shell executor runs your job in a terminal session on your server.
Thus, in order to test your projects you first need to make sure that all Thus, in order to test your projects you first need to make sure that all
dependencies are installed. dependencies are installed.
...@@ -280,7 +280,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available ...@@ -280,7 +280,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md). [shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin. moments the changes will be picked by a public runner and the job will begin.
[php-hub]: https://hub.docker.com/r/_/php/ [php-hub]: https://hub.docker.com/r/_/php/
[phpenv]: https://github.com/phpenv/phpenv [phpenv]: https://github.com/phpenv/phpenv
......
doc/ci/examples/test-scala-application.md
View file @ a084437b
...@@ -51,14 +51,14 @@ The `deploy` stage automatically deploys the project to Heroku using dpl. ...@@ -51,14 +51,14 @@ The `deploy` stage automatically deploys the project to Heroku using dpl.
You can use other versions of Scala and SBT by defining them in You can use other versions of Scala and SBT by defining them in
`build.sbt`. `build.sbt`.
## Display test coverage in build ## Display test coverage in job
Add the `Coverage was \[\d+.\d+\%\]` regular expression in the Add the `Coverage was \[\d+.\d+\%\]` regular expression in the
**Settings ➔ Edit Project ➔ Test coverage parsing** project setting to **Settings ➔ CI/CD Pipelines ➔ Coverage report** project setting to
retrieve the [test coverage] rate from the build trace and have it retrieve the [test coverage] rate from the build trace and have it
displayed with your builds. displayed with your jobs.
**Builds** must be enabled for this option to appear. **Pipelines** must be enabled for this option to appear.
## Heroku application ## Heroku application
......
doc/ci/git_submodules.md
View file @ a084437b
# Using Git submodules with GitLab CI # Using Git submodules with GitLab CI
> **Notes:** > **Notes:**
- GitLab 8.12 introduced a new [CI build permissions model][newperms] and you - GitLab 8.12 introduced a new [CI job permissions model][newperms] and you
are encouraged to upgrade your GitLab instance if you haven't done already. are encouraged to upgrade your GitLab instance if you haven't done already.
If you are **not** using GitLab 8.12 or higher, you would need to work your way If you are **not** using GitLab 8.12 or higher, you would need to work your way
around submodules in order to access the sources of e.g., `gitlab.com/group/project` around submodules in order to access the sources of e.g., `gitlab.com/group/project`
with the use of [SSH keys](ssh_keys/README.md). with the use of [SSH keys](ssh_keys/README.md).
- With GitLab 8.12 onward, your permissions are used to evaluate what a CI build - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job
can access. More information about how this system works can be found in the can access. More information about how this system works can be found in the
[Build permissions model](../user/permissions.md#builds-permissions). [Jobs permissions model](../user/permissions.md#jobs-permissions).
- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance.
## Configuring the `.gitmodules` file ## Configuring the `.gitmodules` file
...@@ -27,7 +27,7 @@ Let's consider the following example: ...@@ -27,7 +27,7 @@ Let's consider the following example:
If you are using GitLab 8.12+ and your submodule is on the same GitLab server, If you are using GitLab 8.12+ and your submodule is on the same GitLab server,
you must update your `.gitmodules` file to use **relative URLs**. you must update your `.gitmodules` file to use **relative URLs**.
Since Git allows the usage of relative URLs for your `.gitmodules` configuration, Since Git allows the usage of relative URLs for your `.gitmodules` configuration,
this easily allows you to use HTTP(S) for cloning all your CI builds and SSH this easily allows you to use HTTP(S) for cloning all your CI jobs and SSH
for all your local checkouts. The `.gitmodules` would look like: for all your local checkouts. The `.gitmodules` would look like:
```ini ```ini
...@@ -38,7 +38,7 @@ for all your local checkouts. The `.gitmodules` would look like: ...@@ -38,7 +38,7 @@ for all your local checkouts. The `.gitmodules` would look like:
The above configuration will instruct Git to automatically deduce the URL that The above configuration will instruct Git to automatically deduce the URL that
should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use
that same channel and it will allow to make all your CI builds use HTTP(S) that same channel and it will allow to make all your CI jobs use HTTP(S)
(because GitLab CI only uses HTTP(S) for cloning your sources), and all your local (because GitLab CI only uses HTTP(S) for cloning your sources), and all your local
clones will continue using SSH. clones will continue using SSH.
...@@ -57,13 +57,13 @@ Once `.gitmodules` is correctly configured, you can move on to ...@@ -57,13 +57,13 @@ Once `.gitmodules` is correctly configured, you can move on to
## Using Git submodules in your CI jobs ## Using Git submodules in your CI jobs
There are a few steps you need to take in order to make submodules work There are a few steps you need to take in order to make submodules work
correctly with your CI builds: correctly with your CI jobs:
1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file) 1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file)
for the submodules located in the same GitLab server. for the submodules located in the same GitLab server.
1. Next, if you are using `gitlab-ci-multi-runner` v1.10+, you can set the 1. Next, if you are using `gitlab-ci-multi-runner` v1.10+, you can set the
`GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell `GIT_SUBMODULE_STRATEGY` variable to either `normal` or `recursive` to tell
the runner to fetch your submodules before the build: the runner to fetch your submodules before the job:
```yaml ```yaml
variables: variables:
GIT_SUBMODULE_STRATEGY: recursive GIT_SUBMODULE_STRATEGY: recursive
...@@ -87,9 +87,9 @@ The rationale to set the `sync` and `update` in `before_script` is because of ...@@ -87,9 +87,9 @@ The rationale to set the `sync` and `update` in `before_script` is because of
the way Git submodules work. On a fresh Runner workspace, Git will set the the way Git submodules work. On a fresh Runner workspace, Git will set the
submodule URL including the token in `.git/config` submodule URL including the token in `.git/config`
(or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current (or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current
remote URL. On subsequent builds on the same Runner, `.git/config` is cached remote URL. On subsequent jobs on the same Runner, `.git/config` is cached
and already contains a full URL for the submodule, corresponding to the previous and already contains a full URL for the submodule, corresponding to the previous
build, and to **a token from a previous build**. `sync` allows to force updating job, and to **a token from a previous job**. `sync` allows to force updating
the full URL. the full URL.
[gitpro]: ../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols [gitpro]: ../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
......
doc/ci/pipelines.md
View file @ a084437b
# Introduction to pipelines and builds # Introduction to pipelines and jobs
>**Note:** >**Note:**
Introduced in GitLab 8.8. Introduced in GitLab 8.8.
## Pipelines ## Pipelines
A pipeline is a group of [builds][] that get executed in [stages][](batches). A pipeline is a group of [jobs][] that get executed in [stages][](batches).
All of the builds in a stage are executed in parallel (if there are enough All of the jobs in a stage are executed in parallel (if there are enough
concurrent [Runners]), and if they all succeed, the pipeline moves on to the 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) next stage. If one of the jobs fails, the next stage is not (usually)
executed. executed.
![Pipelines example](img/pipelines.png) ![Pipelines example](img/pipelines.png)
...@@ -35,10 +35,10 @@ Example continuous delivery flow: ...@@ -35,10 +35,10 @@ Example continuous delivery flow:
![CD Flow](img/pipelines-goal.svg) ![CD Flow](img/pipelines-goal.svg)
## Builds ## Jobs
Builds are individual runs of [jobs]. Not to be confused with a `build` job or Jobs can be defined in the [`.gitlab-ci.yml`][jobs-yaml] file. Not to be
`build` stage. confused with a `build` job or `build` stage.
## Defining pipelines ## Defining pipelines
...@@ -52,11 +52,11 @@ See full [documentation](yaml/README.md#jobs). ...@@ -52,11 +52,11 @@ See full [documentation](yaml/README.md#jobs).
You can find the current and historical pipeline runs under **Pipelines** for You can find the current and historical pipeline runs under **Pipelines** for
your project. your project.
## Seeing build status ## Seeing job status
Clicking on a pipeline will show the builds that were run for that pipeline. Clicking on a pipeline will show the jobs that were run for that pipeline.
Clicking on an individual build will show you its build trace, and allow you to Clicking on an individual job will show you its job trace, and allow you to
cancel the build, retry it, or erase the build trace. cancel the job, retry it, or erase the job trace.
## How the pipeline duration is calculated ## How the pipeline duration is calculated
...@@ -91,11 +91,11 @@ total running time should be: ...@@ -91,11 +91,11 @@ total running time should be:
## Badges ## Badges
Build status and test coverage report badges are available. You can find their Job status and test coverage report badges are available. You can find their
respective link in the [Pipelines settings] page. respective link in the [Pipelines settings] page.
[builds]: #builds [jobs]: #jobs
[jobs]: yaml/README.md#jobs [jobs-yaml]: yaml/README.md#jobs
[stages]: yaml/README.md#stages [stages]: yaml/README.md#stages
[runners]: runners/README.html [runners]: runners/README.html
[pipelines settings]: ../user/project/pipelines/settings.md [pipelines settings]: ../user/project/pipelines/settings.md
doc/ci/quick_start/README.md
View file @ a084437b
# Quick Start # Getting started with GitLab CI
>**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI) >**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI)
is fully integrated into GitLab itself and is [enabled] by default on all is fully integrated into GitLab itself and is [enabled] by default on all
...@@ -7,7 +7,7 @@ projects. ...@@ -7,7 +7,7 @@ projects.
GitLab offers a [continuous integration][ci] service. If you GitLab offers a [continuous integration][ci] service. If you
[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, [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 and configure your GitLab project to use a [Runner], then each merge request or
push triggers your CI [pipeline]. push, triggers your CI [pipeline].
The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs 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 a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to
...@@ -31,13 +31,13 @@ So in brief, the steps needed to have a working CI can be summed up to: ...@@ -31,13 +31,13 @@ So in brief, the steps needed to have a working CI can be summed up to:
From there on, on every push to your Git repository, the Runner will From there on, on every push to your Git repository, the Runner will
automagically start the pipeline and the pipeline will appear under the automagically start the pipeline and the pipeline will appear under the
project's `/pipelines` page. project's **Pipelines** page.
--- ---
This guide assumes that you: This guide assumes that you:
- have a working GitLab instance of version 8.0 or higher or are using - have a working GitLab instance of version 8.0+r or are using
[GitLab.com](https://gitlab.com) [GitLab.com](https://gitlab.com)
- have a project in GitLab that you would like to use CI for - have a project in GitLab that you would like to use CI for
...@@ -54,7 +54,7 @@ The `.gitlab-ci.yml` file is where you configure what CI does with your project. ...@@ -54,7 +54,7 @@ The `.gitlab-ci.yml` file is where you configure what CI does with your project.
It lives in the root of your repository. It lives in the root of your repository.
On any push to your repository, GitLab will look for the `.gitlab-ci.yml` 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, file and start jobs on _Runners_ according to the contents of the file,
for that commit. for that commit.
Because `.gitlab-ci.yml` is in the repository and is version controlled, old Because `.gitlab-ci.yml` is in the repository and is version controlled, old
...@@ -63,11 +63,12 @@ have different pipelines and jobs, and you have a single source of truth for CI. ...@@ -63,11 +63,12 @@ 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 You can read more about the reasons why we are using `.gitlab-ci.yml` [in our
blog about it][blog-ci]. 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 indentation. Always use spaces, not tabs.
### Creating a simple `.gitlab-ci.yml` file ### Creating a simple `.gitlab-ci.yml` file
>**Note:**
`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file
so you have to pay extra attention to indentation. Always use spaces, not tabs.
You need to create a file named `.gitlab-ci.yml` in the root directory of your You need to create a file named `.gitlab-ci.yml` in the root directory of your
repository. Below is an example for a Ruby on Rails project. repository. Below is an example for a Ruby on Rails project.
...@@ -88,7 +89,7 @@ rubocop: ...@@ -88,7 +89,7 @@ rubocop:
- bundle exec rubocop - bundle exec rubocop
``` ```
This is the simplest possible build configuration that will work for most Ruby This is the simplest possible configuration that will work for most Ruby
applications: applications:
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with 1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
...@@ -98,22 +99,22 @@ applications: ...@@ -98,22 +99,22 @@ applications:
The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when
they should be run. The jobs are defined as top-level elements with a name (in they should be run. The jobs are defined as top-level elements with a name (in
our case `rspec` and `rubocop`) and always have to contain the `script` keyword. our case `rspec` and `rubocop`) and always have to contain the `script` keyword.
Jobs are used to create builds, which are then picked by Jobs are used to create jobs, which are then picked by
[Runners](../runners/README.md) and executed within the environment of the Runner. [Runners](../runners/README.md) and executed within the environment of the Runner.
What is important is that each job is run independently from each other. What is important is that each job is run independently from each other.
If you want to check whether your `.gitlab-ci.yml` file is valid, there is a 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 Lint tool under the page `/ci/lint` of your GitLab instance. You can also find
a "CI Lint" button to go to this page under **Pipelines > Pipelines** and a "CI Lint" button to go to this page under **Pipelines ➔ Pipelines** and
**Pipelines > Builds** in your project. **Pipelines ➔ Jobs** in your project.
For more information and a complete `.gitlab-ci.yml` syntax, please read For more information and a complete `.gitlab-ci.yml` syntax, please read
[the documentation on .gitlab-ci.yml](../yaml/README.md). [the reference documentation on .gitlab-ci.yml](../yaml/README.md).
### Push `.gitlab-ci.yml` to GitLab ### Push `.gitlab-ci.yml` to GitLab
Once you've created `.gitlab-ci.yml`, you should add it to your git repository Once you've created `.gitlab-ci.yml`, you should add it to your Git repository
and push it to GitLab. and push it to GitLab.
```bash ```bash
...@@ -125,28 +126,27 @@ git push origin master ...@@ -125,28 +126,27 @@ git push origin master
Now if you go to the **Pipelines** page you will see that the pipeline is Now if you go to the **Pipelines** page you will see that the pipeline is
pending. pending.
You can also go to the **Commits** page and notice the little clock icon next You can also go to the **Commits** page and notice the little pause icon next
to the commit SHA. to the commit SHA.
![New commit pending](img/new_commit.png) ![New commit pending](img/new_commit.png)
Clicking on the clock icon you will be directed to the builds page for that Clicking on it you will be directed to the jobs page for that specific commit.
specific commit.
![Single commit builds page](img/single_commit_status_pending.png) ![Single commit jobs page](img/single_commit_status_pending.png)
Notice that there are two jobs pending which are named after what we wrote in 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 `.gitlab-ci.yml`. The red triangle indicates that there is no Runner configured
yet for these builds. yet for these jobs.
The next step is to configure a Runner so that it picks the pending builds. The next step is to configure a Runner so that it picks the pending jobs.
## Configuring a Runner ## Configuring a Runner
In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`. A Runner In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml`. A Runner
can be a virtual machine, a VPS, a bare-metal machine, a docker container or 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, 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. 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 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_. GitLab. If it serves all projects it's called a _Shared Runner_.
...@@ -155,9 +155,9 @@ Find more information about different Runners in the ...@@ -155,9 +155,9 @@ Find more information about different Runners in the
[Runners](../runners/README.md) documentation. [Runners](../runners/README.md) documentation.
You can find whether any Runners are assigned to your project by going to You can find whether any Runners are assigned to your project by going to
**Settings > Runners**. Setting up a Runner is easy and straightforward. The **Settings ➔ Runners**. Setting up a Runner is easy and straightforward. The
official Runner supported by GitLab is written in Go and can be found at official Runner supported by GitLab is written in Go and its documentation
<https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>. can be found at <https://docs.gitlab.com/runner/>.
In order to have a functional Runner you need to follow two steps: In order to have a functional Runner you need to follow two steps:
...@@ -167,28 +167,25 @@ In order to have a functional Runner you need to follow two steps: ...@@ -167,28 +167,25 @@ In order to have a functional Runner you need to follow two steps:
Follow the links above to set up your own Runner or use a Shared Runner as Follow the links above to set up your own Runner or use a Shared Runner as
described in the next section. described in the next section.
For other types of unofficial Runners written in other languages, see the
[instructions for the various GitLab Runners](https://about.gitlab.com/gitlab-ci/#gitlab-runner).
Once the Runner has been set up, you should see it on the Runners page of your Once the Runner has been set up, you should see it on the Runners page of your
project, following **Settings > Runners**. project, following **Settings ➔ Runners**.
![Activated runners](img/runners_activated.png) ![Activated runners](img/runners_activated.png)
### Shared Runners ### Shared Runners
If you use [GitLab.com](https://gitlab.com/) you can use **Shared Runners** If you use [GitLab.com](https://gitlab.com/) you can use the **Shared Runners**
provided by GitLab Inc. provided by GitLab Inc.
These are special virtual machines that run on GitLab's infrastructure and can These are special virtual machines that run on GitLab's infrastructure and can
build any project. build any project.
To enable **Shared Runners** you have to go to your project's To enable the **Shared Runners** you have to go to your project's
**Settings > Runners** and click **Enable shared runners**. **Settings ➔ Runners** and click **Enable shared runners**.
[Read more on Shared Runners](../runners/README.md). [Read more on Shared Runners](../runners/README.md).
## Seeing the status of your pipeline and builds ## Seeing the status of your pipeline and jobs
After configuring the Runner successfully, you should see the status of your After configuring the Runner successfully, you should see the status of your
last commit change from _pending_ to either _running_, _success_ or _failed_. last commit change from _pending_ to either _running_, _success_ or _failed_.
...@@ -197,23 +194,23 @@ You can view all pipelines by going to the **Pipelines** page in your project. ...@@ -197,23 +194,23 @@ You can view all pipelines by going to the **Pipelines** page in your project.
![Commit status](img/pipelines_status.png) ![Commit status](img/pipelines_status.png)
Or you can view all builds, by going to the **Pipelines > Builds** page. Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
![Commit status](img/builds_status.png) ![Commit status](img/builds_status.png)
By clicking on a Build ID, you will be able to see the log of that build. By clicking on a job's status, you will be able to see the log of that job.
This is important to diagnose why a build failed or acted differently than This is important to diagnose why a job failed or acted differently than
you expected. you expected.
![Build log](img/build_log.png) ![Build log](img/build_log.png)
You are also able to view the status of any commit in the various pages in You are also able to view the status of any commit in the various pages in
GitLab, such as **Commits** and **Merge Requests**. GitLab, such as **Commits** and **Merge requests**.
## Enabling build emails ## Enabling build emails
If you want to receive e-mail notifications about the result status of the If you want to receive e-mail notifications about the result status of the
builds, you should explicitly enable the **Builds Emails** service under your jobs, you should explicitly enable the **Builds Emails** service under your
project's settings. project's settings.
For more information read the For more information read the
...@@ -224,9 +221,7 @@ For more information read the ...@@ -224,9 +221,7 @@ For more information read the
Visit the [examples README][examples] to see a list of examples using GitLab Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages. CI with various languages.
Awesome! You started using CI in GitLab! [runner-install]: https://docs.gitlab.com/runner/install/
[runner-install]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tree/master#install-gitlab-runner
[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ [blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
[examples]: ../examples/README.md [examples]: ../examples/README.md
[ci]: https://about.gitlab.com/gitlab-ci/ [ci]: https://about.gitlab.com/gitlab-ci/
...@@ -235,3 +230,4 @@ Awesome! You started using CI in GitLab! ...@@ -235,3 +230,4 @@ Awesome! You started using CI in GitLab!
[enabled]: ../enable_or_disable_ci.md [enabled]: ../enable_or_disable_ci.md
[stages]: ../yaml/README.md#stages [stages]: ../yaml/README.md#stages
[pipeline]: ../pipelines.md [pipeline]: ../pipelines.md
[internet]: https://about.gitlab.com/images/theinternet.png
doc/ci/quick_start/img/build_log.png
View replaced file @ 6038355f View file @ a084437b
doc/ci/quick_start/img/build_log.png

23.9 KB | W: | H:

doc/ci/quick_start/img/build_log.png

34.4 KB | W: | H:

doc/ci/quick_start/img/build_log.png
doc/ci/quick_start/img/build_log.png
doc/ci/quick_start/img/build_log.png
doc/ci/quick_start/img/build_log.png
  • 2-up
  • Swipe
  • Onion skin
doc/ci/quick_start/img/new_commit.png
View replaced file @ 6038355f View file @ a084437b
doc/ci/quick_start/img/new_commit.png

4.66 KB | W: | H:

doc/ci/quick_start/img/new_commit.png

5.45 KB | W: | H:

doc/ci/quick_start/img/new_commit.png
doc/ci/quick_start/img/new_commit.png
doc/ci/quick_start/img/new_commit.png
doc/ci/quick_start/img/new_commit.png
  • 2-up
  • Swipe
  • Onion skin
doc/ci/runners/README.md
View file @ a084437b
# Runners # Runners
In GitLab CI, Runners run your [yaml](../yaml/README.md). In GitLab CI, Runners run your [yaml](../yaml/README.md).
A runner is an isolated (virtual) machine that picks up builds A Runner is an isolated (virtual) machine that picks up jobs
through the coordinator API of GitLab CI. through the coordinator API of GitLab CI.
A runner can be specific to a certain project or serve any project 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. in GitLab CI. A Runner that serves all projects is called a shared Runner.
Ideally, GitLab Runner should not be installed on the same machine as GitLab. Ideally, GitLab Runner should not be installed on the same machine as GitLab.
Read the [requirements documentation](../../install/requirements.md#gitlab-runner) Read the [requirements documentation](../../install/requirements.md#gitlab-Runner)
for more information. for more information.
## Shared vs. Specific Runners ## Shared vs. Specific Runners
A runner that is specific only runs for the specified project. A shared runner A Runner that is specific only runs for the specified project. A shared Runner
can run jobs for every project that has enabled the option can run jobs for every project that has enabled the option
`Allow shared runners`. `Allow shared Runners`.
**Shared runners** are useful for jobs that have similar requirements, **Shared Runners** are useful for jobs that have similar requirements,
between multiple projects. Rather than having multiple runners idling for 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 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. multiple projects. This makes it easier to maintain and update Runners.
**Specific runners** are useful for jobs that have special requirements or for **Specific Runners** are useful for jobs that have special requirements or for
projects with a specific demand. If a job has certain requirements, you can set projects with a specific 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 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 Runners. For example, if you want to deploy a certain project, you can setup
a specific runner to have the right credentials for this. a specific Runner to have the right credentials for this.
Projects with high demand of CI activity can also benefit from using specific runners. Projects with high demand of CI activity can also benefit from using specific Runners.
By having dedicated runners you are guaranteed that the runner is not being held By having dedicated Runners you are guaranteed that the Runner is not being held
up by another project's jobs. up by another project's jobs.
You can set up a specific runner to be used by multiple projects. The difference You can set up a specific Runner to be used by multiple projects. The difference
with a shared runner is that you have to enable each project explicitly for with a shared Runner is that you have to enable each project explicitly for
the runner to be able to run its jobs. the Runner to be able to run its jobs.
Specific runners do not get shared with forked projects automatically. 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. A fork does copy the CI settings (jobs, allow shared, etc) of the cloned repository.
# Creating and Registering a Runner # Creating and Registering a Runner
There are several ways to create a runner. Only after creation, upon There are several ways to create a Runner. Only after creation, upon
registration its status as Shared or Specific is determined. registration its status as Shared or Specific is determined.
[See the documentation for](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/#installation) [See the documentation for](https://gitlab.com/gitlab-org/gitlab-ci-multi-Runner/#installation)
the different methods of installing a Runner instance. the different methods of installing a Runner instance.
After installing the runner, you can either register it as `Shared` or as `Specific`. After installing the Runner, you can either register it as `Shared` or as `Specific`.
You can only register a Shared Runner if you have admin access to the GitLab instance. You can only register a Shared Runner if you have admin access to the GitLab instance.
## Registering a Shared Runner ## Registering a Shared Runner
You can only register a shared runner if you are an admin on the linked You can only register a shared Runner if you are an admin on the linked
GitLab instance. GitLab instance.
Grab the shared-runner token on the `admin/runners` page of your GitLab CI Grab the shared-Runner token on the `admin/Runners` page of your GitLab CI
instance. instance.
![shared token](shared_runner.png) ![shared token](shared_Runner.png)
Now simply register the runner as any runner: Now simply register the Runner as any Runner:
``` ```
sudo gitlab-ci-multi-runner register sudo gitlab-ci-multi-Runner register
``` ```
Shared runners are enabled by default as of GitLab 8.2, but can be disabled with the Shared Runners are enabled by default as of GitLab 8.2, but can be disabled with the
`DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared runners to `DISABLE SHARED RunnerS` button. Previous versions of GitLab defaulted shared Runners to
disabled. disabled.
## Registering a Specific Runner ## Registering a Specific Runner
Registering a specific can be done in two ways: Registering a specific can be done in two ways:
1. Creating a runner with the project registration token 1. Creating a Runner with the project registration token
1. Converting a shared runner into a specific runner (one-way, admin only) 1. Converting a shared Runner into a specific Runner (one-way, admin only)
There are several ways to create a runner instance. The steps below only There are several ways to create a Runner instance. The steps below only
concern registering the runner on GitLab CI. concern registering the Runner on GitLab CI.
### Registering a Specific Runner with a Project Registration token ### Registering a Specific Runner with a Project Registration token
To create a specific runner without having admin rights to the GitLab instance, To create a specific Runner without having admin rights to the GitLab instance,
visit the project you want to make the runner work for in GitLab CI. visit the project you want to make the Runner work for in GitLab CI.
Click on the runner tab and use the registration token you find there to Click on the Runner tab and use the registration token you find there to
setup a specific runner for this project. setup a specific Runner for this project.
![project runners in GitLab CI](project_specific.png) ![project Runners in GitLab CI](project_specific.png)
To register the runner, run the command below and follow instructions: To register the Runner, run the command below and follow instructions:
``` ```
sudo gitlab-ci-multi-runner register sudo gitlab-ci-multi-Runner register
``` ```
### Lock a specific runner from being enabled for other projects ### Lock a specific Runner from being enabled for other projects
You can configure a runner to assign it exclusively to a project. When a You can configure a Runner to assign it exclusively to a project. When a
runner is locked this way, it can no longer be enabled for other projects. Runner is locked this way, it can no longer be enabled for other projects.
This setting is available on each runner in *Project Settings* > *Runners*. This setting is available on each Runner in *Project Settings* > *Runners*.
### Making an existing Shared Runner Specific ### Making an existing Shared Runner Specific
If you are an admin on your GitLab instance, If you are an admin on your GitLab instance,
you can make any shared runner a specific runner, _but you can not you can make any shared Runner a specific Runner, _but you can not
make a specific runner a shared runner_. make a specific Runner a shared Runner_.
To make a shared runner specific, go to the runner page (`/admin/runners`) To make a shared Runner specific, go to the Runner page (`/admin/Runners`)
and find your runner. Add any projects on the left to make this runner and find your Runner. Add any projects on the left to make this Runner
run exclusively for these projects, therefore making it a specific runner. run exclusively for these projects, therefore making it a specific Runner.
![making a shared runner specific](shared_to_specific_admin.png) ![making a shared Runner specific](shared_to_specific_admin.png)
## Using Shared Runners Effectively ## Using Shared Runners Effectively
If you are planning to use shared runners, there are several things you If you are planning to use shared Runners, there are several things you
should keep in mind. should keep in mind.
### Use Tags ### Use Tags
You must setup a runner to be able to run all the different types of jobs 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 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. 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 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. 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 For instance, at GitLab we have Runners tagged with "rails" if they contain
the appropriate dependencies to run Rails test suites. the appropriate dependencies to run Rails test suites.
### Prevent runner with tags from picking jobs without tags ### Prevent Runner with tags from picking jobs without tags
You can configure a runner to prevent it from picking jobs with tags when You can configure a Runner to prevent it from picking jobs with tags when
the runner does not have tags assigned. This setting is available on each the Runner does not have tags assigned. This setting is available on each
runner in *Project Settings* > *Runners*. Runner in *Project Settings* > *Runners*.
### Be careful with sensitive information ### Be careful with sensitive information
If you can run a build on a runner, you can get access to any code it runs If you can run a job 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 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. 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 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. to create a clone of a Runner and submit false jobs, for example.
The above is easily avoided by restricting the usage of shared runners The above is easily avoided by restricting the usage of shared Runners
on large public GitLab instances and controlling access to your GitLab instance. on large public GitLab instances and controlling access to your GitLab instance.
### Forks ### Forks
Whenever a project is forked, it copies the settings of the jobs that relate 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 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 someone forks that project, the shared Runners will also serve jobs of this
project. project.
## Attack vectors in Runners ## Attack vectors in Runners
Mentioned briefly earlier, but the following things of runners can be exploited. Mentioned briefly earlier, but the following things of Runners can be exploited.
We're always looking for contributions that can mitigate these [Security Considerations](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/security/index.md). We're always looking for contributions that can mitigate these
[Security Considerations](https://docs.gitlab.com/runner/security/).
doc/ci/services/mysql.md
View file @ a084437b
...@@ -31,7 +31,7 @@ Database: el_duderino ...@@ -31,7 +31,7 @@ Database: el_duderino
``` ```
If you are wondering why we used `mysql` for the `Host`, read more at If you are wondering why we used `mysql` for the `Host`, read more at
[How is service linked to the build](../docker/using_docker_images.md#how-is-service-linked-to-the-build). [How is service linked to the job](../docker/using_docker_images.md#how-is-service-linked-to-the-job).
You can also use any other docker image available on [Docker Hub][hub-mysql]. You can also use any other docker image available on [Docker Hub][hub-mysql].
For example, to use MySQL 5.5 the service becomes `mysql:5.5`. For example, to use MySQL 5.5 the service becomes `mysql:5.5`.
...@@ -112,7 +112,7 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly ...@@ -112,7 +112,7 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly
available [shared runners](../runners/README.md). available [shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin. moments the changes will be picked by a public runner and the job will begin.
[hub-mysql]: https://hub.docker.com/r/_/mysql/ [hub-mysql]: https://hub.docker.com/r/_/mysql/
[mysql-example-repo]: https://gitlab.com/gitlab-examples/mysql [mysql-example-repo]: https://gitlab.com/gitlab-examples/mysql
doc/ci/services/postgres.md
View file @ a084437b
...@@ -31,7 +31,7 @@ Database: nice_marmot ...@@ -31,7 +31,7 @@ Database: nice_marmot
``` ```
If you are wondering why we used `postgres` for the `Host`, read more at If you are wondering why we used `postgres` for the `Host`, read more at
[How is service linked to the build](../docker/using_docker_images.md#how-is-service-linked-to-the-build). [How is service linked to the job](../docker/using_docker_images.md#how-is-service-linked-to-the-job).
You can also use any other docker image available on [Docker Hub][hub-pg]. You can also use any other docker image available on [Docker Hub][hub-pg].
For example, to use PostgreSQL 9.3 the service becomes `postgres:9.3`. For example, to use PostgreSQL 9.3 the service becomes `postgres:9.3`.
...@@ -108,7 +108,7 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly ...@@ -108,7 +108,7 @@ convenience that runs on [GitLab.com](https://gitlab.com) using our publicly
available [shared runners](../runners/README.md). available [shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin. moments the changes will be picked by a public runner and the job will begin.
[hub-pg]: https://hub.docker.com/r/_/postgres/ [hub-pg]: https://hub.docker.com/r/_/postgres/
[postgres-example-repo]: https://gitlab.com/gitlab-examples/postgres [postgres-example-repo]: https://gitlab.com/gitlab-examples/postgres
doc/ci/services/redis.md
View file @ a084437b
...@@ -63,7 +63,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available ...@@ -63,7 +63,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md). [shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin. moments the changes will be picked by a public runner and the job will begin.
[hub-redis]: https://hub.docker.com/r/_/redis/ [hub-redis]: https://hub.docker.com/r/_/redis/
[redis-example-repo]: https://gitlab.com/gitlab-examples/redis [redis-example-repo]: https://gitlab.com/gitlab-examples/redis
doc/ci/ssh_keys/README.md
View file @ a084437b
...@@ -25,7 +25,7 @@ This is the universal solution which works with any type of executor ...@@ -25,7 +25,7 @@ This is the universal solution which works with any type of executor
1. Create a new SSH key pair with [ssh-keygen][] 1. Create a new SSH key pair with [ssh-keygen][]
2. Add the private key as a **Secret Variable** to the project 2. Add the private key as a **Secret Variable** to the project
3. Run the [ssh-agent][] during build to load the private key. 3. Run the [ssh-agent][] during job to load the private key.
## SSH keys when using the Docker executor ## SSH keys when using the Docker executor
...@@ -77,7 +77,7 @@ SSH key. ...@@ -77,7 +77,7 @@ SSH key.
You can generate the SSH key from the machine that GitLab Runner is installed You can generate the SSH key from the machine that GitLab Runner is installed
on, and use that key for all projects that are run on this machine. on, and use that key for all projects that are run on this machine.
First, you need to login to the server that runs your builds. First, you need to login to the server that runs your jobs.
Then from the terminal login as the `gitlab-runner` user and generate the SSH Then from the terminal login as the `gitlab-runner` user and generate the SSH
key pair as described in the [SSH keys documentation](../../ssh/README.md). key pair as described in the [SSH keys documentation](../../ssh/README.md).
...@@ -103,7 +103,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available ...@@ -103,7 +103,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
[shared runners](../runners/README.md). [shared runners](../runners/README.md).
Want to hack on it? Simply fork it, commit and push your changes. Within a few Want to hack on it? Simply fork it, commit and push your changes. Within a few
moments the changes will be picked by a public runner and the build will begin. moments the changes will be picked by a public runner and the job will begin.
[ssh-keygen]: http://linux.die.net/man/1/ssh-keygen [ssh-keygen]: http://linux.die.net/man/1/ssh-keygen
[ssh-agent]: http://linux.die.net/man/1/ssh-agent [ssh-agent]: http://linux.die.net/man/1/ssh-agent
......
doc/ci/triggers/README.md
View file @ a084437b
# Triggering Builds through the API # Triggering jobs through the API
> [Introduced][ci-229] in GitLab CE 7.14.
> **Note**: > **Note**:
GitLab 8.12 has a completely redesigned build permissions system. - [Introduced][ci-229] in GitLab CE 7.14.
Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#build-triggers). - GitLab 8.12 has a completely redesigned job permissions system. Read all
about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers).
Triggers can be used to force a rebuild of a specific `ref` (branch or tag) Triggers can be used to force a rebuild of a specific `ref` (branch or tag)
with an API call. with an API call.
## Add a trigger ## Add a trigger
You can add a new trigger by going to your project's **Settings > Triggers**. You can add a new trigger by going to your project's
The **Add trigger** button will create a new token which you can then use to **Settings ➔ CI/CD Pipelines ➔ Triggers**. The **Add trigger** button will
trigger a rebuild of this particular project. create a new token which you can then use to trigger a rerun of this
particular project's pipeline.
Every new trigger you create, gets assigned a different token which you can Every new trigger you create, gets assigned a different token which you can
then use inside your scripts or `.gitlab-ci.yml`. You also have a nice then use inside your scripts or `.gitlab-ci.yml`. You also have a nice
...@@ -27,13 +27,13 @@ You can revoke a trigger any time by going at your project's ...@@ -27,13 +27,13 @@ You can revoke a trigger any time by going at your project's
**Settings > Triggers** and hitting the **Revoke** button. The action is **Settings > Triggers** and hitting the **Revoke** button. The action is
irreversible. irreversible.
## Trigger a build ## Trigger a job
> **Note**: > **Note**:
Valid refs are only the branches and tags. If you pass a commit SHA as a ref, Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
it will not trigger a build. it will not trigger a job.
To trigger a build you need to send a `POST` request to GitLab's API endpoint: To trigger a job you need to send a `POST` request to GitLab's API endpoint:
``` ```
POST /projects/:id/trigger/builds POST /projects/:id/trigger/builds
...@@ -42,31 +42,32 @@ POST /projects/:id/trigger/builds ...@@ -42,31 +42,32 @@ POST /projects/:id/trigger/builds
The required parameters are the trigger's `token` and the Git `ref` on which The required parameters are the trigger's `token` and the Git `ref` on which
the trigger will be performed. Valid refs are the branch and the tag. The `:id` the trigger will be performed. Valid refs are the branch and the tag. The `:id`
of a project can be found by [querying the API](../../api/projects.md) of a project can be found by [querying the API](../../api/projects.md)
or by visiting the **Triggers** page which provides self-explanatory examples. or by visiting the **CI/CD Pipelines** settings page which provides
self-explanatory examples.
When a rebuild is triggered, the information is exposed in GitLab's UI under When a rerun of a pipeline is triggered, the information is exposed in GitLab's
the **Builds** page and the builds are marked as `triggered`. UI under the **Jobs** page and the jobs are marked as triggered 'by API'.
![Marked rebuilds as triggered on builds page](img/builds_page.png) ![Marked rebuilds as on jobs page](img/builds_page.png)
--- ---
You can see which trigger caused the rebuild by visiting the single build page. You can see which trigger caused the rebuild by visiting the single job page.
The token of the trigger is exposed in the UI as you can see from the image A part of the trigger's token is exposed in the UI as you can see from the image
below. below.
![Marked rebuilds as triggered on a single build page](img/trigger_single_build.png) ![Marked rebuilds as triggered on a single job page](img/trigger_single_build.png)
--- ---
See the [Examples](#examples) section for more details on how to actually See the [Examples](#examples) section for more details on how to actually
trigger a rebuild. trigger a rebuild.
## Trigger a build from webhook ## Trigger a job from webhook
> Introduced in GitLab 8.14. > Introduced in GitLab 8.14.
To trigger a build from webhook of another project you need to add the following To trigger a job from webhook of another project you need to add the following
webhook url for Push and Tag push events: webhook url for Push and Tag push events:
``` ```
...@@ -78,7 +79,7 @@ https://gitlab.example.com/api/v3/projects/:id/ref/:ref/trigger/builds?token=TOK ...@@ -78,7 +79,7 @@ https://gitlab.example.com/api/v3/projects/:id/ref/:ref/trigger/builds?token=TOK
from webhook body that designates the branchref that fired the trigger in the source repository. from webhook body that designates the branchref that fired the trigger in the source repository.
- `ref` should be url encoded if contains slashes. - `ref` should be url encoded if contains slashes.
## Pass build variables to a trigger ## Pass job variables to a trigger
You can pass any number of arbitrary variables in the trigger API call and they You can pass any number of arbitrary variables in the trigger API call and they
will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml` will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml`
...@@ -90,7 +91,7 @@ variables[key]=value ...@@ -90,7 +91,7 @@ variables[key]=value
This information is also exposed in the UI. This information is also exposed in the UI.
![Build variables in UI](img/trigger_variables.png) ![Job variables in UI](img/trigger_variables.png)
--- ---
...@@ -116,7 +117,7 @@ curl --request POST \ ...@@ -116,7 +117,7 @@ curl --request POST \
"https://gitlab.example.com/api/v3/projects/9/trigger/builds?token=TOKEN&ref=master" "https://gitlab.example.com/api/v3/projects/9/trigger/builds?token=TOKEN&ref=master"
``` ```
### Triggering a build within `.gitlab-ci.yml` ### Triggering a job within `.gitlab-ci.yml`
You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that
you have two projects, A and B, and you want to trigger a rebuild on the `master` you have two projects, A and B, and you want to trigger a rebuild on the `master`
...@@ -132,7 +133,7 @@ build_docs: ...@@ -132,7 +133,7 @@ build_docs:
- tags - tags
``` ```
Now, whenever a new tag is pushed on project A, the build will run and the Now, whenever a new tag is pushed on project A, the job will run and the
`build_docs` job will be executed, triggering a rebuild of project B. The `build_docs` job will be executed, triggering a rebuild of project B. The
`stage: deploy` ensures that this job will run only after all jobs with `stage: deploy` ensures that this job will run only after all jobs with
`stage: test` complete successfully. `stage: test` complete successfully.
...@@ -189,18 +190,18 @@ curl --request POST \ ...@@ -189,18 +190,18 @@ curl --request POST \
https://gitlab.example.com/api/v3/projects/9/trigger/builds https://gitlab.example.com/api/v3/projects/9/trigger/builds
``` ```
### Using webhook to trigger builds ### Using webhook to trigger job
You can add the following webhook to another project in order to trigger a build: You can add the following webhook to another project in order to trigger a job:
``` ```
https://gitlab.example.com/api/v3/projects/9/ref/master/trigger/builds?token=TOKEN&variables[UPLOAD_TO_S3]=true https://gitlab.example.com/api/v3/projects/9/ref/master/trigger/builds?token=TOKEN&variables[UPLOAD_TO_S3]=true
``` ```
### Using cron to trigger nightly builds ### Using cron to trigger nightly jobs
Whether you craft a script or just run cURL directly, you can trigger builds Whether you craft a script or just run cURL directly, you can trigger jobs
in conjunction with cron. The example below triggers a build on the `master` in conjunction with cron. The example below triggers a job on the `master`
branch of project with ID `9` every night at `00:30`: branch of project with ID `9` every night at `00:30`:
```bash ```bash
......
doc/ci/triggers/img/builds_page.png
View replaced file @ 6038355f View file @ a084437b
doc/ci/triggers/img/builds_page.png

28.4 KB | W: | H:

doc/ci/triggers/img/builds_page.png

19.9 KB | W: | H:

doc/ci/triggers/img/builds_page.png
doc/ci/triggers/img/builds_page.png
doc/ci/triggers/img/builds_page.png
doc/ci/triggers/img/builds_page.png
  • 2-up
  • Swipe
  • Onion skin
doc/ci/variables/README.md
View file @ a084437b
# Variables # Variables
When receiving a build from GitLab CI, the [Runner] prepares the build environment. When receiving a job from GitLab CI, the [Runner] prepares the build environment.
It starts by setting a list of **predefined variables** (environment variables) It starts by setting a list of **predefined variables** (environment variables)
and a list of **user-defined variables**. and a list of **user-defined variables**.
...@@ -29,22 +29,22 @@ version of Runner required. ...@@ -29,22 +29,22 @@ version of Runner required.
| Variable | GitLab | Runner | Description | | Variable | GitLab | Runner | Description |
|-------------------------|--------|--------|-------------| |-------------------------|--------|--------|-------------|
| **CI** | all | 0.4 | Mark that build is executed in CI environment | | **CI** | all | 0.4 | Mark that job is executed in CI environment |
| **GITLAB_CI** | all | all | Mark that build is executed in GitLab CI environment | | **GITLAB_CI** | all | all | Mark that job is executed in GitLab CI environment |
| **CI_SERVER** | all | all | Mark that build is executed in CI environment | | **CI_SERVER** | all | all | Mark that job is executed in CI environment |
| **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate builds | | **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate jobs |
| **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule builds | | **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule jobs |
| **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule builds | | **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule jobs |
| **CI_BUILD_ID** | all | all | The unique id of the current build that GitLab CI uses internally | | **CI_BUILD_ID** | all | all | The unique id of the current job that GitLab CI uses internally |
| **CI_BUILD_REF** | all | all | The commit revision for which project is built | | **CI_BUILD_REF** | all | all | The commit revision for which project is built |
| **CI_BUILD_TAG** | all | 0.5 | The commit tag name. Present only when building tags. | | **CI_BUILD_TAG** | all | 0.5 | The commit tag name. Present only when building tags. |
| **CI_BUILD_NAME** | all | 0.5 | The name of the build as defined in `.gitlab-ci.yml` | | **CI_BUILD_NAME** | all | 0.5 | The name of the job as defined in `.gitlab-ci.yml` |
| **CI_BUILD_STAGE** | all | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | | **CI_BUILD_STAGE** | all | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` |
| **CI_BUILD_REF_NAME** | all | all | The branch or tag name for which project is built | | **CI_BUILD_REF_NAME** | all | all | The branch or tag name for which project is built |
| **CI_BUILD_REF_SLUG** | 8.15 | all | `$CI_BUILD_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | | **CI_BUILD_REF_SLUG** | 8.15 | all | `$CI_BUILD_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. |
| **CI_BUILD_REPO** | all | all | The URL to clone the Git repository | | **CI_BUILD_REPO** | all | all | The URL to clone the Git repository |
| **CI_BUILD_TRIGGERED** | all | 0.5 | The flag to indicate that build was [triggered] | | **CI_BUILD_TRIGGERED** | all | 0.5 | The flag to indicate that job was [triggered] |
| **CI_BUILD_MANUAL** | 8.12 | all | The flag to indicate that build was manually started | | **CI_BUILD_MANUAL** | 8.12 | all | The flag to indicate that job was manually started |
| **CI_BUILD_TOKEN** | all | 1.2 | Token used for authenticating with the GitLab Container Registry | | **CI_BUILD_TOKEN** | all | 1.2 | Token used for authenticating with the GitLab Container Registry |
| **CI_PIPELINE_ID** | 8.10 | 0.5 | The unique id of the current pipeline that GitLab CI uses internally | | **CI_PIPELINE_ID** | 8.10 | 0.5 | The unique id of the current pipeline that GitLab CI uses internally |
| **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally | | **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally |
...@@ -52,8 +52,8 @@ version of Runner required. ...@@ -52,8 +52,8 @@ version of Runner required.
| **CI_PROJECT_NAMESPACE**| 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built | | **CI_PROJECT_NAMESPACE**| 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built |
| **CI_PROJECT_PATH** | 8.10 | 0.5 | The namespace with project name | | **CI_PROJECT_PATH** | 8.10 | 0.5 | The namespace with project name |
| **CI_PROJECT_URL** | 8.10 | 0.5 | The HTTP address to access project | | **CI_PROJECT_URL** | 8.10 | 0.5 | The HTTP address to access project |
| **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the build is run | | **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run |
| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this build | | **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job |
| **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. | | **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. |
| **CI_REGISTRY** | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry | | **CI_REGISTRY** | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry |
| **CI_REGISTRY_IMAGE** | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project | | **CI_REGISTRY_IMAGE** | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project |
...@@ -61,11 +61,11 @@ version of Runner required. ...@@ -61,11 +61,11 @@ version of Runner required.
| **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5 | The description of the runner as saved in GitLab | | **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5 | The description of the runner as saved in GitLab |
| **CI_RUNNER_TAGS** | 8.10 | 0.5 | The defined runner tags | | **CI_RUNNER_TAGS** | 8.10 | 0.5 | The defined runner tags |
| **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | | **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled |
| **GET_SOURCES_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to fetch sources running a build | | **GET_SOURCES_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to fetch sources running a job |
| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a build | | **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job |
| **RESTORE_CACHE_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to restore the cache running a build | | **RESTORE_CACHE_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to restore the cache running a job |
| **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the build | | **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the job |
| **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the build | | **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the job |
Example values: Example values:
...@@ -136,7 +136,7 @@ job_name: ...@@ -136,7 +136,7 @@ job_name:
>**Notes:** >**Notes:**
- This feature requires GitLab Runner 0.4.0 or higher. - This feature requires GitLab Runner 0.4.0 or higher.
- Be aware that secret variables are not masked, and their values can be shown - Be aware that secret variables are not masked, and their values can be shown
in the build logs if explicitly asked to do so. If your project is public or in the job logs if explicitly asked to do so. If your project is public or
internal, you can set the pipelines private from your project's Pipelines internal, you can set the pipelines private from your project's Pipelines
settings. Follow the discussion in issue [#13784][ce-13784] for masking the settings. Follow the discussion in issue [#13784][ce-13784] for masking the
secret variables. secret variables.
...@@ -150,7 +150,7 @@ storing things like passwords, secret keys and credentials. ...@@ -150,7 +150,7 @@ storing things like passwords, secret keys and credentials.
Secret variables can be added by going to your project's Secret variables can be added by going to your project's
**Settings ➔ Variables ➔ Add variable**. **Settings ➔ Variables ➔ Add variable**.
Once you set them, they will be available for all subsequent builds. Once you set them, they will be available for all subsequent jobs.
## Deployment variables ## Deployment variables
...@@ -160,7 +160,7 @@ This feature requires GitLab CI 8.15 or higher. ...@@ -160,7 +160,7 @@ This feature requires GitLab CI 8.15 or higher.
[Project services](../../user/project/integrations/project_services.md) that are [Project services](../../user/project/integrations/project_services.md) that are
responsible for deployment configuration may define their own variables that responsible for deployment configuration may define their own variables that
are set in the build environment. These variables are only defined for are set in the build environment. These variables are only defined for
[deployment builds](../environments.md). Please consult the documentation of [deployment jobs](../environments.md). Please consult the documentation of
the project services that you are using to learn which variables they define. the project services that you are using to learn which variables they define.
An example project service that defines deployment variables is An example project service that defines deployment variables is
...@@ -173,21 +173,21 @@ An example project service that defines deployment variables is ...@@ -173,21 +173,21 @@ An example project service that defines deployment variables is
> **WARNING:** Enabling debug tracing can have severe security implications. The > **WARNING:** Enabling debug tracing can have severe security implications. The
output **will** contain the content of all your secret variables and any other output **will** contain the content of all your secret variables and any other
secrets! The output **will** be uploaded to the GitLab server and made visible secrets! The output **will** be uploaded to the GitLab server and made visible
in build traces! in job traces!
By default, GitLab Runner hides most of the details of what it is doing when By default, GitLab Runner hides most of the details of what it is doing when
processing a job. This behaviour keeps build traces short, and prevents secrets processing a job. This behaviour keeps job traces short, and prevents secrets
from being leaked into the trace unless your script writes them to the screen. from being leaked into the trace unless your script writes them to the screen.
If a job isn't working as expected, this can make the problem difficult to If a job isn't working as expected, this can make the problem difficult to
investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`. investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`.
Available on GitLab Runner v1.7+, this feature enables the shell's execution Available on GitLab Runner v1.7+, this feature enables the shell's execution
trace, resulting in a verbose build trace listing all commands that were run, trace, resulting in a verbose job trace listing all commands that were run,
variables that were set, etc. variables that were set, etc.
Before enabling this, you should ensure builds are visible to Before enabling this, you should ensure jobs are visible to
[team members only](../../user/permissions.md#project-features). You should [team members only](../../user/permissions.md#project-features). You should
also [erase](../pipelines.md#seeing-build-status) all generated build traces also [erase](../pipelines.md#seeing-build-status) all generated job traces
before making them visible again. before making them visible again.
To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`: To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`:
...@@ -320,7 +320,7 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw' ...@@ -320,7 +320,7 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'
All variables are set as environment variables in the build environment, and All variables are set as environment variables in the build environment, and
they are accessible with normal methods that are used to access such variables. they are accessible with normal methods that are used to access such variables.
In most cases `bash` or `sh` is used to execute the build script. In most cases `bash` or `sh` is used to execute the job script.
To access the variables (predefined and user-defined) in a `bash`/`sh` environment, To access the variables (predefined and user-defined) in a `bash`/`sh` environment,
prefix the variable name with the dollar sign (`$`): prefix the variable name with the dollar sign (`$`):
...@@ -328,12 +328,12 @@ prefix the variable name with the dollar sign (`$`): ...@@ -328,12 +328,12 @@ prefix the variable name with the dollar sign (`$`):
``` ```
job_name: job_name:
script: script:
- echo $CI_BUILD_ID - echo $CI_job_ID
``` ```
You can also list all environment variables with the `export` command, You can also list all environment variables with the `export` command,
but be aware that this will also expose the values of all the secret variables but be aware that this will also expose the values of all the secret variables
you set, in the build log: you set, in the job log:
``` ```
job_name: job_name:
...@@ -344,4 +344,4 @@ job_name: ...@@ -344,4 +344,4 @@ job_name:
[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 [ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784
[runner]: https://docs.gitlab.com/runner/ [runner]: https://docs.gitlab.com/runner/
[triggered]: ../triggers/README.md [triggered]: ../triggers/README.md
[triggers]: ../triggers/README.md#pass-build-variables-to-a-trigger [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger
doc/ci/yaml/README.md
View file @ a084437b
# Configuration of your builds with .gitlab-ci.yml # Configuration of your jobs with .gitlab-ci.yml
This document describes the usage of `.gitlab-ci.yml`, the file that is used by This document describes the usage of `.gitlab-ci.yml`, the file that is used by
GitLab Runner to manage your project's builds. GitLab Runner to manage your project's jobs.
If you want a quick introduction to GitLab CI, follow our If you want a quick introduction to GitLab CI, follow our
[quick start guide](../quick_start/README.md). [quick start guide](../quick_start/README.md).
...@@ -30,10 +30,9 @@ jobs, where each of the jobs executes a different command. ...@@ -30,10 +30,9 @@ jobs, where each of the jobs executes a different command.
Of course a command can execute code directly (`./configure;make;make install`) Of course a command can execute code directly (`./configure;make;make install`)
or run a script (`test.sh`) in the repository. or run a script (`test.sh`) in the repository.
Jobs are used to create builds, which are then picked up by Jobs are picked up by [Runners](../runners/README.md) and executed within the
[Runners](../runners/README.md) and executed within the environment of the environment of the Runner. What is important, is that each job is run
Runner. What is important, is that each job is run independently from each independently from each other.
other.
The YAML syntax allows for using more complex job specifications than in the The YAML syntax allows for using more complex job specifications than in the
above example: above example:
...@@ -80,30 +79,31 @@ There are a few reserved `keywords` that **cannot** be used as job names: ...@@ -80,30 +79,31 @@ There are a few reserved `keywords` that **cannot** be used as job names:
### image and services ### image and services
This allows to specify a custom Docker image and a list of services that can be This allows to specify a custom Docker image and a list of services that can be
used for time of the build. The configuration of this feature is covered in used for time of the job. The configuration of this feature is covered in
[a separate document](../docker/README.md). [a separate document](../docker/README.md).
### before_script ### before_script
`before_script` is used to define the command that should be run before all `before_script` is used to define the command that should be run before all
builds, including deploy builds, but after the restoration of artifacts. This can be an array or a multi-line string. jobs, including deploy jobs, but after the restoration of artifacts. This can
be an array or a multi-line string.
### after_script ### after_script
> Introduced in GitLab 8.7 and requires Gitlab Runner v1.2 > Introduced in GitLab 8.7 and requires Gitlab Runner v1.2
`after_script` is used to define the command that will be run after for all `after_script` is used to define the command that will be run after for all
builds. This has to be an array or a multi-line string. jobs. This has to be an array or a multi-line string.
### stages ### stages
`stages` is used to define build stages that can be used by jobs. `stages` is used to define stages that can be used by jobs.
The specification of `stages` allows for having flexible multi stage pipelines. The specification of `stages` allows for having flexible multi stage pipelines.
The ordering of elements in `stages` defines the ordering of builds' execution: The ordering of elements in `stages` defines the ordering of jobs' execution:
1. Builds of the same stage are run in parallel. 1. Jobs of the same stage are run in parallel.
1. Builds of the next stage are run after the jobs from the previous stage 1. Jobs of the next stage are run after the jobs from the previous stage
complete successfully. complete successfully.
Let's consider the following example, which defines 3 stages: Let's consider the following example, which defines 3 stages:
...@@ -115,7 +115,7 @@ stages: ...@@ -115,7 +115,7 @@ stages:
- deploy - deploy
``` ```
1. First all jobs of `build` are executed in parallel. 1. First, all jobs of `build` are executed in parallel.
1. If all jobs of `build` succeed, the `test` jobs are executed in parallel. 1. If all jobs of `build` succeed, the `test` jobs are executed in parallel.
1. If all jobs of `test` succeed, the `deploy` jobs are executed in parallel. 1. If all jobs of `test` succeed, the `deploy` jobs are executed in parallel.
1. If all jobs of `deploy` succeed, the commit is marked as `success`. 1. If all jobs of `deploy` succeed, the commit is marked as `success`.
...@@ -124,7 +124,7 @@ stages: ...@@ -124,7 +124,7 @@ stages:
There are also two edge cases worth mentioning: There are also two edge cases worth mentioning:
1. If no `stages` are defined in `.gitlab-ci.yml`, then by default the `build`, 1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`,
`test` and `deploy` are allowed to be used as job's stage by default. `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. 2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
...@@ -137,7 +137,7 @@ Alias for [stages](#stages). ...@@ -137,7 +137,7 @@ Alias for [stages](#stages).
> Introduced in GitLab Runner v0.5.0. > Introduced in GitLab Runner v0.5.0.
GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
build environment. The variables are stored in the Git repository and are meant job environment. The variables are stored in the Git repository and are meant
to store non-sensitive project configuration, for example: to store non-sensitive project configuration, for example:
```yaml ```yaml
...@@ -163,7 +163,7 @@ which can be set in GitLab's UI. ...@@ -163,7 +163,7 @@ which can be set in GitLab's UI.
> Introduced in GitLab Runner v0.7.0. > Introduced in GitLab Runner v0.7.0.
`cache` is used to specify a list of files and directories which should be `cache` is used to specify a list of files and directories which should be
cached between builds. You can only use paths that are within the project cached between jobs. You can only use paths that are within the project
workspace. workspace.
**By default the caching is enabled per-job and per-branch.** **By default the caching is enabled per-job and per-branch.**
...@@ -202,8 +202,8 @@ rspec: ...@@ -202,8 +202,8 @@ rspec:
- binaries/ - binaries/
``` ```
Locally defined cache overwrites globally defined options. This will cache only Locally defined cache overwrites globally defined options. The following `rspec`
`binaries/`: job will cache only `binaries/`:
```yaml ```yaml
cache: cache:
...@@ -281,8 +281,8 @@ cache: ...@@ -281,8 +281,8 @@ cache:
## Jobs ## Jobs
`.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job
must have a unique name, which is not one of the Keywords mentioned above. must have a unique name, which is not one of the keywords mentioned above.
A job is defined by a list of parameters that define the build behavior. A job is defined by a list of parameters that define the job behavior.
```yaml ```yaml
job_name: job_name:
...@@ -305,20 +305,20 @@ job_name: ...@@ -305,20 +305,20 @@ job_name:
| script | yes | Defines a shell script which is executed by Runner | | script | yes | Defines a shell script which is executed by Runner |
| image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| stage | no | Defines a build stage (default: `test`) | | stage | no | Defines a job stage (default: `test`) |
| type | no | Alias for `stage` | | type | no | Alias for `stage` |
| variables | no | Define build variables on a job level | | variables | no | Define job variables on a job level |
| only | no | Defines a list of git refs for which build is created | | only | no | Defines a list of git refs for which job is created |
| except | no | Defines a list of git refs for which build is not created | | except | no | Defines a list of git refs for which job is not created |
| tags | no | Defines a list of tags which are used to select Runner | | tags | no | Defines a list of tags which are used to select Runner |
| allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status | | allow_failure | no | Allow job to fail. Failed job doesn't contribute to commit status |
| when | no | Define when to run build. Can be `on_success`, `on_failure`, `always` or `manual` | | when | no | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` |
| dependencies | no | Define other builds that a build depends on so that you can pass artifacts between them| | dependencies | no | Define other jobs that a job depends on so that you can pass artifacts between them|
| artifacts | no | Define list of build artifacts | | artifacts | no | Define list of [job artifacts](../../user/project/pipelines/job_artifacts.md) |
| cache | no | Define list of files that should be cached between subsequent runs | | cache | no | Define list of files that should be cached between subsequent runs |
| before_script | no | Override a set of commands that are executed before build | | before_script | no | Override a set of commands that are executed before job |
| after_script | no | Override a set of commands that are executed after build | | after_script | no | Override a set of commands that are executed after job |
| environment | no | Defines a name of environment to which deployment is done by this build | | environment | no | Defines a name of environment to which deployment is done by this job |
| coverage | no | Define code coverage settings for a given job | | coverage | no | Define code coverage settings for a given job |
### script ### script
...@@ -339,11 +339,15 @@ job: ...@@ -339,11 +339,15 @@ job:
- bundle exec rspec - bundle exec rspec
``` ```
Sometimes, `script` commands will need to be wrapped in single or double quotes. For example, commands that contain a colon (`:`) need to be wrapped in quotes so that the YAML parser knows to interpret the whole thing as a string rather than a "key: value" pair. Be careful when using special characters (`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``). Sometimes, `script` commands will need to be wrapped in single or double quotes.
For example, commands that contain a colon (`:`) need to be wrapped in quotes so
that the YAML parser knows to interpret the whole thing as a string rather than
a "key: value" pair. Be careful when using special characters:
`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
### stage ### stage
`stage` allows to group build into different stages. Builds of the same `stage` `stage` allows to group jobs into different stages. Jobs of the same `stage`
are executed in `parallel`. For more info about the use of `stage` please check are executed in `parallel`. For more info about the use of `stage` please check
[stages](#stages). [stages](#stages).
...@@ -352,10 +356,9 @@ are executed in `parallel`. For more info about the use of `stage` please check ...@@ -352,10 +356,9 @@ are executed in `parallel`. For more info about the use of `stage` please check
`only` and `except` are two parameters that set a refs policy to limit when `only` and `except` are two parameters that set a refs policy to limit when
jobs are built: jobs are built:
1. `only` defines the names of branches and tags for which the job will be 1. `only` defines the names of branches and tags for which the job will run.
built.
2. `except` defines the names of branches and tags for which the job will 2. `except` defines the names of branches and tags for which the job will
**not** be built. **not** run.
There are a few rules that apply to the usage of refs policy: There are a few rules that apply to the usage of refs policy:
...@@ -379,8 +382,8 @@ job: ...@@ -379,8 +382,8 @@ job:
- branches - branches
``` ```
In this example, `job` will run only for refs that are tagged, or if a build is explicitly requested In this example, `job` will run only for refs that are tagged, or if a build is
via an API trigger. explicitly requested via an API trigger.
```yaml ```yaml
job: job:
...@@ -404,14 +407,14 @@ job: ...@@ -404,14 +407,14 @@ job:
The above example will run `job` for all branches on `gitlab-org/gitlab-ce`, The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
except master. except master.
### job variables ### Job variables
It is possible to define build variables using a `variables` keyword on a job It is possible to define job variables using a `variables` keyword on a job
level. It works basically the same way as its [global-level equivalent](#variables) level. It works basically the same way as its [global-level equivalent](#variables),
but allows you to define job-specific build variables. but allows you to define job-specific variables.
When the `variables` keyword is used on a job level, it overrides global YAML When the `variables` keyword is used on a job level, it overrides the global YAML
build variables and predefined variables. To turn off global defined variables job variables and predefined ones. To turn off global defined variables
in your job, define an empty array: in your job, define an empty array:
```yaml ```yaml
...@@ -419,8 +422,7 @@ job_name: ...@@ -419,8 +422,7 @@ job_name:
variables: [] variables: []
``` ```
Build variables priority is defined in the Job variables priority is defined in the [variables documentation][variables].
[variables documentation][variables].
### tags ### tags
...@@ -430,7 +432,7 @@ allowed to run this project. ...@@ -430,7 +432,7 @@ allowed to run this project.
During the registration of a Runner, you can specify the Runner's tags, for During the registration of a Runner, you can specify the Runner's tags, for
example `ruby`, `postgres`, `development`. example `ruby`, `postgres`, `development`.
`tags` allow you to run builds with Runners that have the specified tags `tags` allow you to run jobs with Runners that have the specified tags
assigned to them: assigned to them:
```yaml ```yaml
...@@ -445,13 +447,13 @@ has both `ruby` AND `postgres` tags defined. ...@@ -445,13 +447,13 @@ has both `ruby` AND `postgres` tags defined.
### allow_failure ### allow_failure
`allow_failure` is used when you want to allow a build to fail without impacting `allow_failure` is used when you want to allow a job to fail without impacting
the rest of the CI suite. Failed builds don't contribute to the commit status. the rest of the CI suite. Failed jobs don't contribute to the commit status.
When enabled and the build fails, the pipeline will be successful/green for all When enabled and the job fails, the pipeline will be successful/green for all
intents and purposes, but a "CI build passed with warnings" message will be intents and purposes, but a "CI build passed with warnings" message will be
displayed on the merge request or commit or build page. This is to be used by displayed on the merge request or commit or job page. This is to be used by
builds that are allowed to fail, but where failure indicates some other (manual) jobs that are allowed to fail, but where failure indicates some other (manual)
steps should be taken elsewhere. steps should be taken elsewhere.
In the example below, `job1` and `job2` will run in parallel, but if `job1` In the example below, `job1` and `job2` will run in parallel, but if `job1`
...@@ -483,12 +485,12 @@ failure. ...@@ -483,12 +485,12 @@ failure.
`when` can be set to one of the following values: `when` can be set to one of the following values:
1. `on_success` - execute build only when all builds from prior stages 1. `on_success` - execute job only when all jobs from prior stages
succeed. This is the default. succeed. This is the default.
1. `on_failure` - execute build only when at least one build from prior stages 1. `on_failure` - execute job only when at least one job from prior stages
fails. fails.
1. `always` - execute build regardless of the status of builds from prior stages. 1. `always` - execute job regardless of the status of jobs from prior stages.
1. `manual` - execute build manually (added in GitLab 8.10). Read about 1. `manual` - execute job manually (added in GitLab 8.10). Read about
[manual actions](#manual-actions) below. [manual actions](#manual-actions) below.
For example: For example:
...@@ -526,7 +528,7 @@ deploy_job: ...@@ -526,7 +528,7 @@ deploy_job:
cleanup_job: cleanup_job:
stage: cleanup stage: cleanup
script: script:
- cleanup after builds - cleanup after jobs
when: always when: always
``` ```
...@@ -552,10 +554,11 @@ Read more at the [environments documentation][env-manual]. ...@@ -552,10 +554,11 @@ Read more at the [environments documentation][env-manual].
### environment ### environment
> Introduced in GitLab 8.9. >
**Notes:**
> You can read more about environments and find more examples in the - Introduced in GitLab 8.9.
[documentation about environments][environment]. - You can read more about environments and find more examples in the
[documentation about environments][environment].
`environment` is used to define that a job deploys to a specific environment. `environment` is used to define that a job deploys to a specific environment.
If `environment` is specified and no environment under that name exists, a new If `environment` is specified and no environment under that name exists, a new
...@@ -563,7 +566,7 @@ one will be created automatically. ...@@ -563,7 +566,7 @@ one will be created automatically.
In its simplest form, the `environment` keyword can be defined like: In its simplest form, the `environment` keyword can be defined like:
``` ```yaml
deploy to production: deploy to production:
stage: deploy stage: deploy
script: git push production HEAD:master script: git push production HEAD:master
...@@ -576,12 +579,12 @@ deployment to the `production` environment. ...@@ -576,12 +579,12 @@ deployment to the `production` environment.
#### environment:name #### environment:name
> Introduced in GitLab 8.11. >
**Notes:**
>**Note:** - Introduced in GitLab 8.11.
Before GitLab 8.11, the name of an environment could be defined as a string like - Before GitLab 8.11, the name of an environment could be defined as a string like
`environment: production`. The recommended way now is to define it under the `environment: production`. The recommended way now is to define it under the
`name` keyword. `name` keyword.
The `environment` name can contain: The `environment` name can contain:
...@@ -602,7 +605,7 @@ Instead of defining the name of the environment right after the `environment` ...@@ -602,7 +605,7 @@ Instead of defining the name of the environment right after the `environment`
keyword, it is also possible to define it as a separate value. For that, use keyword, it is also possible to define it as a separate value. For that, use
the `name` keyword under `environment`: the `name` keyword under `environment`:
``` ```yaml
deploy to production: deploy to production:
stage: deploy stage: deploy
script: git push production HEAD:master script: git push production HEAD:master
...@@ -612,11 +615,11 @@ deploy to production: ...@@ -612,11 +615,11 @@ deploy to production:
#### environment:url #### environment:url
> Introduced in GitLab 8.11. >
**Notes:**
>**Note:** - Introduced in GitLab 8.11.
Before GitLab 8.11, the URL could be added only in GitLab's UI. The - Before GitLab 8.11, the URL could be added only in GitLab's UI. The
recommended way now is to define it in `.gitlab-ci.yml`. recommended way now is to define it in `.gitlab-ci.yml`.
This is an optional value that when set, it exposes buttons in various places This is an optional value that when set, it exposes buttons in various places
in GitLab which when clicked take you to the defined URL. in GitLab which when clicked take you to the defined URL.
...@@ -625,7 +628,7 @@ In the example below, if the job finishes successfully, it will create buttons ...@@ -625,7 +628,7 @@ In the example below, if the job finishes successfully, it will create buttons
in the merge requests and in the environments/deployments pages which will point in the merge requests and in the environments/deployments pages which will point
to `https://prod.example.com`. to `https://prod.example.com`.
``` ```yaml
deploy to production: deploy to production:
stage: deploy stage: deploy
script: git push production HEAD:master script: git push production HEAD:master
...@@ -690,8 +693,10 @@ The `stop_review_app` job is **required** to have the following keywords defined ...@@ -690,8 +693,10 @@ The `stop_review_app` job is **required** to have the following keywords defined
#### dynamic environments #### dynamic environments
> [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. >
`$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15 **Notes:**
- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
`environment` can also represent a configuration hash with `name` and `url`. `environment` can also represent a configuration hash with `name` and `url`.
These parameters can use any of the defined [CI variables](#variables) These parameters can use any of the defined [CI variables](#variables)
...@@ -699,7 +704,7 @@ These parameters can use any of the defined [CI variables](#variables) ...@@ -699,7 +704,7 @@ These parameters can use any of the defined [CI variables](#variables)
For example: For example:
``` ```yaml
deploy as review app: deploy as review app:
stage: deploy stage: deploy
script: make deploy script: make deploy
...@@ -714,28 +719,27 @@ is an [environment variable][variables] set by the Runner. The ...@@ -714,28 +719,27 @@ is an [environment variable][variables] set by the Runner. The
`$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable
for inclusion in URLs. In this case, if the `deploy as review app` job was run for inclusion in URLs. In this case, if the `deploy as review app` job was run
in a branch named `pow`, this environment would be accessible with an URL like in a branch named `pow`, this environment would be accessible with an URL like
`https://review-pow-aaaaaa.example.com/`. `https://review-pow.example.com/`.
This of course implies that the underlying server which hosts the application This of course implies that the underlying server which hosts the application
is properly configured. is properly configured.
The common use case is to create dynamic environments for branches and use them The common use case is to create dynamic environments for branches and use them
as Review Apps. You can see a simple example using Review Apps at as Review Apps. You can see a simple example using Review Apps at
https://gitlab.com/gitlab-examples/review-apps-nginx/. <https://gitlab.com/gitlab-examples/review-apps-nginx/>.
### artifacts ### artifacts
>**Notes:**
> >
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. **Notes:**
> - Windows support was added in GitLab Runner v.1.0.0. - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
> - Currently not all executors are supported. - Windows support was added in GitLab Runner v.1.0.0.
> - Build artifacts are only collected for successful builds by default. - Currently not all executors are supported.
- Job artifacts are only collected for successful jobs by default.
`artifacts` is used to specify a list of files and directories which should be `artifacts` is used to specify a list of files and directories which should be
attached to the build after success. You can only use paths that are within the attached to the job after success. You can only use paths that are within the
project workspace. To pass artifacts between different builds, see [dependencies](#dependencies). project workspace. To pass artifacts between different jobs, see [dependencies](#dependencies).
Below are some examples. Below are some examples.
Send all files in `binaries` and `.config`: Send all files in `binaries` and `.config`:
...@@ -794,7 +798,7 @@ release-job: ...@@ -794,7 +798,7 @@ release-job:
- tags - tags
``` ```
The artifacts will be sent to GitLab after a successful build and will The artifacts will be sent to GitLab after the job finishes successfully and will
be available for download in the GitLab UI. be available for download in the GitLab UI.
#### artifacts:name #### artifacts:name
...@@ -811,7 +815,7 @@ The default name is `artifacts`, which becomes `artifacts.zip` when downloaded. ...@@ -811,7 +815,7 @@ The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
**Example configurations** **Example configurations**
To create an archive with a name of the current build: To create an archive with a name of the current job:
```yaml ```yaml
job: job:
...@@ -829,7 +833,7 @@ job: ...@@ -829,7 +833,7 @@ job:
untracked: true untracked: true
``` ```
To create an archive with a name of the current build and the current branch or To create an archive with a name of the current job and the current branch or
tag including only the files that are untracked by Git: tag including only the files that are untracked by Git:
```yaml ```yaml
...@@ -864,20 +868,20 @@ job: ...@@ -864,20 +868,20 @@ job:
> Introduced in GitLab 8.9 and GitLab Runner v1.3.0. > Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
`artifacts:when` is used to upload artifacts on build failure or despite the `artifacts:when` is used to upload artifacts on job failure or despite the
failure. failure.
`artifacts:when` can be set to one of the following values: `artifacts:when` can be set to one of the following values:
1. `on_success` - upload artifacts only when the build succeeds. This is the default. 1. `on_success` - upload artifacts only when the job succeeds. This is the default.
1. `on_failure` - upload artifacts only when the build fails. 1. `on_failure` - upload artifacts only when the job fails.
1. `always` - upload artifacts regardless of the build status. 1. `always` - upload artifacts regardless of the job status.
--- ---
**Example configurations** **Example configurations**
To upload artifacts only when build fails. To upload artifacts only when job fails.
```yaml ```yaml
job: job:
...@@ -894,13 +898,14 @@ time. By default, artifacts are stored on GitLab forever. `expire_in` allows you ...@@ -894,13 +898,14 @@ time. By default, artifacts are stored on GitLab forever. `expire_in` allows you
to specify how long artifacts should live before they expire, counting from the to specify how long artifacts should live before they expire, counting from the
time they are uploaded and stored on GitLab. time they are uploaded and stored on GitLab.
You can use the **Keep** button on the build page to override expiration and You can use the **Keep** button on the job page to override expiration and
keep artifacts forever. keep artifacts forever.
After expiry, artifacts are actually deleted hourly by default (via a cron job), After expiry, artifacts are actually deleted hourly by default (via a cron job),
but they are not accessible after expiry. but they are not accessible after expiry.
The value of `expire_in` is an elapsed time. Examples of parseable values: The value of `expire_in` is an elapsed time. Examples of parseable values:
- '3 mins 4 sec' - '3 mins 4 sec'
- '2 hrs 20 min' - '2 hrs 20 min'
- '2h20min' - '2h20min'
...@@ -925,14 +930,14 @@ job: ...@@ -925,14 +930,14 @@ job:
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. > Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
This feature should be used in conjunction with [`artifacts`](#artifacts) and This feature should be used in conjunction with [`artifacts`](#artifacts) and
allows you to define the artifacts to pass between different builds. allows you to define the artifacts to pass between different jobs.
Note that `artifacts` from all previous [stages](#stages) are passed by default. Note that `artifacts` from all previous [stages](#stages) are passed by default.
To use this feature, define `dependencies` in context of the job and pass To use this feature, define `dependencies` in context of the job and pass
a list of all previous builds from which the artifacts should be downloaded. a list of all previous jobs from which the artifacts should be downloaded.
You can only define builds from stages that are executed before the current one. You can only define jobs from stages that are executed before the current one.
An error will be shown if you define builds from the current stage or next ones. An error will be shown if you define jobs from the current stage or next ones.
Defining an empty array will skip downloading any artifacts for that job. Defining an empty array will skip downloading any artifacts for that job.
--- ---
...@@ -942,7 +947,7 @@ In the following example, we define two jobs with artifacts, `build:osx` and ...@@ -942,7 +947,7 @@ In the following example, we define two jobs with artifacts, `build:osx` and
will be downloaded and extracted in the context of the build. The same happens will be downloaded and extracted in the context of the build. The same happens
for `test:linux` and artifacts from `build:linux`. for `test:linux` and artifacts from `build:linux`.
The job `deploy` will download artifacts from all previous builds because of The job `deploy` will download artifacts from all previous jobs because of
the [stage](#stages) precedence: the [stage](#stages) precedence:
```yaml ```yaml
...@@ -979,7 +984,7 @@ deploy: ...@@ -979,7 +984,7 @@ deploy:
### before_script and after_script ### before_script and after_script
It's possible to overwrite globally defined `before_script` and `after_script`: It's possible to overwrite the globally defined `before_script` and `after_script`:
```yaml ```yaml
before_script: before_script:
...@@ -1027,7 +1032,7 @@ There are three possible values: `clone`, `fetch`, and `none`. ...@@ -1027,7 +1032,7 @@ There are three possible values: `clone`, `fetch`, and `none`.
`clone` is the slowest option. It clones the repository from scratch for every `clone` is the slowest option. It clones the repository from scratch for every
job, ensuring that the project workspace is always pristine. job, ensuring that the project workspace is always pristine.
``` ```yaml
variables: variables:
GIT_STRATEGY: clone GIT_STRATEGY: clone
``` ```
...@@ -1036,7 +1041,7 @@ variables: ...@@ -1036,7 +1041,7 @@ variables:
if it doesn't exist). `git clean` is used to undo any changes made by the last if it doesn't exist). `git clean` is used to undo any changes made by the last
job, and `git fetch` is used to retrieve commits made since the last job ran. job, and `git fetch` is used to retrieve commits made since the last job ran.
``` ```yaml
variables: variables:
GIT_STRATEGY: fetch GIT_STRATEGY: fetch
``` ```
...@@ -1047,7 +1052,7 @@ for jobs that operate exclusively on artifacts (e.g., `deploy`). Git repository ...@@ -1047,7 +1052,7 @@ for jobs that operate exclusively on artifacts (e.g., `deploy`). Git repository
data may be present, but it is certain to be out of date, so you should only data may be present, but it is certain to be out of date, so you should only
rely on files brought into the project workspace from cache or artifacts. rely on files brought into the project workspace from cache or artifacts.
``` ```yaml
variables: variables:
GIT_STRATEGY: none GIT_STRATEGY: none
``` ```
...@@ -1061,56 +1066,59 @@ submodules are included when fetching the code before a build. Like ...@@ -1061,56 +1066,59 @@ submodules are included when fetching the code before a build. Like
`GIT_STRATEGY`, it can be set in either the global [`variables`](#variables) `GIT_STRATEGY`, it can be set in either the global [`variables`](#variables)
section or the [`variables`](#job-variables) section for individual jobs. section or the [`variables`](#job-variables) section for individual jobs.
There are three posible values: `none`, `normal`, and `recursive`: There are three possible values: `none`, `normal`, and `recursive`:
- `none` means that submodules will not be included when fetching the project - `none` means that submodules will not be included when fetching the project
code. This is the default, which matches the pre-v1.10 behavior. code. This is the default, which matches the pre-v1.10 behavior.
- `normal` means that only the top-level submodules will be included. It is - `normal` means that only the top-level submodules will be included. It is
equivalent to: equivalent to:
``` ```
$ git submodule sync git submodule sync
$ git submodule update --init git submodule update --init
``` ```
- `recursive` means that all submodules (including submodules of submodules) - `recursive` means that all submodules (including submodules of submodules)
will be included. It is equivalent to: will be included. It is equivalent to:
``` ```
$ git submodule sync --recursive git submodule sync --recursive
$ git submodule update --init --recursive git submodule update --init --recursive
``` ```
Note that for this feature to work correctly, the submodules must be configured Note that for this feature to work correctly, the submodules must be configured
(in `.gitmodules`) with either: (in `.gitmodules`) with either:
- the HTTP(S) URL of a publicly-accessible repository, or - the HTTP(S) URL of a publicly-accessible repository, or
- a relative path to another repository on the same GitLab server. See the - a relative path to another repository on the same GitLab server. See the
[Git submodules](../git_submodules.md) documentation. [Git submodules](../git_submodules.md) documentation.
## Build stages attempts ## Job stages attempts
> Introduced in GitLab, it requires GitLab Runner v1.9+. > Introduced in GitLab, it requires GitLab Runner v1.9+.
You can set the number for attempts the running build will try to execute each You can set the number for attempts the running job will try to execute each
of the following stages: of the following stages:
| Variable | Description | | Variable | Description |
|-------------------------|-------------| |-------------------------------- |-------------|
| **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a build | | **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a job |
| **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a build | | **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a job |
| **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a build | | **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a job |
The default is one single attempt. The default is one single attempt.
Example: Example:
``` ```yaml
variables: variables:
GET_SOURCES_ATTEMPTS: "3" GET_SOURCES_ATTEMPTS: "3"
``` ```
You can set them in the global [`variables`](#variables) section or the [`variables`](#job-variables) You can set them in the global [`variables`](#variables) section or the
section for individual jobs. [`variables`](#job-variables) section for individual jobs.
## Shallow cloning ## Shallow cloning
...@@ -1123,21 +1131,22 @@ repositories with a large number of commits or old, large binaries. The value is ...@@ -1123,21 +1131,22 @@ repositories with a large number of commits or old, large binaries. The value is
passed to `git fetch` and `git clone`. passed to `git fetch` and `git clone`.
>**Note:** >**Note:**
If you use a depth of 1 and have a queue of builds or retry If you use a depth of 1 and have a queue of jobs or retry
builds, jobs may fail. jobs, jobs may fail.
Since Git fetching and cloning is based on a ref, such as a branch name, runners Since Git fetching and cloning is based on a ref, such as a branch name, Runners
can't clone a specific commit SHA. If there are multiple builds in the queue, or can't clone a specific commit SHA. If there are multiple jobs in the queue, or
you are retrying an old build, the commit to be tested needs to be within the you are retrying an old job, the commit to be tested needs to be within the
git history that is cloned. Setting too small a value for `GIT_DEPTH` can make Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make
it impossible to run these old commits. You will see `unresolved reference` in it impossible to run these old commits. You will see `unresolved reference` in
build logs. You should then reconsider changing `GIT_DEPTH` to a higher value. job logs. You should then reconsider changing `GIT_DEPTH` to a higher value.
Builds that rely on `git describe` may not work correctly when `GIT_DEPTH` is Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
set since only part of the git history is present. set since only part of the Git history is present.
To fetch or clone only the last 3 commits: To fetch or clone only the last 3 commits:
```
```yaml
variables: variables:
GIT_DEPTH: "3" GIT_DEPTH: "3"
``` ```
...@@ -1174,7 +1183,7 @@ Read more about the various [YAML features](https://learnxinyminutes.com/docs/ya ...@@ -1174,7 +1183,7 @@ Read more about the various [YAML features](https://learnxinyminutes.com/docs/ya
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1. > Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
YAML also has a handy feature called 'anchors', which let you easily duplicate YAML has a handy feature called 'anchors', which lets you easily duplicate
content across your document. Anchors can be used to duplicate/inherit content across your document. Anchors can be used to duplicate/inherit
properties, and is a perfect example to be used with [hidden keys](#hidden-keys) properties, and is a perfect example to be used with [hidden keys](#hidden-keys)
to provide templates for your jobs. to provide templates for your jobs.
...@@ -1326,17 +1335,17 @@ pages: ...@@ -1326,17 +1335,17 @@ pages:
- master - master
``` ```
Read more on [GitLab Pages user documentation](../../pages/README.md). Read more on [GitLab Pages user documentation](../../user/project/pages/index.md).
## Validate the .gitlab-ci.yml ## Validate the .gitlab-ci.yml
Each instance of GitLab CI has an embedded debug tool called Lint. Each instance of GitLab CI has an embedded debug tool called Lint.
You can find the link under `/ci/lint` of your gitlab instance. You can find the link under `/ci/lint` of your gitlab instance.
## Skipping builds ## Skipping jobs
If your commit message contains `[ci skip]` or `[skip ci]`, using any If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the builds will be skipped. capitalization, the commit will be created but the jobs will be skipped.
## Examples ## Examples
......
doc/development/code_review.md
View file @ a084437b
...@@ -69,7 +69,7 @@ experience, refactors the existing code). Then: ...@@ -69,7 +69,7 @@ experience, refactors the existing code). Then:
someone else would be confused by it as well. someone else would be confused by it as well.
- After a round of line notes, it can be helpful to post a summary note such as - After a round of line notes, it can be helpful to post a summary note such as
"LGTM :thumbsup:", or "Just a couple things to address." "LGTM :thumbsup:", or "Just a couple things to address."
- Avoid accepting a merge request before the build succeeds. Of course, "Merge - Avoid accepting a merge request before the job succeeds. Of course, "Merge
When Pipeline Succeeds" (MWPS) is fine. When Pipeline Succeeds" (MWPS) is fine.
- If you set the MR to "Merge When Pipeline Succeeds", you should take over - If you set the MR to "Merge When Pipeline Succeeds", you should take over
subsequent revisions for anything that would be spotted after that. subsequent revisions for anything that would be spotted after that.
......
doc/install/installation.md
View file @ a084437b
...@@ -307,7 +307,7 @@ sudo usermod -aG redis git ...@@ -307,7 +307,7 @@ sudo usermod -aG redis git
# now that files in public/uploads are served by gitlab-workhorse # now that files in public/uploads are served by gitlab-workhorse
sudo chmod 0700 public/uploads sudo chmod 0700 public/uploads
# Change the permissions of the directory where CI build traces are stored # Change the permissions of the directory where CI job traces are stored
sudo chmod -R u+rwX builds/ sudo chmod -R u+rwX builds/
# Change the permissions of the directory where CI artifacts are stored # Change the permissions of the directory where CI artifacts are stored
......
doc/raketasks/backup_restore.md
View file @ a084437b
...@@ -44,8 +44,8 @@ environment variable `SKIP`. You can skip: ...@@ -44,8 +44,8 @@ environment variable `SKIP`. You can skip:
- `db` (database) - `db` (database)
- `uploads` (attachments) - `uploads` (attachments)
- `repositories` (Git repositories data) - `repositories` (Git repositories data)
- `builds` (CI build output logs) - `builds` (CI job output logs)
- `artifacts` (CI build artifacts) - `artifacts` (CI job artifacts)
- `lfs` (LFS objects) - `lfs` (LFS objects)
- `registry` (Container Registry images) - `registry` (Container Registry images)
......
doc/university/glossary/README.md
View file @ a084437b
...@@ -65,8 +65,8 @@ A branch is a parallel version of a repository. This allows you to work on the r ...@@ -65,8 +65,8 @@ A branch is a parallel version of a repository. This allows you to work on the r
Having your own logo on [your GitLab instance login page](https://docs.gitlab.com/ee/customization/branded_login_page.html) instead of the GitLab logo. Having your own logo on [your GitLab instance login page](https://docs.gitlab.com/ee/customization/branded_login_page.html) instead of the GitLab logo.
### Build triggers ### Job triggers
These protect your code base against breaks, for instance when a team is working on the same project. Learn about [setting up](https://docs.gitlab.com/ce/ci/triggers/README.html) build triggers. These protect your code base against breaks, for instance when a team is working on the same project. Learn about [setting up](https://docs.gitlab.com/ce/ci/triggers/README.html) job triggers.
### CEPH ### CEPH
......
doc/user/admin_area/settings/continuous_integration.md
View file @ a084437b
...@@ -2,9 +2,9 @@ ...@@ -2,9 +2,9 @@
## Maximum artifacts size ## Maximum artifacts size
The maximum size of the [build artifacts][art-yml] can be set in the Admin area The maximum size of the [job artifacts][art-yml] can be set in the Admin area
of your GitLab instance. The value is in MB and the default is 100MB. Note that of your GitLab instance. The value is in MB and the default is 100MB. Note that
this setting is set for each build. this setting is set for each job.
1. Go to **Admin area > Settings** (`/admin/application_settings`). 1. Go to **Admin area > Settings** (`/admin/application_settings`).
...@@ -17,4 +17,4 @@ this setting is set for each build. ...@@ -17,4 +17,4 @@ this setting is set for each build.
1. Hit **Save** for the changes to take effect. 1. Hit **Save** for the changes to take effect.
[art-yml]: ../../../administration/build_artifacts.md [art-yml]: ../../../administration/job_artifacts.md
doc/user/permissions.md
View file @ a084437b
...@@ -22,9 +22,9 @@ The following table depicts the various user permission levels in a project. ...@@ -22,9 +22,9 @@ The following table depicts the various user permission levels in a project.
| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ |
| View confidential issues | (✓) [^1] | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (✓) [^1] | ✓ | ✓ | ✓ | ✓ |
| Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ |
| See a list of builds | ✓ [^2] | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
| See a build log | ✓ [^2] | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
| Download and browse build artifacts | ✓ [^2] | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
| View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | | View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pull project code | | ✓ | ✓ | ✓ | ✓ | | Pull project code | | ✓ | ✓ | ✓ | ✓ |
| Download project | | ✓ | ✓ | ✓ | ✓ | | Download project | | ✓ | ✓ | ✓ | ✓ |
...@@ -46,7 +46,7 @@ The following table depicts the various user permission levels in a project. ...@@ -46,7 +46,7 @@ The following table depicts the various user permission levels in a project.
| Remove non-protected branches | | | ✓ | ✓ | ✓ | | Remove non-protected branches | | | ✓ | ✓ | ✓ |
| Add tags | | | ✓ | ✓ | ✓ | | Add tags | | | ✓ | ✓ | ✓ |
| Write a wiki | | | ✓ | ✓ | ✓ | | Write a wiki | | | ✓ | ✓ | ✓ |
| Cancel and retry builds | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | ✓ | ✓ | ✓ |
| Create or update commit status | | | ✓ | ✓ | ✓ | | Create or update commit status | | | ✓ | ✓ | ✓ |
| Update a container registry | | | ✓ | ✓ | ✓ | | Update a container registry | | | ✓ | ✓ | ✓ |
| Remove a container registry image | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ |
...@@ -60,7 +60,7 @@ The following table depicts the various user permission levels in a project. ...@@ -60,7 +60,7 @@ The following table depicts the various user permission levels in a project.
| Add deploy keys to project | | | | ✓ | ✓ | | Add deploy keys to project | | | | ✓ | ✓ |
| Configure project hooks | | | | ✓ | ✓ | | Configure project hooks | | | | ✓ | ✓ |
| Manage runners | | | | ✓ | ✓ | | Manage runners | | | | ✓ | ✓ |
| Manage build triggers | | | | ✓ | ✓ | | Manage job triggers | | | | ✓ | ✓ |
| Manage variables | | | | ✓ | ✓ | | Manage variables | | | | ✓ | ✓ |
| Manage pages | | | | ✓ | ✓ | | Manage pages | | | | ✓ | ✓ |
| Manage pages domains and certificates | | | | ✓ | ✓ | | Manage pages domains and certificates | | | | ✓ | ✓ |
...@@ -134,8 +134,8 @@ instance and project. In addition, all admins can use the admin interface under ...@@ -134,8 +134,8 @@ instance and project. In addition, all admins can use the admin interface under
| Action | Guest, Reporter | Developer | Master | Admin | | Action | Guest, Reporter | Developer | Master | Admin |
|---------------------------------------|-----------------|-------------|----------|--------| |---------------------------------------|-----------------|-------------|----------|--------|
| See commits and builds | ✓ | ✓ | ✓ | ✓ | | See commits and jobs | ✓ | ✓ | ✓ | ✓ |
| Retry or cancel build | | ✓ | ✓ | ✓ | | Retry or cancel job | | ✓ | ✓ | ✓ |
| Remove project | | | ✓ | ✓ | | Remove project | | | ✓ | ✓ |
| Create project | | | ✓ | ✓ | | Create project | | | ✓ | ✓ |
| Change project configuration | | | ✓ | ✓ | | Change project configuration | | | ✓ | ✓ |
...@@ -144,18 +144,18 @@ instance and project. In addition, all admins can use the admin interface under ...@@ -144,18 +144,18 @@ instance and project. In addition, all admins can use the admin interface under
| See events in the system | | | | ✓ | | See events in the system | | | | ✓ |
| Admin interface | | | | ✓ | | Admin interface | | | | ✓ |
### Builds permissions ### Jobs permissions
>**Note:** >**Note:**
GitLab 8.12 has a completely redesigned build permissions system. GitLab 8.12 has a completely redesigned job permissions system.
Read all about the [new model and its implications][new-mod]. Read all about the [new model and its implications][new-mod].
This table shows granted privileges for builds triggered by specific types of This table shows granted privileges for jobs triggered by specific types of
users: users:
| Action | Guest, Reporter | Developer | Master | Admin | | Action | Guest, Reporter | Developer | Master | Admin |
|---------------------------------------------|-----------------|-------------|----------|--------| |---------------------------------------------|-----------------|-------------|----------|--------|
| Run CI build | | ✓ | ✓ | ✓ | | Run CI job | | ✓ | ✓ | ✓ |
| Clone source and LFS from current project | | ✓ | ✓ | ✓ | | Clone source and LFS from current project | | ✓ | ✓ | ✓ |
| Clone source and LFS from public projects | | ✓ | ✓ | ✓ | | Clone source and LFS from public projects | | ✓ | ✓ | ✓ |
| Clone source and LFS from internal projects | | ✓ [^4] | ✓ [^4] | ✓ | | Clone source and LFS from internal projects | | ✓ [^4] | ✓ [^4] | ✓ |
......
doc/user/project/builds/artifacts.md
View file @ a084437b
# Introduction to build artifacts This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md).
>**Notes:**
>- Since GitLab 8.2 and GitLab Runner 0.7.0, build artifacts that are created by
GitLab Runner are uploaded to GitLab and are downloadable as a single archive
(`tar.gz`) using the GitLab UI.
>- Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
changed to `ZIP`, and it is now possible to browse its contents, with the added
ability of downloading the files separately.
>- The artifacts browser will be available only for new artifacts that are sent
to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
browse old artifacts already uploaded to GitLab.
>- This is the user documentation. For the administration guide see
[administration/build_artifacts.md](../../../administration/build_artifacts.md).
Artifacts is a list of files and directories which are attached to a build
after it completes successfully. This feature is enabled by default in all GitLab installations.
## Defining artifacts in `.gitlab-ci.yml`
A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
the following:
```yaml
pdf:
script: xelatex mycv.tex
artifacts:
paths:
- mycv.pdf
```
A job named `pdf` calls the `xelatex` command in order to build a pdf file from
the latex source file `mycv.tex`. We then define the `artifacts` paths which in
turn are defined with the `paths` keyword. All paths to files and directories
are relative to the repository that was cloned during the build.
For more examples on artifacts, follow the artifacts reference in
[`.gitlab-ci.yml` documentation](../../../ci/yaml/README.md#artifacts).
## Browsing build artifacts
When GitLab receives an artifacts archive, an archive metadata file is also
generated. This metadata file describes all the entries that are located in the
artifacts archive itself. The metadata file is in a binary format, with
additional GZIP compression.
GitLab does not extract the artifacts archive in order to save space, memory
and disk I/O. It instead inspects the metadata file which contains all the
relevant information. This is especially important when there is a lot of
artifacts, or an archive is a very large file.
---
After a build finishes, if you visit the build's specific page, you can see
that there are two buttons. One is for downloading the artifacts archive and
the other for browsing its contents.
![Build artifacts browser button](img/build_artifacts_browser_button.png)
---
The archive browser shows the name and the actual file size of each file in the
archive. If your artifacts contained directories, then you are also able to
browse inside them.
Below you can see how browsing looks like. In this case we have browsed inside
the archive and at this point there is one directory and one HTML file.
![Build artifacts browser](img/build_artifacts_browser.png)
---
## Downloading build artifacts
>**Note:**
GitLab does not extract the entire artifacts archive to send just a single file
to the user. When clicking on a specific file, [GitLab Workhorse] extracts it
from the archive and the download begins. This implementation saves space,
memory and disk I/O.
If you need to download the whole archive, there are buttons in various places
inside GitLab that make that possible.
1. While on the pipelines page, you can see the download icon for each build's
artifacts archive in the right corner:
![Build artifacts in Pipelines page](img/build_artifacts_pipelines_page.png)
1. While on the builds page, you can see the download icon for each build's
artifacts archive in the right corner:
![Build artifacts in Builds page](img/build_artifacts_builds_page.png)
1. While inside a specific build, you are presented with a download button
along with the one that browses the archive:
![Build artifacts browser button](img/build_artifacts_browser_button.png)
1. And finally, when browsing an archive you can see the download button at
the top right corner:
![Build artifacts browser](img/build_artifacts_browser.png)
## Downloading the latest build artifacts
It is possible to download the latest artifacts of a build via a well known URL
so you can use it for scripting purposes.
The structure of the URL is the following:
```
https://example.com/<namespace>/<project>/builds/artifacts/<ref>/download?job=<job_name>
```
For example, to download the latest artifacts of the job named `rspec 6 20` of
the `master` branch of the `gitlab-ce` project that belongs to the `gitlab-org`
namespace, the URL would be:
```
https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/download?job=rspec+6+20
```
The latest builds are also exposed in the UI in various places. Specifically,
look for the download button in:
- the main project's page
- the branches page
- the tags page
If the latest build has failed to upload the artifacts, you can see that
information in the UI.
![Latest artifacts button](img/build_latest_artifacts_browser.png)
[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository"
doc/user/project/integrations/webhooks.md
View file @ a084437b
...@@ -11,7 +11,7 @@ a new issue is created. You can configure webhooks to listen for specific events ...@@ -11,7 +11,7 @@ a new issue is created. You can configure webhooks to listen for specific events
like pushes, issues or merge requests. GitLab will send a POST request with data like pushes, issues or merge requests. GitLab will send a POST request with data
to the webhook URL. to the webhook URL.
Webhooks can be used to update an external issue tracker, trigger CI builds, Webhooks can be used to update an external issue tracker, trigger CI jobs,
update a backup mirror, or even deploy to your production server. update a backup mirror, or even deploy to your production server.
Navigate to the webhooks page by going to the **Integrations** page from your Navigate to the webhooks page by going to the **Integrations** page from your
......
doc/user/project/merge_requests/index.md
View file @ a084437b
...@@ -22,7 +22,7 @@ in a merged merge requests or a commit. ...@@ -22,7 +22,7 @@ in a merged merge requests or a commit.
## Merge when pipeline succeeds ## Merge when pipeline succeeds
When reviewing a merge request that looks ready to merge but still has one or When reviewing a merge request that looks ready to merge but still has one or
more CI builds running, you can set it to be merged automatically when CI more CI jobs running, you can set it to be merged automatically when CI
pipeline succeeds. This way, you don't have to wait for the pipeline to finish pipeline succeeds. This way, you don't have to wait for the pipeline to finish
and remember to merge the request manually. and remember to merge the request manually.
......
doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
View file @ a084437b
# Merge When Pipeline Succeeds # Merge When Pipeline Succeeds
When reviewing a merge request that looks ready to merge but still has one or When reviewing a merge request that looks ready to merge but still has one or
more CI builds running, you can set it to be merged automatically when the more CI jobs running, you can set it to be merged automatically when the
builds pipeline succeeds. This way, you don't have to wait for the builds to jobs pipeline succeeds. This way, you don't have to wait for the jobs to
finish and remember to merge the request manually. finish and remember to merge the request manually.
![Enable](img/merge_when_build_succeeds_enable.png) ![Enable](img/merge_when_build_succeeds_enable.png)
...@@ -19,10 +19,10 @@ after all. ...@@ -19,10 +19,10 @@ after all.
![Status](img/merge_when_build_succeeds_status.png) ![Status](img/merge_when_build_succeeds_status.png)
When the pipeline succeeds, the merge request will automatically be merged. When the pipeline succeeds, the merge request will automatically be merged.
When the pipeline fails, the author gets a chance to retry any failed builds, When the pipeline fails, the author gets a chance to retry any failed jobs,
or to push new commits to fix the failure. or to push new commits to fix the failure.
When the builds are retried and succeed on the second try, the merge request When the jobs are retried and succeed on the second try, the merge request
will automatically be merged after all. When the merge request is updated with will automatically be merged after all. When the merge request is updated with
new commits, the automatic merge is automatically canceled to allow the new new commits, the automatic merge is automatically canceled to allow the new
changes to be reviewed. changes to be reviewed.
...@@ -30,7 +30,7 @@ changes to be reviewed. ...@@ -30,7 +30,7 @@ changes to be reviewed.
## Only allow merge requests to be merged if the pipeline succeeds ## Only allow merge requests to be merged if the pipeline succeeds
> **Note:** > **Note:**
You need to have builds configured to enable this feature. You need to have jobs configured to enable this feature.
You can prevent merge requests from being merged if their pipeline did not succeed. You can prevent merge requests from being merged if their pipeline did not succeed.
...@@ -41,6 +41,6 @@ hit **Save** for the changes to take effect. ...@@ -41,6 +41,6 @@ hit **Save** for the changes to take effect.
![Only allow merge if pipeline succeeds settings](img/merge_when_build_succeeds_only_if_succeeds_settings.png) ![Only allow merge if pipeline succeeds settings](img/merge_when_build_succeeds_only_if_succeeds_settings.png)
From now on, every time the pipeline fails you will not be able to merge the From now on, every time the pipeline fails you will not be able to merge the
merge request from the UI, until you make all relevant builds pass. merge request from the UI, until you make all relevant jobs pass.
![Only allow merge if pipeline succeeds message](img/merge_when_build_succeeds_only_if_succeeds_msg.png) ![Only allow merge if pipeline succeeds message](img/merge_when_build_succeeds_only_if_succeeds_msg.png)
doc/user/project/new_ci_build_permissions_model.md
View file @ a084437b
# New CI build permissions model # New CI job permissions model
> Introduced in GitLab 8.12. > Introduced in GitLab 8.12.
GitLab 8.12 has a completely redesigned [build permissions] system. You can find GitLab 8.12 has a completely redesigned [job permissions] system. You can find
all discussion and all our concerns when choosing the current approach in issue all discussion and all our concerns when choosing the current approach in issue
[#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994). [#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994).
--- ---
Builds permissions should be tightly integrated with the permissions of a user Jobs permissions should be tightly integrated with the permissions of a user
who is triggering a build. who is triggering a job.
The reasons to do it like that are: The reasons to do it like that are:
- We already have a permissions system in place: group and project membership - We already have a permissions system in place: group and project membership
of users. of users.
- We already fully know who is triggering a build (using `git push`, using the - We already fully know who is triggering a job (using `git push`, using the
web UI, executing triggers). web UI, executing triggers).
- We already know what user is allowed to do. - We already know what user is allowed to do.
- We use the user permissions for builds that are triggered by the user. - We use the user permissions for jobs that are triggered by the user.
- It opens a lot of possibilities to further enforce user permissions, like - It opens a lot of possibilities to further enforce user permissions, like
allowing only specific users to access runners or use secure variables and allowing only specific users to access runners or use secure variables and
environments. environments.
- It is simple and convenient that your build can access everything that you - It is simple and convenient that your job can access everything that you
as a user have access to. as a user have access to.
- Short living unique tokens are now used, granting access for time of the build - Short living unique tokens are now used, granting access for time of the job
and maximizing security. and maximizing security.
With the new behavior, any build that is triggered by the user, is also marked With the new behavior, any job that is triggered by the user, is also marked
with their permissions. When a user does a `git push` or changes files through with their permissions. When a user does a `git push` or changes files through
the web UI, a new pipeline will be usually created. This pipeline will be marked the web UI, a new pipeline will be usually created. This pipeline will be marked
as created be the pusher (local push or via the UI) and any build created in this as created be the pusher (local push or via the UI) and any job created in this
pipeline will have the permissions of the pusher. pipeline will have the permissions of the pusher.
This allows us to make it really easy to evaluate the access for all projects This allows us to make it really easy to evaluate the access for all projects
that have [Git submodules][gitsub] or are using container images that the pusher that have [Git submodules][gitsub] or are using container images that the pusher
would have access too. **The permission is granted only for time that build is would have access too. **The permission is granted only for time that job is
running. The access is revoked after the build is finished.** running. The access is revoked after the job is finished.**
## Types of users ## Types of users
It is important to note that we have a few types of users: It is important to note that we have a few types of users:
- **Administrators**: CI builds created by Administrators will not have access - **Administrators**: CI jobs created by Administrators will not have access
to all GitLab projects, but only to projects and container images of projects to all GitLab projects, but only to projects and container images of projects
that the administrator is a member of.That means that if a project is either that the administrator is a member of.That means that if a project is either
public or internal users have access anyway, but if a project is private, the public or internal users have access anyway, but if a project is private, the
Administrator will have to be a member of it in order to have access to it Administrator will have to be a member of it in order to have access to it
via another project's build. via another project's job.
- **External users**: CI builds created by [external users][ext] will have - **External users**: CI jobs created by [external users][ext] will have
access only to projects to which user has at least reporter access. This access only to projects to which user has at least reporter access. This
rules out accessing all internal projects by default, rules out accessing all internal projects by default,
...@@ -57,46 +57,46 @@ This allows us to make the CI and permission system more trustworthy. ...@@ -57,46 +57,46 @@ This allows us to make the CI and permission system more trustworthy.
Let's consider the following scenario: Let's consider the following scenario:
1. You are an employee of a company. Your company has a number of internal tools 1. You are an employee of a company. Your company has a number of internal tools
hosted in private repositories and you have multiple CI builds that make use hosted in private repositories and you have multiple CI jobs that make use
of these repositories. of these repositories.
2. You invite a new [external user][ext]. CI builds created by that user do not 2. You invite a new [external user][ext]. CI jobs created by that user do not
have access to internal repositories, because the user also doesn't have the have access to internal repositories, because the user also doesn't have the
access from within GitLab. You as an employee have to grant explicit access access from within GitLab. You as an employee have to grant explicit access
for this user. This allows us to prevent from accidental data leakage. for this user. This allows us to prevent from accidental data leakage.
## Build token ## Job token
A unique build token is generated for each build and it allows the user to A unique job token is generated for each job and it allows the user to
access all projects that would be normally accessible to the user creating that access all projects that would be normally accessible to the user creating that
build. job.
We try to make sure that this token doesn't leak by: We try to make sure that this token doesn't leak by:
1. Securing all API endpoints to not expose the build token. 1. Securing all API endpoints to not expose the job token.
1. Masking the build token from build logs. 1. Masking the job token from job logs.
1. Allowing to use the build token **only** when build is running. 1. Allowing to use the job token **only** when job is running.
However, this brings a question about the Runners security. To make sure that However, this brings a question about the Runners security. To make sure that
this token doesn't leak, you should also make sure that you configure this token doesn't leak, you should also make sure that you configure
your Runners in the most possible secure way, by avoiding the following: your Runners in the most possible secure way, by avoiding the following:
1. Any usage of Docker's `privileged` mode is risky if the machines are re-used. 1. Any usage of Docker's `privileged` mode is risky if the machines are re-used.
1. Using the `shell` executor since builds run on the same machine. 1. Using the `shell` executor since jobs run on the same machine.
By using an insecure GitLab Runner configuration, you allow the rogue developers By using an insecure GitLab Runner configuration, you allow the rogue developers
to steal the tokens of other builds. to steal the tokens of other jobs.
## Build triggers ## job triggers
[Build triggers][triggers] do not support the new permission model. [job triggers][triggers] do not support the new permission model.
They continue to use the old authentication mechanism where the CI build They continue to use the old authentication mechanism where the CI job
can access only its own sources. We plan to remove that limitation in one of can access only its own sources. We plan to remove that limitation in one of
the upcoming releases. the upcoming releases.
## Before GitLab 8.12 ## Before GitLab 8.12
In versions before GitLab 8.12, all CI builds would use the CI Runner's token In versions before GitLab 8.12, all CI jobs would use the CI Runner's token
to checkout project sources. to checkout project sources.
The project's Runner's token was a token that you could find under the The project's Runner's token was a token that you could find under the
...@@ -105,7 +105,7 @@ project. ...@@ -105,7 +105,7 @@ project.
It could be used for registering new specific Runners assigned to the project It could be used for registering new specific Runners assigned to the project
and to checkout project sources. and to checkout project sources.
It could also be used with the GitLab Container Registry for that project, It could also be used with the GitLab Container Registry for that project,
allowing pulling and pushing Docker images from within the CI build. allowing pulling and pushing Docker images from within the CI job.
--- ---
...@@ -115,7 +115,7 @@ GitLab would create a special checkout URL like: ...@@ -115,7 +115,7 @@ GitLab would create a special checkout URL like:
https://gitlab-ci-token:<project-runners-token>/gitlab.com/gitlab-org/gitlab-ce.git https://gitlab-ci-token:<project-runners-token>/gitlab.com/gitlab-org/gitlab-ce.git
``` ```
And then the users could also use it in their CI builds all Docker related And then the users could also use it in their CI jobs all Docker related
commands to interact with GitLab Container Registry. For example: commands to interact with GitLab Container Registry. For example:
``` ```
...@@ -125,7 +125,7 @@ docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com ...@@ -125,7 +125,7 @@ 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 - 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 that could run CI jobs, allowing the developer to register any specific
Runner for that project. Runner for that project.
- The token would allow to access only the project's sources, forbidding from - The token would allow to access only the project's sources, forbidding from
accessing any other projects. accessing any other projects.
...@@ -133,12 +133,12 @@ Using single token had multiple security implications: ...@@ -133,12 +133,12 @@ Using single token had multiple security implications:
for registering specific runners and for accessing a project's container for registering specific runners and for accessing a project's container
registry with read-write permissions. registry with read-write permissions.
All the above led to a new permission model for builds that was introduced All the above led to a new permission model for jobs that was introduced
with GitLab 8.12. with GitLab 8.12.
## Making use of the new CI build permissions model ## Making use of the new CI job permissions model
With the new build permissions model, there is now an easy way to access all With the new job permissions model, there is now an easy way to access all
dependent source code in a project. That way, we can: dependent source code in a project. That way, we can:
1. Access a project's [Git submodules][gitsub] 1. Access a project's [Git submodules][gitsub]
...@@ -151,9 +151,9 @@ the container registry. ...@@ -151,9 +151,9 @@ the container registry.
### Prerequisites to use the new permissions model ### Prerequisites to use the new permissions model
With the new permissions model in place, there may be times that your build will With the new permissions model in place, there may be times that your job will
fail. This is most likely because your project tries to access other project's fail. This is most likely because your project tries to access other project's
sources, and you don't have the appropriate permissions. In the build log look sources, and you don't have the appropriate permissions. In the job log look
for information about 403 or forbidden access messages. for information about 403 or forbidden access messages.
In short here's what you need to do should you encounter any issues. In short here's what you need to do should you encounter any issues.
...@@ -175,7 +175,7 @@ As a user: ...@@ -175,7 +175,7 @@ As a user:
- Make sure you are a member of the group or project you're trying to have - Make sure you are a member of the group or project you're trying to have
access to. As an Administrator, you can verify that by impersonating the user access to. As an Administrator, you can verify that by impersonating the user
and retry the failing build in order to verify that everything is correct. and retry the failing job in order to verify that everything is correct.
### Git submodules ### Git submodules
...@@ -199,9 +199,9 @@ Container Registries for private projects. ...@@ -199,9 +199,9 @@ Container Registries for private projects.
to pass a personal access token instead of your password in order to login to to pass a personal access token instead of your password in order to login to
GitLab's Container Registry. GitLab's Container Registry.
Your builds can access all container images that you would normally have access Your jobs can access all container images that you would normally have access
to. The only implication is that you can push to the Container Registry of the to. The only implication is that you can push to the Container Registry of the
project for which the build is triggered. project for which the job is triggered.
This is how an example usage can look like: This is how an example usage can look like:
...@@ -213,7 +213,7 @@ test: ...@@ -213,7 +213,7 @@ test:
- docker run $CI_REGISTRY/group/other-project:latest - docker run $CI_REGISTRY/group/other-project:latest
``` ```
[build permissions]: ../permissions.md#builds-permissions [job permissions]: ../permissions.md#jobs-permissions
[comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302 [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302
[ext]: ../permissions.md#external-users [ext]: ../permissions.md#external-users
[gitsub]: ../../ci/git_submodules.md [gitsub]: ../../ci/git_submodules.md
......
doc/user/project/pages/index.md
View file @ a084437b
...@@ -100,7 +100,7 @@ whereas a group's project under `http(s)://groupname.example.io/projectname`. ...@@ -100,7 +100,7 @@ whereas a group's project under `http(s)://groupname.example.io/projectname`.
The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that
gives you absolute control over the build process. You can actually watch your gives you absolute control over the build process. You can actually watch your
website being built live by following the CI build traces. website being built live by following the CI job traces.
> **Note:** > **Note:**
> Before reading this section, make sure you familiarize yourself with GitLab CI > Before reading this section, make sure you familiarize yourself with GitLab CI
...@@ -127,7 +127,7 @@ pages: ...@@ -127,7 +127,7 @@ pages:
``` ```
When the Runner reaches to build the `pages` job, it executes whatever is When the Runner reaches to build the `pages` job, it executes whatever is
defined in the `script` parameter and if the build completes with a non-zero defined in the `script` parameter and if the job completes with a non-zero
exit status, it then uploads the `public/` directory to GitLab Pages. exit status, it then uploads the `public/` directory to GitLab Pages.
The `public/` directory should contain all the static content of your website. The `public/` directory should contain all the static content of your website.
...@@ -211,11 +211,11 @@ pages: # the build job must be named pages ...@@ -211,11 +211,11 @@ pages: # the build job must be named pages
``` ```
Here, we used the Docker executor and in the first line we specified the base Here, we used the Docker executor and in the first line we specified the base
image against which our builds will run. image against which our jobs will run.
You have to make sure that the generated static files are ultimately placed You have to make sure that the generated static files are ultimately placed
under the `public` directory, that's why in the `script` section we run the under the `public` directory, that's why in the `script` section we run the
`jekyll` command that builds the website and puts all content in the `public/` `jekyll` command that jobs the website and puts all content in the `public/`
directory. Depending on the static generator of your choice, this command will directory. Depending on the static generator of your choice, this command will
differ. Search in the documentation of the static generator you will use if differ. Search in the documentation of the static generator you will use if
there is an option to explicitly set the output directory. If there is not there is an option to explicitly set the output directory. If there is not
...@@ -403,7 +403,7 @@ don't have to create and edit HTML files manually. For example, Jekyll has the ...@@ -403,7 +403,7 @@ don't have to create and edit HTML files manually. For example, Jekyll has the
### Can I download my generated pages? ### Can I download my generated pages?
Sure. All you need to do is download the artifacts archive from the build page. Sure. All you need to do is download the artifacts archive from the job page.
### Can I use GitLab Pages if my project is private? ### Can I use GitLab Pages if my project is private?
......
doc/user/project/pipelines/job_artifacts.md 0 → 100644
View file @ a084437b
# Introduction to job artifacts
>**Notes:**
>- Since GitLab 8.2 and GitLab Runner 0.7.0, job artifacts that are created by
GitLab Runner are uploaded to GitLab and are downloadable as a single archive
(`tar.gz`) using the GitLab UI.
>- Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format
changed to `ZIP`, and it is now possible to browse its contents, with the added
ability of downloading the files separately.
>- Starting with GitLab 8.17, builds are renamed to jobs.
>- The artifacts browser will be available only for new artifacts that are sent
to GitLab using GitLab Runner version 1.0 and up. It will not be possible to
browse old artifacts already uploaded to GitLab.
>- This is the user documentation. For the administration guide see
[administration/job_artifacts.md](../../../administration/job_artifacts.md).
Artifacts is a list of files and directories which are attached to a job
after it completes successfully. This feature is enabled by default in all
GitLab installations.
## Defining artifacts in `.gitlab-ci.yml`
A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
the following:
```yaml
pdf:
script: xelatex mycv.tex
artifacts:
paths:
- mycv.pdf
```
A job named `pdf` calls the `xelatex` command in order to build a pdf file from
the latex source file `mycv.tex`. We then define the `artifacts` paths which in
turn are defined with the `paths` keyword. All paths to files and directories
are relative to the repository that was cloned during the build.
For more examples on artifacts, follow the artifacts reference in
[`.gitlab-ci.yml` documentation](../../../ci/yaml/README.md#artifacts).
## Browsing job artifacts
After a job finishes, if you visit the job's specific page, you can see
that there are two buttons. One is for downloading the artifacts archive and
the other for browsing its contents.
![Job artifacts browser button](img/job_artifacts_browser_button.png)
---
The archive browser shows the name and the actual file size of each file in the
archive. If your artifacts contained directories, then you are also able to
browse inside them.
Below you can see how browsing looks like. In this case we have browsed inside
the archive and at this point there is one directory and one HTML file.
![Job artifacts browser](img/job_artifacts_browser.png)
---
## Downloading job artifacts
If you need to download the whole archive, there are buttons in various places
inside GitLab that make that possible.
1. While on the pipelines page, you can see the download icon for each job's
artifacts archive in the right corner:
![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
1. While on the **Jobs** page, you can see the download icon for each job's
artifacts archive in the right corner:
![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
1. While inside a specific job, you are presented with a download button
along with the one that browses the archive:
![Job artifacts browser button](img/job_artifacts_browser_button.png)
1. And finally, when browsing an archive you can see the download button at
the top right corner:
![Job artifacts browser](img/job_artifacts_browser.png)
## Downloading the latest job artifacts
It is possible to download the latest artifacts of a job via a well known URL
so you can use it for scripting purposes.
The structure of the URL is the following:
```
https://example.com/<namespace>/<project>/builds/artifacts/<ref>/download?job=<job_name>
```
For example, to download the latest artifacts of the job named `rspec 6 20` of
the `master` branch of the `gitlab-ce` project that belongs to the `gitlab-org`
namespace, the URL would be:
```
https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/download?job=rspec+6+20
```
The latest builds are also exposed in the UI in various places. Specifically,
look for the download button in:
- the main project's page
- the branches page
- the tags page
If the latest job has failed to upload the artifacts, you can see that
information in the UI.
![Latest artifacts button](img/job_latest_artifacts_browser.png)
doc/user/project/pipelines/settings.md
View file @ a084437b
...@@ -35,7 +35,7 @@ if the job surpasses the threshold, it is marked as failed. ...@@ -35,7 +35,7 @@ if the job surpasses the threshold, it is marked as failed.
## Test coverage parsing ## Test coverage parsing
If you use test coverage in your code, GitLab can capture its output in the If you use test coverage in your code, GitLab can capture its output in the
build log using a regular expression. In the pipelines settings, search for the job log using a regular expression. In the pipelines settings, search for the
"Test coverage parsing" section. "Test coverage parsing" section.
![Pipelines settings test coverage](img/pipelines_settings_test_coverage.png) ![Pipelines settings test coverage](img/pipelines_settings_test_coverage.png)
...@@ -44,7 +44,7 @@ Leave blank if you want to disable it or enter a ruby regular expression. You ...@@ -44,7 +44,7 @@ Leave blank if you want to disable it or enter a ruby regular expression. You
can use http://rubular.com to test your regex. can use http://rubular.com to test your regex.
If the pipeline succeeds, the coverage is shown in the merge request widget and If the pipeline succeeds, the coverage is shown in the merge request widget and
in the builds table. in the jobs table.
![MR widget coverage](img/pipelines_test_coverage_mr_widget.png) ![MR widget coverage](img/pipelines_test_coverage_mr_widget.png)
...@@ -62,9 +62,9 @@ pipelines** checkbox and save the changes. ...@@ -62,9 +62,9 @@ pipelines** checkbox and save the changes.
## Badges ## Badges
In the pipelines settings page you can find build status and test coverage In the pipelines settings page you can find job status and test coverage
badges for your project. The latest successful pipeline will be used to read badges for your project. The latest successful pipeline will be used to read
the build status and test coverage values. the job status and test coverage values.
Visit the pipelines settings page in your project to see the exact link to Visit the pipelines settings page in your project to see the exact link to
your badges, as well as ways to embed the badge image in your HTML or Markdown your badges, as well as ways to embed the badge image in your HTML or Markdown
...@@ -72,9 +72,9 @@ pages. ...@@ -72,9 +72,9 @@ pages.
![Pipelines badges](img/pipelines_settings_badges.png) ![Pipelines badges](img/pipelines_settings_badges.png)
### Build status badge ### Job status badge
Depending on the status of your build, a badge can have the following values: Depending on the status of your job, a badge can have the following values:
- running - running
- success - success
...@@ -82,7 +82,7 @@ Depending on the status of your build, a badge can have the following values: ...@@ -82,7 +82,7 @@ Depending on the status of your build, a badge can have the following values:
- skipped - skipped
- unknown - unknown
You can access a build status badge image using the following link: You can access a job status badge image using the following link:
``` ```
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg
...@@ -91,7 +91,7 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg ...@@ -91,7 +91,7 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg
### Test coverage report badge ### Test coverage report badge
GitLab makes it possible to define the regular expression for [coverage report], GitLab makes it possible to define the regular expression for [coverage report],
that each build log will be matched against. This means that each build in the that each job log will be matched against. This means that each job in the
pipeline can have the test coverage percentage value defined. pipeline can have the test coverage percentage value defined.
The test coverage badge can be accessed using following link: The test coverage badge can be accessed using following link:
......
doc/user/project/slash_commands.md
View file @ a084437b
...@@ -14,7 +14,7 @@ do. ...@@ -14,7 +14,7 @@ do.
|:---------------------------|:-------------| |:---------------------------|:-------------|
| `/close` | Close the issue or merge request | | `/close` | Close the issue or merge request |
| `/reopen` | Reopen the issue or merge request | | `/reopen` | Reopen the issue or merge request |
| `/merge` | Merge (when build succeeds) | | `/merge` | Merge (when pipeline succeeds) |
| `/title <New title>` | Change title | | `/title <New title>` | Change title |
| `/assign @username` | Assign | | `/assign @username` | Assign |
| `/unassign` | Remove assignee | | `/unassign` | Remove assignee |
......
doc/workflow/shortcuts.md
View file @ a084437b
...@@ -45,7 +45,7 @@ You can see GitLab's keyboard shortcuts by using 'shift + ?' ...@@ -45,7 +45,7 @@ You can see GitLab's keyboard shortcuts by using 'shift + ?'
| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project's activity feed | | <kbd>g</kbd> + <kbd>e</kbd> | Go to the project's activity feed |
| <kbd>g</kbd> + <kbd>f</kbd> | Go to files | | <kbd>g</kbd> + <kbd>f</kbd> | Go to files |
| <kbd>g</kbd> + <kbd>c</kbd> | Go to commits | | <kbd>g</kbd> + <kbd>c</kbd> | Go to commits |
| <kbd>g</kbd> + <kbd>b</kbd> | Go to builds | | <kbd>g</kbd> + <kbd>b</kbd> | Go to jobs |
| <kbd>g</kbd> + <kbd>n</kbd> | Go to network graph | | <kbd>g</kbd> + <kbd>n</kbd> | Go to network graph |
| <kbd>g</kbd> + <kbd>g</kbd> | Go to graphs | | <kbd>g</kbd> + <kbd>g</kbd> | Go to graphs |
| <kbd>g</kbd> + <kbd>i</kbd> | Go to issues | | <kbd>g</kbd> + <kbd>i</kbd> | Go to issues |
......
doc/workflow/todos.md
View file @ a084437b
...@@ -27,8 +27,8 @@ A Todo appears in your Todos dashboard when: ...@@ -27,8 +27,8 @@ A Todo appears in your Todos dashboard when:
- an issue or merge request is assigned to you, - an issue or merge request is assigned to you,
- you are `@mentioned` in an issue or merge request, be it the description of - you are `@mentioned` in an issue or merge request, be it the description of
the issue/merge request or in a comment, the issue/merge request or in a comment,
- build in the CI pipeline running for your merge request failed, but this - a job in the CI pipeline running for your merge request failed, but this
build is not allowed to fail. job is not allowed to fail.
>**Note:** Commenting on a commit will _not_ trigger a Todo. >**Note:** Commenting on a commit will _not_ trigger a Todo.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7