diff options
Diffstat (limited to 'doc/ci')
33 files changed, 433 insertions, 419 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index dd14698e9cd..cbab7c9f18d 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -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. diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md index 05605f10fb4..e7692b8b9a2 100644 --- a/doc/ci/build_artifacts/README.md +++ b/doc/ci/build_artifacts/README.md @@ -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). diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index 84eaf29efd1..99669a9272a 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -1,4 +1,4 @@ # Docker integration -+ [Using Docker Images](using_docker_images.md) -+ [Using Docker Build](using_docker_build.md)
\ No newline at end of file +- [Using Docker Images](using_docker_images.md) +- [Using Docker Build](using_docker_build.md) diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 28141cced3b..2b3082acd5d 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/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/ diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index aba77490915..9dee61bfa1f 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -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.* diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 7971daf2637..796a025b951 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -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. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index cb62ed723f0..3bba94f8b83 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -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 | | --------- | ----------------| ------------ | ----------- | -------| |  |  |  |  |  | @@ -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 diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 7d91ce6710f..d28aa282825 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -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 diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 5334a73e1f5..8b0d8a003fd 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -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. @@ -153,4 +153,4 @@ stage_deploy: - scp -P22 -r build/* server_user@server_host:htdocs/wp-content/themes/_tmp - ssh -p22 server_user@server_host "mv htdocs/wp-content/themes/live htdocs/wp-content/themes/_old && mv htdocs/wp-content/themes/_tmp htdocs/wp-content/themes/live" - ssh -p22 server_user@server_host "rm -rf htdocs/wp-content/themes/_old" -```
\ No newline at end of file +``` diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 5eeec92d976..f2dd12b67d3 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -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 diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 85f8849fa99..01c13941c21 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -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 diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 869743ce80a..36c6e153d95 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -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 diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index ab289876252..3134405e10b 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -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.  @@ -35,10 +35,10 @@ Example continuous delivery flow:  -## 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 diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 1104edaabe9..2a5401ac13a 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.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.  -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. - + 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**.  ### 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.  -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.  -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.  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 diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png Binary files differindex 87643d62d58..3a7248ca772 100644 --- a/doc/ci/quick_start/img/build_log.png +++ b/doc/ci/quick_start/img/build_log.png diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png Binary files differindex d287ae3064f..f829240f3b3 100644 --- a/doc/ci/quick_start/img/builds_status.png +++ b/doc/ci/quick_start/img/builds_status.png diff --git a/doc/ci/quick_start/img/new_commit.png b/doc/ci/quick_start/img/new_commit.png Binary files differindex 29c2fea5d6d..b3dd848b294 100644 --- a/doc/ci/quick_start/img/new_commit.png +++ b/doc/ci/quick_start/img/new_commit.png diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png Binary files differindex 53ccc49bd66..06d1559f5d2 100644 --- a/doc/ci/quick_start/img/pipelines_status.png +++ b/doc/ci/quick_start/img/pipelines_status.png diff --git a/doc/ci/quick_start/img/runners_activated.png b/doc/ci/quick_start/img/runners_activated.png Binary files differindex 5ce6fe8e17c..cd83c1a7e4c 100644 --- a/doc/ci/quick_start/img/runners_activated.png +++ b/doc/ci/quick_start/img/runners_activated.png diff --git a/doc/ci/quick_start/img/single_commit_status_pending.png b/doc/ci/quick_start/img/single_commit_status_pending.png Binary files differindex 91fc9011847..ffc7054d3b0 100644 --- a/doc/ci/quick_start/img/single_commit_status_pending.png +++ b/doc/ci/quick_start/img/single_commit_status_pending.png diff --git a/doc/ci/quick_start/img/status_pending.png b/doc/ci/quick_start/img/status_pending.png Binary files differdeleted file mode 100644 index cbd44a189d3..00000000000 --- a/doc/ci/quick_start/img/status_pending.png +++ /dev/null diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index ddebd987650..e15b6891334 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -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. - + -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. - + -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. - + ## 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/). diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index aaf3aa77837..338368dbbc9 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -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 diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index f787cc0a124..3899b555f32 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -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 diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index 80705024d2f..554c321fd0c 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -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 diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index b858029d25e..49e7ac38b26 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -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 diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index efca05af7b8..740edba1f59 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -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'. - + --- -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. - + --- 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. - + --- @@ -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 diff --git a/doc/ci/triggers/img/builds_page.png b/doc/ci/triggers/img/builds_page.png Binary files differindex fded5839f76..c9cc8f308f4 100644 --- a/doc/ci/triggers/img/builds_page.png +++ b/doc/ci/triggers/img/builds_page.png diff --git a/doc/ci/triggers/img/trigger_single_build.png b/doc/ci/triggers/img/trigger_single_build.png Binary files differindex c4a5550d640..837bbeffe9f 100644 --- a/doc/ci/triggers/img/trigger_single_build.png +++ b/doc/ci/triggers/img/trigger_single_build.png diff --git a/doc/ci/triggers/img/trigger_variables.png b/doc/ci/triggers/img/trigger_variables.png Binary files differindex 65fe1ea9ab6..0c2a761cfa9 100644 --- a/doc/ci/triggers/img/trigger_variables.png +++ b/doc/ci/triggers/img/trigger_variables.png diff --git a/doc/ci/triggers/img/triggers_page.png b/doc/ci/triggers/img/triggers_page.png Binary files differindex 56d13905ce6..8ebf68d0384 100644 --- a/doc/ci/triggers/img/triggers_page.png +++ b/doc/ci/triggers/img/triggers_page.png diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 49fca884f35..8a638ed3df8 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -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 diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index cd492d16747..63be61d1bca 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -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: @@ -302,24 +302,24 @@ job_name: | Keyword | Required | Description | |---------------|----------|-------------| -| 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`) | -| 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 | -| 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 | -| 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 | -| coverage | no | Define code coverage settings for a given job | +| 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 job stage (default: `test`) | +| type | no | Alias for `stage` | +| 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 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 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 | +| Variable | Description | +|-------------------------------- |-------------| +| **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 |
