diff options
Diffstat (limited to 'doc/ci')
| -rw-r--r-- | doc/ci/caching/index.md | 69 | ||||
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 41 | ||||
| -rw-r--r-- | doc/ci/docker/using_docker_images.md | 71 | ||||
| -rw-r--r-- | doc/ci/environments.md | 53 | ||||
| -rw-r--r-- | doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md | 4 | ||||
| -rw-r--r-- | doc/ci/git_submodules.md | 19 | ||||
| -rw-r--r-- | doc/ci/interactive_web_terminal/index.md | 6 | ||||
| -rw-r--r-- | doc/ci/pipelines.md | 47 | ||||
| -rw-r--r-- | doc/ci/review_apps/index.md | 9 | ||||
| -rw-r--r-- | doc/ci/runners/README.md | 5 | ||||
| -rw-r--r-- | doc/ci/ssh_keys/README.md | 4 | ||||
| -rw-r--r-- | doc/ci/triggers/README.md | 29 | ||||
| -rw-r--r-- | doc/ci/variables/README.md | 16 | ||||
| -rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 27 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 97 |
15 files changed, 259 insertions, 238 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 01e95b54fc4..b41101695f6 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -24,14 +24,14 @@ Don't mix the caching with passing artifacts between stages. Caching is not designed to pass artifacts between stages. Cache is for runtime dependencies needed to compile the project: -- `cache` - **Use for temporary storage for project dependencies.** Not useful +- `cache`: **Use for temporary storage for project dependencies.** Not useful for keeping intermediate build results, like `jar` or `apk` files. Cache was designed to be used to speed up invocations of subsequent runs of a given job, by keeping things like dependencies (e.g., npm packages, Go vendor packages, etc.) so they don't have to be re-fetched from the public internet. While the cache can be abused to pass intermediate build results between stages, there may be cases where artifacts are a better fit. -- `artifacts` - **Use for stage results that will be passed between stages.** +- `artifacts`: **Use for stage results that will be passed between stages.** Artifacts were designed to upload some compiled/generated bits of the build, and they can be fetched by any number of concurrent Runners. They are guaranteed to be available and are there to pass data between jobs. They are @@ -57,19 +57,20 @@ control exactly where artifacts are passed around. In summary: -- Caches are disabled if not defined globally or per job (using `cache:`) -- Caches are available for all jobs in your `.gitlab-ci.yml` if enabled globally +- Caches are disabled if not defined globally or per job (using `cache:`). +- Caches are available for all jobs in your `.gitlab-ci.yml` if enabled globally. - Caches can be used by subsequent pipelines of that very same job (a script in a stage) in which the cache was created (if not defined globally). - Caches are stored where the Runner is installed **and** uploaded to S3 if - [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) -- Caches defined per job are only used either a) for the next pipeline of that job, - or b) if that same cache is also defined in a subsequent job of the same pipeline -- Artifacts are disabled if not defined per job (using `artifacts:`) -- Artifacts can only be enabled per job, not globally + [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). +- Caches defined per job are only used, either: + - For the next pipeline of that job. + - If that same cache is also defined in a subsequent job of the same pipeline. +- Artifacts are disabled if not defined per job (using `artifacts:`). +- Artifacts can only be enabled per job, not globally. - Artifacts are created during a pipeline and can be used by the subsequent - jobs of that currently active pipeline -- Artifacts are always uploaded to GitLab (known as coordinator) + jobs of that currently active pipeline. +- Artifacts are always uploaded to GitLab (known as coordinator). - Artifacts can have an expiration value for controlling disk usage (30 days by default). ## Good caching practices @@ -97,13 +98,13 @@ or pipelines in a guaranteed manner. From the perspective of the Runner, in order for cache to work effectively, one of the following must be true: -- Use a single Runner for all your jobs -- Use multiple Runners (in autoscale mode or not) that use +- Use a single Runner for all your jobs. +- Use multiple Runners (in autoscale mode or not) that use. [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching), - where the cache is stored in S3 buckets (like shared Runners on GitLab.com) + where the cache is stored in S3 buckets (like shared Runners on GitLab.com). - Use multiple Runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) - where the cache will be stored + where the cache will be stored. TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) @@ -367,19 +368,19 @@ job B: Here's what happens behind the scenes: -1. Pipeline starts -1. `job A` runs -1. `before_script` is executed -1. `script` is executed -1. `after_script` is executed +1. Pipeline starts. +1. `job A` runs. +1. `before_script` is executed. +1. `script` is executed. +1. `after_script` is executed. 1. `cache` runs and the `vendor/` directory is zipped into `cache.zip`. This file is then saved in the directory based on the [Runner's setting](#where-the-caches-are-stored) and the `cache: key`. -1. `job B` runs -1. The cache is extracted (if found) -1. `before_script` is executed -1. `script` is executed -1. Pipeline finishes +1. `job B` runs. +1. The cache is extracted (if found). +1. `before_script` is executed. +1. `script` is executed. +1. Pipeline finishes. By using a single Runner on a single machine, you'll not have the issue where `job B` might execute on a Runner different from `job A`, thus guaranteeing the @@ -451,13 +452,13 @@ job B: - vendor/ ``` -1. `job A` runs -1. `public/` is cached as cache.zip -1. `job B` runs -1. The previous cache, if any, is unzipped -1. `vendor/` is cached as cache.zip and overwrites the previous one +1. `job A` runs. +1. `public/` is cached as cache.zip. +1. `job B` runs. +1. The previous cache, if any, is unzipped. +1. `vendor/` is cached as cache.zip and overwrites the previous one. 1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective + and thus will be ineffective. To fix that, use different `keys` for each job. @@ -514,12 +515,12 @@ next run of the pipeline, the cache will be stored in a different location. If you want to avoid editing `.gitlab-ci.yml`, you can easily clear the cache via GitLab's UI: -1. Navigate to your project's **CI/CD > Pipelines** page -1. Click on the **Clear Runner caches** button to clean up the cache +1. Navigate to your project's **CI/CD > Pipelines** page. +1. Click on the **Clear Runner caches** button to clean up the cache.  -1. On the next push, your CI/CD job will use a new cache +1. On the next push, your CI/CD job will use a new cache. Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 63338ff632c..aa997d15b64 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -151,16 +151,16 @@ In order to do that, follow the steps: DOCKER_DRIVER: overlay2 services: - - docker:dind + - docker:dind before_script: - - docker info + - docker info build: stage: build script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests ``` Docker-in-Docker works well, and is the recommended configuration, but it is @@ -246,13 +246,13 @@ In order to do that, follow the steps: image: docker:stable before_script: - - docker info + - docker info build: stage: build script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests ``` While the above method avoids using Docker in privileged mode, you should be @@ -381,17 +381,18 @@ environment = ["DOCKER_DRIVER=overlay2"] If you're running multiple Runners you will have to modify all configuration files. > **Notes:** -- More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). -- For more information about using OverlayFS with Docker, you can read - [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). +> +> - More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). +> - For more information about using OverlayFS with Docker, you can read +> [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry > **Notes:** -- This feature requires GitLab 8.8 and GitLab Runner 1.2. -- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. +> - This feature requires GitLab 8.8 and GitLab Runner 1.2. +> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, @@ -402,7 +403,7 @@ could look like: build: image: docker:stable services: - - docker:dind + - docker:dind variables: DOCKER_HOST: tcp://docker:2375 DOCKER_DRIVER: overlay2 @@ -455,13 +456,13 @@ an application-specific deploy script: ```yaml image: docker:stable services: -- docker:dind + - docker:dind stages: -- build -- test -- release -- deploy + - build + - test + - release + - deploy variables: DOCKER_HOST: tcp://docker:2375 diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 71f1d69cdf4..9abedcc6acb 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -452,13 +452,14 @@ that runner. ## Define an image from a private Container Registry > **Notes:** -- This feature requires GitLab Runner **1.8** or higher -- For GitLab Runner versions **>= 0.6, <1.8** there was a partial - support for using private registries, which required manual configuration - of credentials on runner's host. We recommend to upgrade your Runner to - at least version **1.8** if you want to use private registries. -- If the repository is private you need to authenticate your GitLab Runner in the - registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. +> +> - This feature requires GitLab Runner **1.8** or higher +> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial +> support for using private registries, which required manual configuration +> of credentials on runner's host. We recommend to upgrade your Runner to +> at least version **1.8** if you want to use private registries. +> - If the repository is private you need to authenticate your GitLab Runner in the +> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. As an example, let's assume that you want to use the `registry.example.com/private/image:latest` image which is private and requires you to login into a private container registry. @@ -475,57 +476,57 @@ To configure access for `registry.example.com`, follow these steps: 1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to accomplish this: - - **First way -** Do a `docker login` on your local machine: + - **First way -** Do a `docker login` on your local machine: - ```bash - docker login registry.example.com --username my_username --password my_password - ``` + ```bash + docker login registry.example.com --username my_username --password my_password + ``` - Then copy the content of `~/.docker/config.json`. - - **Second way -** In some setups, it's possible that Docker client will use + Then copy the content of `~/.docker/config.json`. + - **Second way -** In some setups, it's possible that Docker client will use the available system keystore to store the result of `docker login`. In that case, it's impossible to read `~/.docker/config.json`, so you will need to prepare the required base64-encoded version of `${username}:${password}` manually. Open a terminal and execute the following command: - ```bash - echo -n "my_username:my_password" | base64 + ```bash + echo -n "my_username:my_password" | base64 - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` 1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: - ```json - { - "auths": { - "registry.example.com": { - "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" - } - } - } - ``` + ```json + { + "auths": { + "registry.example.com": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } + } + ``` 1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG` value, do a `docker logout` on your computer if you don't need access to the registry from it: - ```bash - docker logout registry.example.com - ``` + ```bash + docker logout registry.example.com + ``` 1. You can now use any private image from `registry.example.com` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: - ```yaml - image: my.registry.tld:5000/namespace/image:tag - ``` + ```yaml + image: my.registry.tld:5000/namespace/image:tag + ``` - In the example above, GitLab Runner will look at `my.registry.tld:5000` for the - image `namespace/image:tag`. + In the example above, GitLab Runner will look at `my.registry.tld:5000` for the + image `namespace/image:tag`. You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 8ea2e0a81dc..f1e5b00e927 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that has an environment specified and succeeds, a deployment is recorded, remembering the Git SHA and environment name. ->**Note:** -Starting with GitLab 8.15, the environment name is exposed to the Runner in -two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is -the name given in `.gitlab-ci.yml` (with any variables expanded), while the -second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, -etc. - ->**Note:** -Starting with GitLab 9.3, the environment URL is exposed to the Runner via -`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if -the URL was not defined there, the external URL from the environment would be -used. +> **Note:** +> Starting with GitLab 8.15, the environment name is exposed to the Runner in +> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is +> the name given in `.gitlab-ci.yml` (with any variables expanded), while the +> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, +> etc. +> +> **Note:** +> Starting with GitLab 9.3, the environment URL is exposed to the Runner via +> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if +> the URL was not defined there, the external URL from the environment would be +> used. To sum up, with the above `.gitlab-ci.yml` we have achieved that: @@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see: - A button that re-deploys the latest deployment, meaning it runs the job defined by the environment name for that specific commit ->**Notes:** -- While you can create environments manually in the web interface, we recommend - that you define your environments in `.gitlab-ci.yml` first. They will - be automatically created for you after the first deploy. -- The environments page can only be viewed by Reporters and above. For more - information on the permissions, see the [permissions documentation][permissions]. -- Only deploys that happen after your `.gitlab-ci.yml` is properly configured - will show up in the "Environment" and "Last deployment" lists. +> **Notes:** +> +> - While you can create environments manually in the web interface, we recommend +> that you define your environments in `.gitlab-ci.yml` first. They will +> be automatically created for you after the first deploy. +> - The environments page can only be viewed by Reporters and above. For more +> information on the permissions, see the [permissions documentation][permissions]. +> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured +> will show up in the "Environment" and "Last deployment" lists. The information shown in the Environments page is limited to the latest deployments, but as you may have guessed an environment can have multiple @@ -563,13 +564,13 @@ exist, you should see something like: ## Monitoring environments ->**Notes:** +> **Notes:** > -- For the monitoring dashboard to appear, you need to: - - Have enabled the [Prometheus integration][prom] - - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) -- With GitLab 9.2, all deployments to an environment are shown directly on the - monitoring dashboard +> - For the monitoring dashboard to appear, you need to: +> - Have enabled the [Prometheus integration][prom] +> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +> - With GitLab 9.2, all deployments to an environment are shown directly on the +> monitoring dashboard If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index a2de0408797..b2c73caae2e 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -85,7 +85,7 @@ When asked, answer `Y` to fetch and install dependencies. If everything went fine, you'll get an output like this: - + Now, our project is located inside the directory with the same name we pass to `mix` command, for example, `~/GitLab/hello_gitlab_ci`. @@ -145,7 +145,7 @@ Now, we have our app running locally. We can preview it directly on our browser. not work, open [`127.0.0.1:4000`](http://127.0.0.1:4000) instead and later, configure your OS to point `localhost` to `127.0.0.1`. - + Great, now we have a local Phoenix Server running our app. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 286f3dee665..37078230b34 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,15 +1,16 @@ # Using Git submodules with GitLab CI > **Notes:** -- 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 job - can access. More information about how this system works can be found in the - [Jobs permissions model](../user/permissions.md#job-permissions). -- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. +> +> - 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 job +> can access. More information about how this system works can be found in the +> [Jobs permissions model](../user/permissions.md#job-permissions). +> - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. ## Configuring the `.gitmodules` file diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 507aceb27fa..8ce4fe55cec 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,10 +1,6 @@ # Getting started with interactive web terminals -> Introduced in GitLab 11.3. - -CAUTION: **Warning:** -Interactive web terminals are in beta, so they might not work properly and -lack features. For more information [follow issue #25990](https://gitlab.com/gitlab-org/gitlab-ce/issues/25990). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for running one-of commands for their CI pipeline. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 4e964af97f5..ea47d676edb 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -9,7 +9,7 @@ you may need to enable pipeline triggering in your project's ## Pipelines -A pipeline is a group of [jobs][] that get executed in [stages][](batches). +A pipeline is a group of [jobs] that get executed in [stages]. 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 jobs fails, the next stage is not (usually) @@ -29,17 +29,17 @@ There are three types of pipelines that often use the single shorthand of "pipel  -1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml` -2. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production -3. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus. +1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`. +1. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production. +1. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus. ## Development workflows Pipelines accommodate several development workflows: -1. **Branch Flow** (e.g. different branch for dev, qa, staging, production) -2. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases) -3. **Fork-based Flow** (e.g. merge requests come from forks) +1. **Branch Flow** (e.g. different branch for dev, qa, staging, production). +1. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases). +1. **Fork-based Flow** (e.g. merge requests come from forks). Example continuous delivery flow: @@ -57,6 +57,16 @@ Pipelines are defined in `.gitlab-ci.yml` by specifying [jobs] that run in See the reference [documentation for jobs](yaml/README.md#jobs). +## Manually executing pipelines + +Pipelines can be manually executed, with predefined or manually-specified [variables](variables/README.md). + +To execute a pipeline manually: + +1. Navigate to your project's **CI/CD > Pipelines**. +1. Click on the **Run Pipeline** button. +1. Select the branch to run the pipeline for and enter any environment variables required for the pipeline run. + ## Seeing pipeline status You can find the current and historical pipeline runs under your project's @@ -112,9 +122,9 @@ Then, there is the pipeline mini graph which takes less space and can give you a quick glance if all jobs pass or something failed. The pipeline mini graph can be found when you visit: -- the pipelines index page -- a single commit page -- a merge request page +- The pipelines index page. +- A single commit page. +- A merge request page. That way, you can see all related jobs for a single commit and the net result of each stage of your pipeline. This allows you to quickly see what failed and @@ -142,9 +152,9 @@ jobs. Click to expand them. The basic requirements is that there are two numbers separated with one of the following (you can even use them interchangeably): -- a space -- a slash (`/`) -- a colon (`:`) +- A space (` `) +- A slash (`/`) +- A colon (`:`) >**Note:** More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`. @@ -252,11 +262,12 @@ A strict security model is enforced when pipelines are executed on The following actions are allowed on protected branches only if the user is [allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings) on that specific branch: -- run **manual pipelines** (using Web UI or Pipelines API) -- run **scheduled pipelines** -- run pipelines using **triggers** -- trigger **manual actions** on existing pipelines -- **retry/cancel** existing jobs (using Web UI or Pipelines API) + +- Run **manual pipelines** (using [Web UI](#manually-executing-pipelines) or Pipelines API). +- Run **scheduled pipelines**. +- Run pipelines using **triggers**. +- Trigger **manual actions** on existing pipelines. +- **Retry/cancel** existing jobs (using Web UI or Pipelines API). **Variables** marked as **protected** are accessible only to jobs that run on protected branches, avoiding untrusted users to get unintended access to diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 28c484ddbe6..1b17f6ac5ea 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,10 +1,9 @@ # Getting started with Review Apps -> -- [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab - 8.13 and 8.14. -- Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by - [Fourchette]. +> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab +> 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by +> [Fourchette]. The basis of Review Apps is the [dynamic environments] which allow you to create a new environment (dynamically) for each one of your branches. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8f1ff190804..7859d2ec631 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -144,9 +144,8 @@ An admin can enable/disable a specific Runner for projects: ## Protected Runners -> -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) -in GitLab 10.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) +> in GitLab 10.0. You can protect Runners from revealing sensitive information. Whenever a Runner is protected, the Runner picks only jobs created on diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 4cb05509e7b..0c3b0bf6990 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -46,7 +46,7 @@ to access it. This is where an SSH key pair comes in handy. 1. You will first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will\ + **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. 1. Create a new [variable](../variables/README.md#variables). @@ -175,7 +175,7 @@ Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) above, here's what more you need to add: - ```yaml +```yaml before_script: ## ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index c213b096a14..cf92d90ba30 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,9 +1,10 @@ # Triggering pipelines through the API > **Notes**: -- [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). +> +> - [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 pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -49,11 +50,12 @@ The action is irreversible. ## Triggering a pipeline > **Notes**: -- Valid refs are only the branches and tags. If you pass a commit SHA as a ref, - it will not trigger a job. -- If your project is public, passing the token in plain text is probably not the - wisest idea, so you might want to use a - [variable](../variables/README.md#variables) for that purpose. +> +> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref, +> it will not trigger a job. +> - If your project is public, passing the token in plain text is probably not the +> wisest idea, so you might want to use a +> [variable](../variables/README.md#variables) for that purpose. To trigger a job you need to send a `POST` request to GitLab's API endpoint: @@ -122,11 +124,12 @@ Now, whenever a new tag is pushed on project A, the job will run and the ## Triggering a pipeline from a webhook > **Notes**: -- Introduced in GitLab 8.14. -- `ref` should be passed as part of the URL in order to take precedence over - `ref` from the webhook body that designates the branch ref that fired the - trigger in the source repository. -- `ref` should be URL-encoded if it contains slashes. +> +> - Introduced in GitLab 8.14. +> - `ref` should be passed as part of the URL in order to take precedence over +> `ref` from the webhook body that designates the branch ref that fired the +> trigger in the source repository. +> - `ref` should be URL-encoded if it contains slashes. To trigger a job from a webhook of another project you need to add the following webhook URL for Push and Tag events (change the project ID, ref and token): diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 115e6e390c9..f11949da64e 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -34,7 +34,7 @@ Some of the predefined environment variables are available only if a minimum version of [GitLab Runner][runner] is used. Consult the table below to find the version of Runner required. ->**Note:** +NOTE: **Note:** Starting with GitLab 9.0, we have deprecated some variables. Read the [9.0 Renaming](#9-0-renaming) section to find out their replacements. **You are strongly advised to use the new variables as we will remove the old ones in @@ -109,7 +109,7 @@ To follow conventions of naming across GitLab, and to further move away from the `build` term and toward `job` CI variables have been renamed for the 9.0 release. ->**Note:** +NOTE: **Note:** Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are strongly advised to use the new variables as we will remove the old ones in future GitLab releases.** @@ -131,7 +131,7 @@ future GitLab releases.** ## `.gitlab-ci.yml` defined variables ->**Note:** +NOTE **Note:** This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher. GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the @@ -215,9 +215,15 @@ Protected variables can be added by going to your project's Once you set them, they will be available for all subsequent pipelines. +### Manually-specified variables + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8. + +Variables can be specified for a single pipeline run when a [manual pipeline](../pipelines.md#manually-executing-pipelines) is created. + ## Deployment variables ->**Note:** +NOTE: **Note:** This feature requires GitLab CI 8.15 or higher. [Project services](../../user/project/integrations/project_services.md) that are @@ -567,4 +573,4 @@ Below you can find supported syntax reference: [builds-policies]: ../yaml/README.md#only-and-except-complex [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token [registry]: ../../user/project/container_registry.md -[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
\ No newline at end of file +[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b2b4a26bdda..b0d2ea6484d 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -8,10 +8,10 @@ This document describes where and how the different types of variables can be us ## Variables usage -There are basically two places where you can use any defined variables: +There are two places defined variables can be used. On the: -1. On GitLab's side there's `.gitlab-ci.yml` -1. On the Runner's side there's `config.toml` +1. GitLab side, in `.gitlab-ci.yml`. +1. The runner side, in `config.toml`. ### `.gitlab-ci.yml` file @@ -56,8 +56,8 @@ since the expansion is done in GitLab before any Runner will get the job. ### GitLab Runner internal variable expansion mechanism - **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and - variables from triggers and pipeline schedules -- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`) + variables from triggers, pipeline schedules, and manual pipelines. +- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle only variables defined as `$variable` and `${variable}`. What's also important, is that @@ -80,11 +80,10 @@ are using a different variables syntax. `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules). - The `script` may also use all variables defined in the lines before. So, for example, if you define a variable `export MY_VARIABLE="test"`: - - - in `before_script`, it will work in the following lines of `before_script` and - all lines of the related `script` - - in `script`, it will work in the following lines of `script` - - in `after_script`, it will work in following lines of `after_script` + - In `before_script`, it will work in the following lines of `before_script` and + all lines of the related `script`. + - In `script`, it will work in the following lines of `script`. + - In `after_script`, it will work in following lines of `after_script`. ## Persisted variables @@ -107,7 +106,7 @@ The following variables are known as "persisted": They are: -- **supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner" -- **not supported:** - - by the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab" - - in the `only` and `except` [variables expressions](README.md#variables-expressions) +- **Supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner". +- **Not supported:** + - By the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab". + - In the `only` and `except` [variables expressions](README.md#variables-expressions). diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index c1ebe39e076..72b90ac6334 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -383,7 +383,7 @@ except master. ## `only` and `except` (complex) > `refs` and `kubernetes` policies introduced in GitLab 10.0 - +> > `variables` policy introduced in 10.7 CAUTION: **Warning:** @@ -583,9 +583,10 @@ The above script will: ### `when:manual` > **Notes:** -- Introduced in GitLab 8.10. -- Blocking manual actions were introduced in GitLab 9.0. -- Protected actions were introduced in GitLab 9.2. +> +> - Introduced in GitLab 8.10. +> - Blocking manual actions were introduced in GitLab 9.0. +> - Protected actions were introduced in GitLab 9.2. Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions @@ -616,11 +617,11 @@ have ability to merge to this branch. ## `environment` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.9. -- You can read more about environments and find more examples in the - [documentation about environments][environment]. +> - 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 @@ -641,15 +642,15 @@ deployment to the `production` environment. ### `environment:name` +> **Notes:** > -**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 `name` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - 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 `name` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. The `environment` name can contain: @@ -680,14 +681,14 @@ deploy to production: ### `environment:url` +> **Notes:** > -**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`. -- The `url` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - 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`. +> - The `url` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. 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. @@ -707,12 +708,12 @@ deploy to production: ### `environment:on_stop` +> **Notes:** > -**Notes:** -- [Introduced][ce-6669] in GitLab 8.13. -- Starting with GitLab 8.14, when you have an environment that has a stop action - defined, GitLab will automatically trigger a stop action when the associated - branch is deleted. +> - [Introduced][ce-6669] in GitLab 8.13. +> - Starting with GitLab 8.14, when you have an environment that has a stop action +> defined, GitLab will automatically trigger a stop action when the associated +> branch is deleted. Closing (stoping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close @@ -763,13 +764,13 @@ The `stop_review_app` job is **required** to have the following keywords defined ### Dynamic environments +> **Notes:** > -**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. -- The `name` and `url` parameters can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. +> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. +> - The `name` and `url` parameters can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. For example: @@ -799,13 +800,13 @@ as Review Apps. You can see a simple example using Review Apps at ## `cache` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0. -- `cache` can be set globally and per-job. -- From GitLab 9.0, caching is enabled and shared between pipelines and jobs - by default. -- From GitLab 9.2, caches are restored before [artifacts](#artifacts). +> - Introduced in GitLab Runner v0.7.0. +> - `cache` can be set globally and per-job. +> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs +> by default. +> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). TIP: **Learn more:** Read how caching works and find out some good practices in the @@ -967,13 +968,13 @@ skip the download step. ## `artifacts` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -- Windows support was added in GitLab Runner v.1.0.0. -- From GitLab 9.2, caches are restored before artifacts. -- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -- Job artifacts are only collected for successful jobs by default. +> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. +> - Windows support was added in GitLab Runner v.1.0.0. +> - From GitLab 9.2, caches are restored before artifacts. +> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). +> - 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 job after success. @@ -1455,7 +1456,9 @@ There are three possible values: `none`, `normal`, and `recursive`: ``` - `recursive` means that all submodules (including submodules of submodules) - will be included. It is equivalent to: + will be included. This feature needs Git v1.8.1 and later. When using a + GitLab Runner with an executor not based on Docker, make sure the Git version + meets that requirement. It is equivalent to: ``` git submodule sync --recursive |