Merge branch 'docs/builds-to-jobs-massacre' into 'master'
Rename builds to jobs in docs See merge request !9204
|
@ -1,96 +1 @@
|
|||
# Build artifacts administration
|
||||
|
||||
>**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).
|
||||
This document was moved to [jobs_artifacts](jobs_artifacts.md).
|
||||
|
|
|
@ -0,0 +1,114 @@
|
|||
# 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"
|
|
@ -2,22 +2,22 @@
|
|||
|
||||
## 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)
|
||||
- [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)
|
||||
- [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 CI to build Docker images](docker/using_docker_build.md)
|
||||
- [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
|
||||
- [Use SSH keys in your build environment](ssh_keys/README.md)
|
||||
- [Trigger builds through the API](triggers/README.md)
|
||||
- [Build artifacts](../user/project/builds/artifacts.md)
|
||||
- [Trigger jobs through the API](triggers/README.md)
|
||||
- [Job artifacts](../user/project/pipelines/job_artifacts.md)
|
||||
- [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)
|
||||
- [CI services (linked docker containers)](services/README.md)
|
||||
- [CI/CD pipelines settings](../user/project/pipelines/settings.md)
|
||||
|
@ -27,6 +27,6 @@
|
|||
|
||||
## Breaking changes
|
||||
|
||||
- [New CI build permissions model](../user/project/new_ci_build_permissions_model.md)
|
||||
Read about what changed in GitLab 8.12 and how that affects your builds.
|
||||
There's a new way to access your Git submodules and LFS objects in builds.
|
||||
- [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 jobs.
|
||||
There's a new way to access your Git submodules and LFS objects in jobs.
|
||||
|
|
|
@ -1,4 +1 @@
|
|||
This document was moved to:
|
||||
|
||||
- [user/project/builds/artifacts.md](../../user/project/builds/artifacts.md) - user guide
|
||||
- [administration/build_artifacts.md](../../administration/build_artifacts.md) - administrator guide
|
||||
This document was moved to [user/project/job_artifacts.md](../../user/project/job_artifacts.md).
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# Docker integration
|
||||
|
||||
+ [Using Docker Images](using_docker_images.md)
|
||||
+ [Using Docker Build](using_docker_build.md)
|
||||
- [Using Docker Images](using_docker_images.md)
|
||||
- [Using Docker Build](using_docker_build.md)
|
||||
|
|
|
@ -12,6 +12,7 @@ One of the new trends in Continuous Integration/Deployment is to:
|
|||
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:
|
||||
|
||||
```bash
|
||||
$ docker build -t my-image dockerfiles/
|
||||
$ docker run my-docker-image /script/to/run/tests
|
||||
|
@ -19,23 +20,23 @@ $ docker tag my-image 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
|
||||
|
||||
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
|
||||
|
||||
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. 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
|
||||
$ sudo gitlab-ci-multi-runner register -n \
|
||||
sudo gitlab-ci-multi-runner register -n \
|
||||
--url https://gitlab.com/ci \
|
||||
--registration-token REGISTRATION_TOKEN \
|
||||
--executor shell \
|
||||
|
@ -50,16 +51,17 @@ GitLab Runner then executes build scripts as the `gitlab-runner` user.
|
|||
3. Add `gitlab-runner` user to `docker` group:
|
||||
|
||||
```bash
|
||||
$ sudo usermod -aG docker gitlab-runner
|
||||
sudo usermod -aG docker gitlab-runner
|
||||
```
|
||||
|
||||
4. Verify that `gitlab-runner` has access to Docker:
|
||||
|
||||
```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`:
|
||||
|
||||
```yaml
|
||||
before_script:
|
||||
- docker info
|
||||
|
@ -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)
|
||||
[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.
|
||||
|
||||
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`
|
||||
mode:
|
||||
|
@ -155,10 +157,10 @@ not without its own challenges:
|
|||
escalation which can lead to container breakout. For more information, check
|
||||
out the official Docker documentation on
|
||||
[Runtime privilege and Linux capabilities][docker-cap].
|
||||
- Using docker-in-docker, each build is in a clean environment without the past
|
||||
history. Concurrent builds work fine because every build gets it's own
|
||||
- When using docker-in-docker, each job is in a clean environment without the past
|
||||
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
|
||||
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
|
||||
form offered. To use a different driver, see
|
||||
[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
|
|||
|
||||
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`:
|
||||
|
||||
|
@ -187,7 +189,9 @@ In order to do that, follow the steps:
|
|||
|
||||
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
|
||||
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:
|
||||
|
||||
|
@ -206,7 +210,8 @@ In order to do that, follow the steps:
|
|||
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
|
||||
image: docker:latest
|
||||
|
@ -221,18 +226,23 @@ In order to do that, follow the steps:
|
|||
- 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:
|
||||
* By sharing the docker daemon, you are effectively disabling all
|
||||
the security mechanisms of containers and exposing your host to privilege
|
||||
escalation which can lead to container breakout. For example, if a project
|
||||
ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
|
||||
containers.
|
||||
* Concurrent builds may not work; if your tests
|
||||
create containers with specific names, they may conflict with each other.
|
||||
* Sharing files and directories from the source repo into containers may not
|
||||
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`
|
||||
While the above method avoids using Docker in privileged mode, you should be
|
||||
aware of the following implications:
|
||||
|
||||
- By sharing the docker daemon, you are effectively disabling all
|
||||
the security mechanisms of containers and exposing your host to privilege
|
||||
escalation which can lead to container breakout. For example, if a project
|
||||
ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
|
||||
containers.
|
||||
- Concurrent jobs may not work; if your tests
|
||||
create containers with specific names, they may conflict with each other.
|
||||
- Sharing files and directories from the source repo into containers may not
|
||||
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
|
||||
|
||||
|
@ -299,7 +309,7 @@ push to the Registry connected to your project. Its password is provided in the
|
|||
of your Docker images.
|
||||
|
||||
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
|
||||
when needed. Changes to `master` also get tagged as `latest` and deployed using
|
||||
an application-specific deploy script:
|
||||
|
@ -360,17 +370,17 @@ deploy:
|
|||
Some things you should be aware of when using the Container Registry:
|
||||
|
||||
- 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
|
||||
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.
|
||||
- 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
|
||||
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
|
||||
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.
|
||||
|
||||
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
|
||||
|
|
|
@ -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
|
||||
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
|
||||
[`.gitlab-ci.yml`](../yaml/README.md).
|
||||
|
||||
|
@ -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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
The service image can run any application, but the most common use case is to
|
||||
|
@ -61,13 +61,13 @@ time the project is built.
|
|||
You can see some widely used services examples in the relevant documentation of
|
||||
[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
|
||||
[Linking containers together][linking-containers].
|
||||
|
||||
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`.
|
||||
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:
|
|||
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.
|
||||
|
||||
## Define an image from a private Docker registry
|
||||
|
@ -167,7 +167,7 @@ services:
|
|||
- 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`.
|
||||
|
||||
The alias hostname for the service is made from the image name following these
|
||||
|
@ -202,21 +202,21 @@ See the specific documentation for
|
|||
|
||||
## 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.
|
||||
|
||||
1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`.
|
||||
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).
|
||||
1. Create build container and link any service container to build container.
|
||||
1. Start build container and send build script to the container.
|
||||
1. Run build script.
|
||||
1. Start build container and send job script to the container.
|
||||
1. Run job script.
|
||||
1. Checkout code in: `/builds/group-name/project-name/`.
|
||||
1. Run any step defined in `.gitlab-ci.yml`.
|
||||
1. Check exit status of build script.
|
||||
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
|
||||
able to run docker with your regular user account.*
|
||||
|
|
|
@ -12,7 +12,7 @@ API.
|
|||
---
|
||||
|
||||
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
|
||||
it's hidden from the left sidebar menu.
|
||||
|
||||
|
|
|
@ -75,7 +75,7 @@ We have defined 3 [stages](yaml/README.md#stages):
|
|||
- deploy
|
||||
|
||||
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
|
||||
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
|
||||
|
@ -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 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
|
||||
branch and the Git SHA of the commit
|
||||
- The exact time the last deployment was performed
|
||||
|
@ -219,9 +219,9 @@ deploy_prod:
|
|||
|
||||
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.
|
||||
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) |
|
||||
|
||||
|
@ -419,7 +419,7 @@ Behind the scenes:
|
|||
- GitLab Runner picks up the changes and starts running the jobs
|
||||
- The jobs run sequentially as defined in `stages`
|
||||
- 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
|
||||
branch
|
||||
|
||||
|
|
|
@ -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.**
|
||||
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.
|
||||
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):
|
||||
1. `$SECRET_VARIABLE` - use it for non-Windows runners
|
||||
|
|
|
@ -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;
|
||||
2. We create the `~/.ssh` folder;
|
||||
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.
|
||||
|
||||
|
|
|
@ -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
|
||||
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.
|
||||
|
||||
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
|
||||
about [Using Docker images](../docker/using_docker_images.md#what-is-image)).
|
||||
|
||||
|
@ -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
|
||||
provided by the official php docker image that you can use to easilly install
|
||||
extensions. For more information read the the documentation at
|
||||
provided by the official php docker image that you can use to easily install
|
||||
extensions. For more information read the documentation at
|
||||
<https://hub.docker.com/r/_/php/>.
|
||||
|
||||
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
|
|||
|
||||
## 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
|
||||
dependencies are installed.
|
||||
|
||||
|
@ -280,7 +280,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
|
|||
[shared runners](../runners/README.md).
|
||||
|
||||
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/
|
||||
[phpenv]: https://github.com/phpenv/phpenv
|
||||
|
|
|
@ -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
|
||||
`build.sbt`.
|
||||
|
||||
## Display test coverage in build
|
||||
## Display test coverage in job
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
|
|
@ -1,14 +1,14 @@
|
|||
# Using Git submodules with GitLab CI
|
||||
|
||||
> **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.
|
||||
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`
|
||||
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
|
||||
[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.
|
||||
|
||||
## Configuring the `.gitmodules` file
|
||||
|
@ -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,
|
||||
you must update your `.gitmodules` file to use **relative URLs**.
|
||||
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:
|
||||
|
||||
```ini
|
||||
|
@ -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
|
||||
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
|
||||
clones will continue using SSH.
|
||||
|
||||
|
@ -57,13 +57,13 @@ Once `.gitmodules` is correctly configured, you can move on to
|
|||
## Using Git submodules in your CI jobs
|
||||
|
||||
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)
|
||||
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
|
||||
`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
|
||||
variables:
|
||||
GIT_SUBMODULE_STRATEGY: recursive
|
||||
|
@ -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
|
||||
submodule URL including the token in `.git/config`
|
||||
(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
|
||||
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.
|
||||
|
||||
[gitpro]: ../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
|
||||
|
|
|
@ -1,14 +1,14 @@
|
|||
# Introduction to pipelines and builds
|
||||
# Introduction to pipelines and jobs
|
||||
|
||||
>**Note:**
|
||||
Introduced in GitLab 8.8.
|
||||
|
||||
## Pipelines
|
||||
|
||||
A pipeline is a group of [builds][] that get executed in [stages][](batches).
|
||||
All of the builds in a stage are executed in parallel (if there are enough
|
||||
A pipeline is a group of [jobs][] that get executed in [stages][](batches).
|
||||
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
|
||||
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.
|
||||
|
||||
![Pipelines example](img/pipelines.png)
|
||||
|
@ -35,10 +35,10 @@ Example continuous delivery flow:
|
|||
|
||||
![CD Flow](img/pipelines-goal.svg)
|
||||
|
||||
## Builds
|
||||
## Jobs
|
||||
|
||||
Builds are individual runs of [jobs]. Not to be confused with a `build` job or
|
||||
`build` stage.
|
||||
Jobs can be defined in the [`.gitlab-ci.yml`][jobs-yaml] file. Not to be
|
||||
confused with a `build` job or `build` stage.
|
||||
|
||||
## Defining pipelines
|
||||
|
||||
|
@ -52,11 +52,11 @@ See full [documentation](yaml/README.md#jobs).
|
|||
You can find the current and historical pipeline runs under **Pipelines** for
|
||||
your project.
|
||||
|
||||
## Seeing build status
|
||||
## Seeing job status
|
||||
|
||||
Clicking on a pipeline will show the builds that were run for that pipeline.
|
||||
Clicking on an individual build will show you its build trace, and allow you to
|
||||
cancel the build, retry it, or erase the build trace.
|
||||
Clicking on a pipeline will show the jobs that were run for that pipeline.
|
||||
Clicking on an individual job will show you its job trace, and allow you to
|
||||
cancel the job, retry it, or erase the job trace.
|
||||
|
||||
## How the pipeline duration is calculated
|
||||
|
||||
|
@ -91,11 +91,11 @@ total running time should be:
|
|||
|
||||
## 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.
|
||||
|
||||
[builds]: #builds
|
||||
[jobs]: yaml/README.md#jobs
|
||||
[jobs]: #jobs
|
||||
[jobs-yaml]: yaml/README.md#jobs
|
||||
[stages]: yaml/README.md#stages
|
||||
[runners]: runners/README.html
|
||||
[pipelines settings]: ../user/project/pipelines/settings.md
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# Quick Start
|
||||
# Getting started with GitLab 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
|
||||
|
@ -7,7 +7,7 @@ projects.
|
|||
GitLab offers a [continuous integration][ci] service. If you
|
||||
[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
|
||||
and configure your GitLab project to use a [Runner], then each merge request or
|
||||
push triggers your CI [pipeline].
|
||||
push, triggers your CI [pipeline].
|
||||
|
||||
The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs
|
||||
a pipeline with three [stages]: `build`, `test`, and `deploy`. 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:
|
|||
|
||||
From there on, on every push to your Git repository, the Runner will
|
||||
automagically start the pipeline and the pipeline will appear under the
|
||||
project's `/pipelines` page.
|
||||
project's **Pipelines** page.
|
||||
|
||||
---
|
||||
|
||||
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)
|
||||
- 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.
|
|||
It lives in the root of your repository.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
|||
You can read more about the reasons why we are using `.gitlab-ci.yml` [in our
|
||||
blog about it][blog-ci].
|
||||
|
||||
**Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file
|
||||
so you have to pay extra attention to indentation. Always use spaces, not tabs.
|
||||
|
||||
### 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
|
||||
repository. Below is an example for a Ruby on Rails project.
|
||||
|
||||
|
@ -88,7 +89,7 @@ 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:
|
||||
|
||||
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
|
||||
|
@ -98,22 +99,22 @@ applications:
|
|||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
**Pipelines > Builds** in your project.
|
||||
a "CI Lint" button to go to this page under **Pipelines ➔ Pipelines** and
|
||||
**Pipelines ➔ Jobs** in your project.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
|
@ -125,28 +126,27 @@ git push origin master
|
|||
Now if you go to the **Pipelines** page you will see that the pipeline is
|
||||
pending.
|
||||
|
||||
You can also go to the **Commits** page and notice the little clock icon next
|
||||
You can also go to the **Commits** page and notice the little pause icon next
|
||||
to the commit SHA.
|
||||
|
||||
![New commit pending](img/new_commit.png)
|
||||
|
||||
Clicking on the clock icon you will be directed to the builds page for that
|
||||
specific commit.
|
||||
Clicking on it you will be directed to the jobs page for that 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
|
||||
`.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
|
||||
|
||||
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
|
||||
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
|
||||
GitLab. If it serves all projects it's called a _Shared Runner_.
|
||||
|
@ -155,9 +155,9 @@ Find more information about different Runners in the
|
|||
[Runners](../runners/README.md) documentation.
|
||||
|
||||
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
|
||||
official Runner supported by GitLab is written in Go and can be found at
|
||||
<https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>.
|
||||
**Settings ➔ Runners**. Setting up a Runner is easy and straightforward. The
|
||||
official Runner supported by GitLab is written in Go and its documentation
|
||||
can be found at <https://docs.gitlab.com/runner/>.
|
||||
|
||||
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
|
||||
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
|
||||
project, following **Settings > Runners**.
|
||||
project, following **Settings ➔ Runners**.
|
||||
|
||||
![Activated runners](img/runners_activated.png)
|
||||
|
||||
### 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.
|
||||
|
||||
These are special virtual machines that run on GitLab's infrastructure and can
|
||||
build any project.
|
||||
|
||||
To enable **Shared Runners** you have to go to your project's
|
||||
**Settings > Runners** and click **Enable shared runners**.
|
||||
To enable the **Shared Runners** you have to go to your project's
|
||||
**Settings ➔ Runners** and click **Enable shared runners**.
|
||||
|
||||
[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
|
||||
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.
|
|||
|
||||
![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)
|
||||
|
||||
By clicking on a Build ID, you will be able to see the log of that build.
|
||||
This is important to diagnose why a build failed or acted differently than
|
||||
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 job failed or acted differently than
|
||||
you expected.
|
||||
|
||||
![Build log](img/build_log.png)
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
CI with various languages.
|
||||
|
||||
Awesome! You started using CI in GitLab!
|
||||
|
||||
[runner-install]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tree/master#install-gitlab-runner
|
||||
[runner-install]: https://docs.gitlab.com/runner/install/
|
||||
[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
|
||||
[examples]: ../examples/README.md
|
||||
[ci]: https://about.gitlab.com/gitlab-ci/
|
||||
|
@ -235,3 +230,4 @@ Awesome! You started using CI in GitLab!
|
|||
[enabled]: ../enable_or_disable_ci.md
|
||||
[stages]: ../yaml/README.md#stages
|
||||
[pipeline]: ../pipelines.md
|
||||
[internet]: https://about.gitlab.com/images/theinternet.png
|
||||
|
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 19 KiB |
Before Width: | Height: | Size: 4.7 KiB After Width: | Height: | Size: 5.5 KiB |
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 22 KiB |
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 18 KiB |
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 13 KiB |
Before Width: | Height: | Size: 9.3 KiB |
|
@ -1,162 +1,163 @@
|
|||
# Runners
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
`Allow shared runners`.
|
||||
`Allow shared Runners`.
|
||||
|
||||
**Shared runners** are useful for jobs that have similar requirements,
|
||||
between multiple projects. Rather than having multiple runners idling for
|
||||
many projects, you can have a single or a small number of runners that handle
|
||||
multiple projects. This makes it easier to maintain and update runners.
|
||||
**Shared Runners** are useful for jobs that have similar requirements,
|
||||
between multiple projects. Rather than having multiple Runners idling for
|
||||
many projects, you can have a single or a small number of Runners that handle
|
||||
multiple projects. This makes it easier to maintain and update Runners.
|
||||
|
||||
**Specific runners** are useful for jobs that have special requirements or for
|
||||
**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
|
||||
up the specific runner with this in mind, while not having to do this for all
|
||||
runners. For example, if you want to deploy a certain project, you can setup
|
||||
a specific runner to have the right credentials for this.
|
||||
up the specific Runner with this in mind, while not having to do this for all
|
||||
Runners. For example, if you want to deploy a certain project, you can setup
|
||||
a specific Runner to have the right credentials for this.
|
||||
|
||||
Projects with high demand of CI activity can also benefit from using specific runners.
|
||||
By having dedicated runners you are guaranteed that the runner is not being held
|
||||
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
|
||||
up by another project's jobs.
|
||||
|
||||
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
|
||||
the runner to be able to run its jobs.
|
||||
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
|
||||
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.
|
||||
|
||||
# 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.
|
||||
|
||||
[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.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
![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
|
||||
`DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared runners to
|
||||
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
|
||||
disabled.
|
||||
|
||||
## Registering a Specific Runner
|
||||
|
||||
Registering a specific can be done in two ways:
|
||||
|
||||
1. Creating a runner with the project registration token
|
||||
1. Converting a shared runner into a specific runner (one-way, admin only)
|
||||
1. Creating a Runner with the project registration token
|
||||
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
|
||||
concern registering the runner on GitLab CI.
|
||||
There are several ways to create a Runner instance. The steps below only
|
||||
concern registering the Runner on GitLab CI.
|
||||
|
||||
### Registering a Specific Runner with a Project Registration token
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Click on the runner tab and use the registration token you find there to
|
||||
setup a specific runner for this project.
|
||||
Click on the Runner tab and use the registration token you find there to
|
||||
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
|
||||
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*.
|
||||
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.
|
||||
This setting is available on each Runner in *Project Settings* > *Runners*.
|
||||
|
||||
### Making an existing Shared Runner Specific
|
||||
|
||||
If you are an admin on your GitLab instance,
|
||||
you can make any shared runner a specific runner, _but you can not
|
||||
make a specific runner a shared runner_.
|
||||
you can make any shared Runner a specific Runner, _but you can not
|
||||
make a specific Runner a shared Runner_.
|
||||
|
||||
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
|
||||
run exclusively for these projects, therefore making it a specific runner.
|
||||
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
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
problematic for large amounts of projects, if it wasn't for tags.
|
||||
|
||||
By tagging a Runner for the types of jobs it can handle, you can make sure
|
||||
shared runners will only run the jobs they are equipped to run.
|
||||
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.
|
||||
|
||||
### 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
|
||||
the runner does not have tags assigned. This setting is available on each
|
||||
runner in *Project Settings* > *Runners*.
|
||||
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
|
||||
Runner in *Project Settings* > *Runners*.
|
||||
|
||||
### Be careful with sensitive information
|
||||
|
||||
If you can run a build on a runner, you can get access to any code it runs
|
||||
and get the token of the runner. With shared runners, this means that anyone
|
||||
that runs jobs on the runner, can access anyone else's code that runs on the runner.
|
||||
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
|
||||
that runs jobs on the Runner, can access anyone else's code that runs on the Runner.
|
||||
|
||||
In addition, because you can get access to the runner token, it is possible
|
||||
to create a clone of a runner and submit false builds, for example.
|
||||
In addition, because you can get access to the Runner token, it is possible
|
||||
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.
|
||||
|
||||
### Forks
|
||||
|
||||
Whenever a project is forked, it copies the settings of the jobs that relate
|
||||
to it. This means that if you have shared runners setup for a project and
|
||||
someone forks that project, the shared runners will also serve jobs of this
|
||||
to it. This means that if you have shared Runners setup for a project and
|
||||
someone forks that project, the shared Runners will also serve jobs of this
|
||||
project.
|
||||
|
||||
## Attack vectors in Runners
|
||||
|
||||
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).
|
||||
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://docs.gitlab.com/runner/security/).
|
||||
|
|
|
@ -31,7 +31,7 @@ Database: el_duderino
|
|||
```
|
||||
|
||||
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].
|
||||
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
|
|||
available [shared runners](../runners/README.md).
|
||||
|
||||
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/
|
||||
[mysql-example-repo]: https://gitlab.com/gitlab-examples/mysql
|
||||
|
|
|
@ -31,7 +31,7 @@ Database: nice_marmot
|
|||
```
|
||||
|
||||
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].
|
||||
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
|
|||
available [shared runners](../runners/README.md).
|
||||
|
||||
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/
|
||||
[postgres-example-repo]: https://gitlab.com/gitlab-examples/postgres
|
||||
|
|
|
@ -63,7 +63,7 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available
|
|||
[shared runners](../runners/README.md).
|
||||
|
||||
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/
|
||||
[redis-example-repo]: https://gitlab.com/gitlab-examples/redis
|
||||
|
|
|
@ -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][]
|
||||
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
|
||||
|
||||
|
@ -77,7 +77,7 @@ SSH key.
|
|||
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.
|
||||
|
||||
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
|
||||
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
|
|||
[shared runners](../runners/README.md).
|
||||
|
||||
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-agent]: http://linux.die.net/man/1/ssh-agent
|
||||
|
|
|
@ -1,19 +1,19 @@
|
|||
# Triggering Builds through the API
|
||||
|
||||
> [Introduced][ci-229] in GitLab CE 7.14.
|
||||
# Triggering jobs through the API
|
||||
|
||||
> **Note**:
|
||||
GitLab 8.12 has a completely redesigned build permissions system.
|
||||
Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#build-triggers).
|
||||
- [Introduced][ci-229] in GitLab CE 7.14.
|
||||
- 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)
|
||||
with an API call.
|
||||
|
||||
## Add a trigger
|
||||
|
||||
You can add a new trigger by going to your project's **Settings > Triggers**.
|
||||
The **Add trigger** button will create a new token which you can then use to
|
||||
trigger a rebuild of this particular project.
|
||||
You can add a new trigger by going to your project's
|
||||
**Settings ➔ CI/CD Pipelines ➔ Triggers**. The **Add trigger** button will
|
||||
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
|
||||
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
|
|||
**Settings > Triggers** and hitting the **Revoke** button. The action is
|
||||
irreversible.
|
||||
|
||||
## Trigger a build
|
||||
## Trigger a job
|
||||
|
||||
> **Note**:
|
||||
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
|
||||
|
@ -42,31 +42,32 @@ POST /projects/:id/trigger/builds
|
|||
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`
|
||||
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
|
||||
the **Builds** page and the builds are marked as `triggered`.
|
||||
When a rerun of a pipeline is triggered, the information is exposed in GitLab's
|
||||
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.
|
||||
The token of the trigger is exposed in the UI as you can see from the image
|
||||
You can see which trigger caused the rebuild by visiting the single job page.
|
||||
A part of the trigger's token is exposed in the UI as you can see from the image
|
||||
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
|
||||
trigger a rebuild.
|
||||
|
||||
## Trigger a build from webhook
|
||||
## Trigger a job from webhook
|
||||
|
||||
> 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:
|
||||
|
||||
```
|
||||
|
@ -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.
|
||||
- `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
|
||||
will be available in GitLab CI so that they can be used in your `.gitlab-ci.yml`
|
||||
|
@ -90,7 +91,7 @@ variables[key]=value
|
|||
|
||||
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 \
|
|||
"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 have two projects, A and B, and you want to trigger a rebuild on the `master`
|
||||
|
@ -132,7 +133,7 @@ build_docs:
|
|||
- 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
|
||||
`stage: deploy` ensures that this job will run only after all jobs with
|
||||
`stage: test` complete successfully.
|
||||
|
@ -189,18 +190,18 @@ curl --request POST \
|
|||
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
|
||||
```
|
||||
|
||||
### 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
|
||||
in conjunction with cron. The example below triggers a build on the `master`
|
||||
Whether you craft a script or just run cURL directly, you can trigger jobs
|
||||
in conjunction with cron. The example below triggers a job on the `master`
|
||||
branch of project with ID `9` every night at `00:30`:
|
||||
|
||||
```bash
|
||||
|
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 20 KiB |
Before Width: | Height: | Size: 8.0 KiB After Width: | Height: | Size: 6.4 KiB |
Before Width: | Height: | Size: 3.6 KiB After Width: | Height: | Size: 3.6 KiB |
Before Width: | Height: | Size: 5.0 KiB After Width: | Height: | Size: 5.0 KiB |
|
@ -1,6 +1,6 @@
|
|||
# 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)
|
||||
and a list of **user-defined variables**.
|
||||
|
||||
|
@ -29,22 +29,22 @@ version of Runner required.
|
|||
|
||||
| Variable | GitLab | Runner | Description |
|
||||
|-------------------------|--------|--------|-------------|
|
||||
| **CI** | all | 0.4 | Mark that build is executed in CI environment |
|
||||
| **GITLAB_CI** | all | all | Mark that build is executed in GitLab CI environment |
|
||||
| **CI_SERVER** | all | all | Mark that build is executed in CI environment |
|
||||
| **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate builds |
|
||||
| **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule builds |
|
||||
| **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule builds |
|
||||
| **CI_BUILD_ID** | all | all | The unique id of the current build that GitLab CI uses internally |
|
||||
| **CI** | all | 0.4 | Mark that job is executed in CI environment |
|
||||
| **GITLAB_CI** | all | all | Mark that job is executed in GitLab 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 jobs |
|
||||
| **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 jobs |
|
||||
| **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_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_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_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_MANUAL** | 8.12 | all | The flag to indicate that build was manually started |
|
||||
| **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 job was manually started |
|
||||
| **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_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally |
|
||||
|
@ -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_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_DIR** | all | all | The full path where the repository is cloned and where the build is run |
|
||||
| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this build |
|
||||
| **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 job |
|
||||
| **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_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.
|
|||
| **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_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 |
|
||||
| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a build |
|
||||
| **RESTORE_CACHE_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to restore the cache running a build |
|
||||
| **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the build |
|
||||
| **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the 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 job |
|
||||
| **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 job |
|
||||
| **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the job |
|
||||
|
||||
|
||||
Example values:
|
||||
|
@ -136,7 +136,7 @@ job_name:
|
|||
>**Notes:**
|
||||
- This feature requires GitLab Runner 0.4.0 or higher.
|
||||
- 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
|
||||
settings. Follow the discussion in issue [#13784][ce-13784] for masking the
|
||||
secret variables.
|
||||
|
@ -150,7 +150,7 @@ storing things like passwords, secret keys and credentials.
|
|||
Secret variables can be added by going to your project's
|
||||
**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
|
||||
|
||||
|
@ -160,7 +160,7 @@ This feature requires GitLab CI 8.15 or higher.
|
|||
[Project services](../../user/project/integrations/project_services.md) that are
|
||||
responsible for deployment configuration may define their own variables that
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
in build traces!
|
||||
in job traces!
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`:
|
||||
|
@ -320,7 +320,7 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'
|
|||
|
||||
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.
|
||||
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,
|
||||
prefix the variable name with the dollar sign (`$`):
|
||||
|
@ -328,12 +328,12 @@ prefix the variable name with the dollar sign (`$`):
|
|||
```
|
||||
job_name:
|
||||
script:
|
||||
- echo $CI_BUILD_ID
|
||||
- echo $CI_job_ID
|
||||
```
|
||||
|
||||
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
|
||||
you set, in the build log:
|
||||
you set, in the job log:
|
||||
|
||||
```
|
||||
job_name:
|
||||
|
@ -344,4 +344,4 @@ job_name:
|
|||
[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784
|
||||
[runner]: https://docs.gitlab.com/runner/
|
||||
[triggered]: ../triggers/README.md
|
||||
[triggers]: ../triggers/README.md#pass-build-variables-to-a-trigger
|
||||
[triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
# 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
|
||||
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
|
||||
[quick start guide](../quick_start/README.md).
|
||||
|
@ -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`)
|
||||
or run a script (`test.sh`) in the repository.
|
||||
|
||||
Jobs are used to create builds, which are then picked up by
|
||||
[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.
|
||||
Jobs are picked up by [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.
|
||||
|
||||
The YAML syntax allows for using more complex job specifications than in the
|
||||
above example:
|
||||
|
@ -80,30 +79,31 @@ There are a few reserved `keywords` that **cannot** be used as job names:
|
|||
### image and services
|
||||
|
||||
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).
|
||||
|
||||
### before_script
|
||||
|
||||
`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
|
||||
|
||||
> 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
|
||||
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` 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 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. Builds of the next stage are run after the jobs from the previous stage
|
||||
1. Jobs of the same stage are run in parallel.
|
||||
1. Jobs of the next stage are run after the jobs from the previous stage
|
||||
complete successfully.
|
||||
|
||||
Let's consider the following example, which defines 3 stages:
|
||||
|
@ -115,7 +115,7 @@ stages:
|
|||
- 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 `test` succeed, the `deploy` jobs are executed in parallel.
|
||||
1. If all jobs of `deploy` succeed, the commit is marked as `success`.
|
||||
|
@ -124,7 +124,7 @@ stages:
|
|||
|
||||
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.
|
||||
2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
|
||||
|
||||
|
@ -137,7 +137,7 @@ Alias for [stages](#stages).
|
|||
> Introduced in GitLab Runner v0.5.0.
|
||||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
|
@ -163,7 +163,7 @@ which can be set in GitLab's UI.
|
|||
> Introduced in GitLab Runner v0.7.0.
|
||||
|
||||
`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.
|
||||
|
||||
**By default the caching is enabled per-job and per-branch.**
|
||||
|
@ -202,8 +202,8 @@ rspec:
|
|||
- binaries/
|
||||
```
|
||||
|
||||
Locally defined cache overwrites globally defined options. This will cache only
|
||||
`binaries/`:
|
||||
Locally defined cache overwrites globally defined options. The following `rspec`
|
||||
job will cache only `binaries/`:
|
||||
|
||||
```yaml
|
||||
cache:
|
||||
|
@ -281,8 +281,8 @@ cache:
|
|||
## Jobs
|
||||
|
||||
`.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.
|
||||
A job is defined by a list of parameters that define the build behavior.
|
||||
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 job behavior.
|
||||
|
||||
```yaml
|
||||
job_name:
|
||||
|
@ -305,20 +305,20 @@ job_name:
|
|||
| 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) |
|
||||
| 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` |
|
||||
| variables | no | Define build variables on a job level |
|
||||
| only | no | Defines a list of git refs for which build is created |
|
||||
| except | no | Defines a list of git refs for which build is not created |
|
||||
| variables | no | Define job variables on a job level |
|
||||
| only | no | Defines a list of git refs for which job is 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 |
|
||||
| allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status |
|
||||
| when | no | Define when to run build. 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|
|
||||
| artifacts | no | Define list of build artifacts |
|
||||
| allow_failure | no | Allow job to fail. Failed job doesn't contribute to commit status |
|
||||
| when | no | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` |
|
||||
| dependencies | no | Define other jobs that a job depends on so that you can pass artifacts between them|
|
||||
| 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 |
|
||||
| before_script | no | Override a set of commands that are executed before build |
|
||||
| after_script | no | Override a set of commands that are executed after build |
|
||||
| environment | no | Defines a name of environment to which deployment is done by this 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 job |
|
||||
| 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 |
|
||||
|
||||
### script
|
||||
|
@ -339,11 +339,15 @@ job:
|
|||
- 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` 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
|
||||
[stages](#stages).
|
||||
|
||||
|
@ -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
|
||||
jobs are built:
|
||||
|
||||
1. `only` defines the names of branches and tags for which the job will be
|
||||
built.
|
||||
1. `only` defines the names of branches and tags for which the job will run.
|
||||
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:
|
||||
|
||||
|
@ -379,8 +382,8 @@ job:
|
|||
- branches
|
||||
```
|
||||
|
||||
In this example, `job` will run only for refs that are tagged, or if a build is explicitly requested
|
||||
via an API trigger.
|
||||
In this example, `job` will run only for refs that are tagged, or if a build is
|
||||
explicitly requested via an API trigger.
|
||||
|
||||
```yaml
|
||||
job:
|
||||
|
@ -404,14 +407,14 @@ job:
|
|||
The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
|
||||
except master.
|
||||
|
||||
### job variables
|
||||
### Job variables
|
||||
|
||||
It is possible to define build variables using a `variables` keyword on a job
|
||||
level. It works basically the same way as its [global-level equivalent](#variables)
|
||||
but allows you to define job-specific build variables.
|
||||
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),
|
||||
but allows you to define job-specific variables.
|
||||
|
||||
When the `variables` keyword is used on a job level, it overrides global YAML
|
||||
build variables and predefined variables. To turn off global defined variables
|
||||
When the `variables` keyword is used on a job level, it overrides the global YAML
|
||||
job variables and predefined ones. To turn off global defined variables
|
||||
in your job, define an empty array:
|
||||
|
||||
```yaml
|
||||
|
@ -419,8 +422,7 @@ job_name:
|
|||
variables: []
|
||||
```
|
||||
|
||||
Build variables priority is defined in the
|
||||
[variables documentation][variables].
|
||||
Job variables priority is defined in the [variables documentation][variables].
|
||||
|
||||
### tags
|
||||
|
||||
|
@ -430,7 +432,7 @@ allowed to run this project.
|
|||
During the registration of a Runner, you can specify the Runner's tags, for
|
||||
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:
|
||||
|
||||
```yaml
|
||||
|
@ -445,13 +447,13 @@ has both `ruby` AND `postgres` tags defined.
|
|||
|
||||
### allow_failure
|
||||
|
||||
`allow_failure` is used when you want to allow a build to fail without impacting
|
||||
the rest of the CI suite. Failed builds don't contribute to the commit status.
|
||||
`allow_failure` is used when you want to allow a job to fail without impacting
|
||||
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
|
||||
displayed on the merge request or commit or build page. This is to be used by
|
||||
builds that are allowed to fail, but where failure indicates some other (manual)
|
||||
displayed on the merge request or commit or job page. This is to be used by
|
||||
jobs that are allowed to fail, but where failure indicates some other (manual)
|
||||
steps should be taken elsewhere.
|
||||
|
||||
In the example below, `job1` and `job2` will run in parallel, but if `job1`
|
||||
|
@ -483,12 +485,12 @@ failure.
|
|||
|
||||
`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.
|
||||
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.
|
||||
1. `always` - execute build regardless of the status of builds from prior stages.
|
||||
1. `manual` - execute build manually (added in GitLab 8.10). Read about
|
||||
1. `always` - execute job regardless of the status of jobs from prior stages.
|
||||
1. `manual` - execute job manually (added in GitLab 8.10). Read about
|
||||
[manual actions](#manual-actions) below.
|
||||
|
||||
For example:
|
||||
|
@ -526,7 +528,7 @@ deploy_job:
|
|||
cleanup_job:
|
||||
stage: cleanup
|
||||
script:
|
||||
- cleanup after builds
|
||||
- cleanup after jobs
|
||||
when: always
|
||||
```
|
||||
|
||||
|
@ -552,10 +554,11 @@ Read more at the [environments documentation][env-manual].
|
|||
|
||||
### environment
|
||||
|
||||
> Introduced in GitLab 8.9.
|
||||
|
||||
> You can read more about environments and find more examples in the
|
||||
[documentation about environments][environment].
|
||||
>
|
||||
**Notes:**
|
||||
- Introduced in GitLab 8.9.
|
||||
- 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.
|
||||
If `environment` is specified and no environment under that name exists, a new
|
||||
|
@ -563,7 +566,7 @@ one will be created automatically.
|
|||
|
||||
In its simplest form, the `environment` keyword can be defined like:
|
||||
|
||||
```
|
||||
```yaml
|
||||
deploy to production:
|
||||
stage: deploy
|
||||
script: git push production HEAD:master
|
||||
|
@ -576,12 +579,12 @@ deployment to the `production` environment.
|
|||
|
||||
#### environment:name
|
||||
|
||||
> Introduced in GitLab 8.11.
|
||||
|
||||
>**Note:**
|
||||
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
|
||||
`name` keyword.
|
||||
>
|
||||
**Notes:**
|
||||
- Introduced in GitLab 8.11.
|
||||
- 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
|
||||
`name` keyword.
|
||||
|
||||
The `environment` name can contain:
|
||||
|
||||
|
@ -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
|
||||
the `name` keyword under `environment`:
|
||||
|
||||
```
|
||||
```yaml
|
||||
deploy to production:
|
||||
stage: deploy
|
||||
script: git push production HEAD:master
|
||||
|
@ -612,11 +615,11 @@ deploy to production:
|
|||
|
||||
#### environment:url
|
||||
|
||||
> Introduced in GitLab 8.11.
|
||||
|
||||
>**Note:**
|
||||
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`.
|
||||
>
|
||||
**Notes:**
|
||||
- Introduced in GitLab 8.11.
|
||||
- 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`.
|
||||
|
||||
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.
|
||||
|
@ -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
|
||||
to `https://prod.example.com`.
|
||||
|
||||
```
|
||||
```yaml
|
||||
deploy to production:
|
||||
stage: deploy
|
||||
script: git push production HEAD:master
|
||||
|
@ -690,8 +693,10 @@ The `stop_review_app` job is **required** to have the following keywords defined
|
|||
|
||||
#### 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`.
|
||||
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:
|
||||
|
||||
```
|
||||
```yaml
|
||||
deploy as review app:
|
||||
stage: deploy
|
||||
script: make deploy
|
||||
|
@ -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
|
||||
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
|
||||
`https://review-pow-aaaaaa.example.com/`.
|
||||
`https://review-pow.example.com/`.
|
||||
|
||||
This of course implies that the underlying server which hosts the application
|
||||
is properly configured.
|
||||
|
||||
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
|
||||
https://gitlab.com/gitlab-examples/review-apps-nginx/.
|
||||
<https://gitlab.com/gitlab-examples/review-apps-nginx/>.
|
||||
|
||||
### artifacts
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
|
||||
> - Windows support was added in GitLab Runner v.1.0.0.
|
||||
> - Currently not all executors are supported.
|
||||
> - Build artifacts are only collected for successful builds by default.
|
||||
**Notes:**
|
||||
- Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
|
||||
- Windows support was added in GitLab Runner v.1.0.0.
|
||||
- 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
|
||||
attached to the build after success. You can only use paths that are within the
|
||||
project workspace. To pass artifacts between different builds, see [dependencies](#dependencies).
|
||||
|
||||
attached to the job after success. You can only use paths that are within the
|
||||
project workspace. To pass artifacts between different jobs, see [dependencies](#dependencies).
|
||||
Below are some examples.
|
||||
|
||||
Send all files in `binaries` and `.config`:
|
||||
|
@ -794,7 +798,7 @@ release-job:
|
|||
- 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.
|
||||
|
||||
#### artifacts:name
|
||||
|
@ -811,7 +815,7 @@ The default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
|
|||
|
||||
**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
|
||||
job:
|
||||
|
@ -829,7 +833,7 @@ job:
|
|||
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:
|
||||
|
||||
```yaml
|
||||
|
@ -864,20 +868,20 @@ job:
|
|||
|
||||
> 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.
|
||||
|
||||
`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_failure` - upload artifacts only when the build fails.
|
||||
1. `always` - upload artifacts regardless of the build status.
|
||||
1. `on_success` - upload artifacts only when the job succeeds. This is the default.
|
||||
1. `on_failure` - upload artifacts only when the job fails.
|
||||
1. `always` - upload artifacts regardless of the job status.
|
||||
|
||||
---
|
||||
|
||||
**Example configurations**
|
||||
|
||||
To upload artifacts only when build fails.
|
||||
To upload artifacts only when job fails.
|
||||
|
||||
```yaml
|
||||
job:
|
||||
|
@ -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
|
||||
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.
|
||||
|
||||
After expiry, artifacts are actually deleted hourly by default (via a cron job),
|
||||
but they are not accessible after expiry.
|
||||
|
||||
The value of `expire_in` is an elapsed time. Examples of parseable values:
|
||||
|
||||
- '3 mins 4 sec'
|
||||
- '2 hrs 20 min'
|
||||
- '2h20min'
|
||||
|
@ -925,14 +930,14 @@ job:
|
|||
> Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
You can only define builds 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.
|
||||
a list of all previous jobs from which the artifacts should be downloaded.
|
||||
You can only define jobs from stages that are executed before the current one.
|
||||
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.
|
||||
|
||||
---
|
||||
|
@ -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
|
||||
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:
|
||||
|
||||
```yaml
|
||||
|
@ -979,7 +984,7 @@ deploy:
|
|||
|
||||
### 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
|
||||
before_script:
|
||||
|
@ -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
|
||||
job, ensuring that the project workspace is always pristine.
|
||||
|
||||
```
|
||||
```yaml
|
||||
variables:
|
||||
GIT_STRATEGY: clone
|
||||
```
|
||||
|
@ -1036,7 +1041,7 @@ variables:
|
|||
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.
|
||||
|
||||
```
|
||||
```yaml
|
||||
variables:
|
||||
GIT_STRATEGY: fetch
|
||||
```
|
||||
|
@ -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
|
||||
rely on files brought into the project workspace from cache or artifacts.
|
||||
|
||||
```
|
||||
```yaml
|
||||
variables:
|
||||
GIT_STRATEGY: none
|
||||
```
|
||||
|
@ -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)
|
||||
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
|
||||
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
|
||||
equivalent to:
|
||||
|
||||
```
|
||||
$ git submodule sync
|
||||
$ git submodule update --init
|
||||
git submodule sync
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
- `recursive` means that all submodules (including submodules of submodules)
|
||||
will be included. It is equivalent to:
|
||||
|
||||
```
|
||||
$ git submodule sync --recursive
|
||||
$ git submodule update --init --recursive
|
||||
git submodule sync --recursive
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Note that for this feature to work correctly, the submodules must be configured
|
||||
(in `.gitmodules`) with either:
|
||||
|
||||
- the HTTP(S) URL of a publicly-accessible repository, or
|
||||
- a relative path to another repository on the same GitLab server. See the
|
||||
[Git submodules](../git_submodules.md) documentation.
|
||||
|
||||
|
||||
## Build stages attempts
|
||||
## Job stages attempts
|
||||
|
||||
> 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:
|
||||
|
||||
| Variable | Description |
|
||||
|-------------------------|-------------|
|
||||
| **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a build |
|
||||
| **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a build |
|
||||
| **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache 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 job |
|
||||
| **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a job |
|
||||
|
||||
The default is one single attempt.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```yaml
|
||||
variables:
|
||||
GET_SOURCES_ATTEMPTS: "3"
|
||||
```
|
||||
|
||||
You can set them in the global [`variables`](#variables) section or the [`variables`](#job-variables)
|
||||
section for individual jobs.
|
||||
You can set them in the global [`variables`](#variables) section or the
|
||||
[`variables`](#job-variables) section for individual jobs.
|
||||
|
||||
## Shallow cloning
|
||||
|
||||
|
@ -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`.
|
||||
|
||||
>**Note:**
|
||||
If you use a depth of 1 and have a queue of builds or retry
|
||||
builds, jobs may fail.
|
||||
If you use a depth of 1 and have a queue of jobs or retry
|
||||
jobs, jobs may fail.
|
||||
|
||||
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
|
||||
you are retrying an old build, 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
|
||||
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 jobs in the queue, or
|
||||
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
|
||||
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
|
||||
set since only part of the git history is present.
|
||||
Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is
|
||||
set since only part of the Git history is present.
|
||||
|
||||
To fetch or clone only the last 3 commits:
|
||||
```
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
GIT_DEPTH: "3"
|
||||
```
|
||||
|
@ -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.
|
||||
|
||||
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
|
||||
properties, and is a perfect example to be used with [hidden keys](#hidden-keys)
|
||||
to provide templates for your jobs.
|
||||
|
@ -1326,17 +1335,17 @@ pages:
|
|||
- 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
|
||||
|
||||
Each instance of GitLab CI has an embedded debug tool called Lint.
|
||||
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
|
||||
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
|
||||
|
||||
|
|
|
@ -69,7 +69,7 @@ experience, refactors the existing code). Then:
|
|||
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
|
||||
"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.
|
||||
- If you set the MR to "Merge When Pipeline Succeeds", you should take over
|
||||
subsequent revisions for anything that would be spotted after that.
|
||||
|
|
|
@ -307,7 +307,7 @@ sudo usermod -aG redis git
|
|||
# now that files in public/uploads are served by gitlab-workhorse
|
||||
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/
|
||||
|
||||
# Change the permissions of the directory where CI artifacts are stored
|
||||
|
|
|
@ -44,8 +44,8 @@ environment variable `SKIP`. You can skip:
|
|||
- `db` (database)
|
||||
- `uploads` (attachments)
|
||||
- `repositories` (Git repositories data)
|
||||
- `builds` (CI build output logs)
|
||||
- `artifacts` (CI build artifacts)
|
||||
- `builds` (CI job output logs)
|
||||
- `artifacts` (CI job artifacts)
|
||||
- `lfs` (LFS objects)
|
||||
- `registry` (Container Registry images)
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
### 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) 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) job triggers.
|
||||
|
||||
### CEPH
|
||||
|
||||
|
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
## 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
|
||||
this setting is set for each build.
|
||||
this setting is set for each job.
|
||||
|
||||
1. Go to **Admin area > Settings** (`/admin/application_settings`).
|
||||
|
||||
|
@ -17,4 +17,4 @@ this setting is set for each build.
|
|||
1. Hit **Save** for the changes to take effect.
|
||||
|
||||
|
||||
[art-yml]: ../../../administration/build_artifacts.md
|
||||
[art-yml]: ../../../administration/job_artifacts.md
|
||||
|
|
|
@ -22,9 +22,9 @@ The following table depicts the various user permission levels in a project.
|
|||
| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| View confidential issues | (✓) [^1] | ✓ | ✓ | ✓ | ✓ |
|
||||
| Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| See a list of builds | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| See a build log | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| Download and browse build artifacts | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| See a list of jobs | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| See a job log | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| Download and browse job artifacts | ✓ [^2] | ✓ | ✓ | ✓ | ✓ |
|
||||
| View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
| Pull project code | | ✓ | ✓ | ✓ | ✓ |
|
||||
| Download project | | ✓ | ✓ | ✓ | ✓ |
|
||||
|
@ -46,7 +46,7 @@ The following table depicts the various user permission levels in a project.
|
|||
| Remove non-protected branches | | | ✓ | ✓ | ✓ |
|
||||
| Add tags | | | ✓ | ✓ | ✓ |
|
||||
| Write a wiki | | | ✓ | ✓ | ✓ |
|
||||
| Cancel and retry builds | | | ✓ | ✓ | ✓ |
|
||||
| Cancel and retry jobs | | | ✓ | ✓ | ✓ |
|
||||
| Create or update commit status | | | ✓ | ✓ | ✓ |
|
||||
| Update a container registry | | | ✓ | ✓ | ✓ |
|
||||
| Remove a container registry image | | | ✓ | ✓ | ✓ |
|
||||
|
@ -60,7 +60,7 @@ The following table depicts the various user permission levels in a project.
|
|||
| Add deploy keys to project | | | | ✓ | ✓ |
|
||||
| Configure project hooks | | | | ✓ | ✓ |
|
||||
| Manage runners | | | | ✓ | ✓ |
|
||||
| Manage build triggers | | | | ✓ | ✓ |
|
||||
| Manage job triggers | | | | ✓ | ✓ |
|
||||
| Manage variables | | | | ✓ | ✓ |
|
||||
| Manage pages | | | | ✓ | ✓ |
|
||||
| Manage pages domains and certificates | | | | ✓ | ✓ |
|
||||
|
@ -134,8 +134,8 @@ instance and project. In addition, all admins can use the admin interface under
|
|||
|
||||
| Action | Guest, Reporter | Developer | Master | Admin |
|
||||
|---------------------------------------|-----------------|-------------|----------|--------|
|
||||
| See commits and builds | ✓ | ✓ | ✓ | ✓ |
|
||||
| Retry or cancel build | | ✓ | ✓ | ✓ |
|
||||
| See commits and jobs | ✓ | ✓ | ✓ | ✓ |
|
||||
| Retry or cancel job | | ✓ | ✓ | ✓ |
|
||||
| Remove project | | | ✓ | ✓ |
|
||||
| Create project | | | ✓ | ✓ |
|
||||
| Change project configuration | | | ✓ | ✓ |
|
||||
|
@ -144,18 +144,18 @@ instance and project. In addition, all admins can use the admin interface under
|
|||
| See events in the system | | | | ✓ |
|
||||
| Admin interface | | | | ✓ |
|
||||
|
||||
### Builds permissions
|
||||
### Jobs permissions
|
||||
|
||||
>**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].
|
||||
|
||||
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:
|
||||
|
||||
| Action | Guest, Reporter | Developer | Master | Admin |
|
||||
|---------------------------------------------|-----------------|-------------|----------|--------|
|
||||
| Run CI build | | ✓ | ✓ | ✓ |
|
||||
| Run CI job | | ✓ | ✓ | ✓ |
|
||||
| Clone source and LFS from current project | | ✓ | ✓ | ✓ |
|
||||
| Clone source and LFS from public projects | | ✓ | ✓ | ✓ |
|
||||
| Clone source and LFS from internal projects | | ✓ [^4] | ✓ [^4] | ✓ |
|
||||
|
|
|
@ -1,136 +1 @@
|
|||
# Introduction to build artifacts
|
||||
|
||||
>**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"
|
||||
This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md).
|
||||
|
|
Before Width: | Height: | Size: 3.7 KiB |
Before Width: | Height: | Size: 4.8 KiB |
Before Width: | Height: | Size: 22 KiB |
Before Width: | Height: | Size: 28 KiB |
|
@ -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
|
||||
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.
|
||||
|
||||
Navigate to the webhooks page by going to the **Integrations** page from your
|
||||
|
|
|
@ -22,7 +22,7 @@ in a merged merge requests or a commit.
|
|||
## Merge when pipeline succeeds
|
||||
|
||||
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
|
||||
and remember to merge the request manually.
|
||||
|
||||
|
|
|
@ -1,8 +1,8 @@
|
|||
# Merge When Pipeline Succeeds
|
||||
|
||||
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
|
||||
builds pipeline succeeds. This way, you don't have to wait for the builds to
|
||||
more CI jobs running, you can set it to be merged automatically when the
|
||||
jobs pipeline succeeds. This way, you don't have to wait for the jobs to
|
||||
finish and remember to merge the request manually.
|
||||
|
||||
![Enable](img/merge_when_build_succeeds_enable.png)
|
||||
|
@ -19,10 +19,10 @@ after all.
|
|||
![Status](img/merge_when_build_succeeds_status.png)
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
new commits, the automatic merge is automatically canceled to allow the new
|
||||
changes to be reviewed.
|
||||
|
@ -30,7 +30,7 @@ changes to be reviewed.
|
|||
## Only allow merge requests to be merged if the pipeline succeeds
|
||||
|
||||
> **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.
|
||||
|
||||
|
@ -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)
|
||||
|
||||
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)
|
||||
|
|
|
@ -1,55 +1,55 @@
|
|||
# New CI build permissions model
|
||||
# New CI job permissions model
|
||||
|
||||
> 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
|
||||
[#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994).
|
||||
|
||||
---
|
||||
|
||||
Builds permissions should be tightly integrated with the permissions of a user
|
||||
who is triggering a build.
|
||||
Jobs permissions should be tightly integrated with the permissions of a user
|
||||
who is triggering a job.
|
||||
|
||||
The reasons to do it like that are:
|
||||
|
||||
- We already have a permissions system in place: group and project membership
|
||||
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).
|
||||
- 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
|
||||
allowing only specific users to access runners or use secure variables and
|
||||
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.
|
||||
- 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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
would have access too. **The permission is granted only for time that build is
|
||||
running. The access is revoked after the build is finished.**
|
||||
would have access too. **The permission is granted only for time that job is
|
||||
running. The access is revoked after the job is finished.**
|
||||
|
||||
## 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
|
||||
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
|
||||
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
|
||||
rules out accessing all internal projects by default,
|
||||
|
||||
|
@ -57,46 +57,46 @@ This allows us to make the CI and permission system more trustworthy.
|
|||
Let's consider the following scenario:
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
## 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
|
||||
build.
|
||||
job.
|
||||
|
||||
We try to make sure that this token doesn't leak by:
|
||||
|
||||
1. Securing all API endpoints to not expose the build token.
|
||||
1. Masking the build token from build logs.
|
||||
1. Allowing to use the build token **only** when build is running.
|
||||
1. Securing all API endpoints to not expose the job token.
|
||||
1. Masking the job token from job logs.
|
||||
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
|
||||
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:
|
||||
|
||||
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
|
||||
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.
|
||||
They continue to use the old authentication mechanism where the CI build
|
||||
[job triggers][triggers] do not support the new permission model.
|
||||
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
|
||||
the upcoming releases.
|
||||
|
||||
## 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.
|
||||
|
||||
The project's Runner's token was a token that you could find under the
|
||||
|
@ -105,7 +105,7 @@ project.
|
|||
It could be used for registering new specific Runners assigned to the project
|
||||
and to checkout project sources.
|
||||
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:
|
|||
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:
|
||||
|
||||
```
|
||||
|
@ -125,7 +125,7 @@ docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com
|
|||
Using single token had multiple security implications:
|
||||
|
||||
- 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.
|
||||
- The token would allow to access only the project's sources, forbidding from
|
||||
accessing any other projects.
|
||||
|
@ -133,12 +133,12 @@ Using single token had multiple security implications:
|
|||
for registering specific runners and for accessing a project's container
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
1. Access a project's [Git submodules][gitsub]
|
||||
|
@ -151,9 +151,9 @@ the container registry.
|
|||
|
||||
### 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
|
||||
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.
|
||||
|
||||
In short here's what you need to do should you encounter any issues.
|
||||
|
@ -175,7 +175,7 @@ As a user:
|
|||
|
||||
- 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
|
||||
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
|
||||
|
||||
|
@ -199,9 +199,9 @@ Container Registries for private projects.
|
|||
to pass a personal access token instead of your password in order to login to
|
||||
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
|
||||
project for which the build is triggered.
|
||||
project for which the job is triggered.
|
||||
|
||||
This is how an example usage can look like:
|
||||
|
||||
|
@ -213,7 +213,7 @@ test:
|
|||
- 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
|
||||
[ext]: ../permissions.md#external-users
|
||||
[gitsub]: ../../ci/git_submodules.md
|
||||
|
|
|
@ -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
|
||||
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:**
|
||||
> Before reading this section, make sure you familiarize yourself with GitLab CI
|
||||
|
@ -127,7 +127,7 @@ pages:
|
|||
```
|
||||
|
||||
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.
|
||||
|
||||
The `public/` directory should contain all the static content of your website.
|
||||
|
@ -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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
@ -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?
|
||||
|
||||
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?
|
||||
|
||||
|
|
After Width: | Height: | Size: 3.7 KiB |
After Width: | Height: | Size: 5.4 KiB |
After Width: | Height: | Size: 15 KiB |
After Width: | Height: | Size: 16 KiB |
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 10 KiB |
Before Width: | Height: | Size: 2.5 KiB After Width: | Height: | Size: 2.5 KiB |
Before Width: | Height: | Size: 6.2 KiB After Width: | Height: | Size: 6.2 KiB |
|
@ -0,0 +1,118 @@
|
|||
# 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)
|
||||
|
|
@ -35,7 +35,7 @@ if the job surpasses the threshold, it is marked as failed.
|
|||
## Test coverage parsing
|
||||
|
||||
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.
|
||||
|
||||
![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
|
|||
can use http://rubular.com to test your regex.
|
||||
|
||||
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)
|
||||
|
||||
|
@ -62,9 +62,9 @@ pipelines** checkbox and save the changes.
|
|||
|
||||
## 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
|
||||
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
|
||||
your badges, as well as ways to embed the badge image in your HTML or Markdown
|
||||
|
@ -72,9 +72,9 @@ pages.
|
|||
|
||||
![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
|
||||
- success
|
||||
|
@ -82,7 +82,7 @@ Depending on the status of your build, a badge can have the following values:
|
|||
- skipped
|
||||
- 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
|
||||
|
@ -91,7 +91,7 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg
|
|||
### Test coverage report badge
|
||||
|
||||
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.
|
||||
|
||||
The test coverage badge can be accessed using following link:
|
||||
|
|
|
@ -14,7 +14,7 @@ do.
|
|||
|:---------------------------|:-------------|
|
||||
| `/close` | Close 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 |
|
||||
| `/assign @username` | Assign |
|
||||
| `/unassign` | Remove assignee |
|
||||
|
|
|
@ -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>f</kbd> | Go to files |
|
||||
| <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>g</kbd> | Go to graphs |
|
||||
| <kbd>g</kbd> + <kbd>i</kbd> | Go to issues |
|
||||
|
|
|
@ -27,8 +27,8 @@ A Todo appears in your Todos dashboard when:
|
|||
- an issue or merge request is assigned to you,
|
||||
- you are `@mentioned` in an issue or merge request, be it the description of
|
||||
the issue/merge request or in a comment,
|
||||
- build in the CI pipeline running for your merge request failed, but this
|
||||
build is not allowed to fail.
|
||||
- a job in the CI pipeline running for your merge request failed, but this
|
||||
job is not allowed to fail.
|
||||
|
||||
>**Note:** Commenting on a commit will _not_ trigger a Todo.
|
||||
|
||||
|
|