diff options
Diffstat (limited to 'doc/ci/yaml/README.md')
| -rw-r--r-- | doc/ci/yaml/README.md | 149 |
1 files changed, 78 insertions, 71 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index accf6340398..be114e7008e 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -10,6 +10,11 @@ of your repository and contains definitions of how your project should be built. If you want a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md). +NOTE: **Note:** +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +you may need to enable pipeline triggering in your project's +**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. + ## Jobs The YAML file defines a set of jobs with constraints stating when they should @@ -315,9 +320,14 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Two keys are now available: `refs` and `kubernetes`. Refs strategy equals to -simplified only/except configuration, whereas kubernetes strategy accepts only -`active` keyword. +Three keys are now available: `refs`, `kubernetes` and `variables`. +Refs strategy equals to simplified only/except configuration, whereas +kubernetes strategy accepts only `active` keyword. + +`variables` keyword is used to define variables expressions. In other words +you can use predefined variables / secret variables / project / group or +environment-scoped variables to define an expression GitLab is going to +evaluate in order to decide whether a job should be created or not. See the example below. Job is going to be created only when pipeline has been scheduled or runs for a `master` branch, and only if kubernetes service is @@ -332,6 +342,20 @@ job: kubernetes: active ``` +Example of using variables expressions: + +```yaml +deploy: + only: + refs: + - branches + variables: + - $RELEASE == "staging" + - $STAGING +``` + +Learn more about variables expressions on a separate page. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -674,6 +698,10 @@ as Review Apps. You can see a simple example using Review Apps at 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 +[caching dependencies documentation](../caching/index.md). + `cache` is used to specify a list of files and directories which should be cached between jobs. You can only use paths that are within the project workspace. @@ -681,35 +709,20 @@ workspace. If `cache` is defined outside the scope of jobs, it means it is set globally and all jobs will use that definition. -Cache all files in `binaries` and `.config`: +### `cache:paths` -```yaml -rspec: - script: test - cache: - paths: - - binaries/ - - .config -``` +Use the `paths` directive to choose which files or directories will be cached. +Wildcards can be used as well. -Cache all Git untracked files: +Cache all files in `binaries` that end in `.apk` and the `.config` file: ```yaml rspec: script: test cache: - untracked: true -``` - -Cache all Git untracked files and files in `binaries`: - -```yaml -rspec: - script: test - cache: - untracked: true paths: - - binaries/ + - binaries/*.apk + - .config ``` Locally defined cache overrides globally defined options. The following `rspec` @@ -723,33 +736,26 @@ cache: rspec: script: test cache: - key: rspec paths: - binaries/ ``` -Note that since cache is shared between jobs, if you're using different -paths for different jobs, you should also set a different **cache:key** -otherwise cache content can be overwritten. - -NOTE: **Note:** -The cache is provided on a best-effort basis, so don't expect that the cache -will be always present. - ### `cache:key` > Introduced in GitLab Runner v1.0.0. -The `key` directive allows you to define the affinity of caching -between jobs, allowing to have a single cache for all jobs, -cache per-job, cache per-branch or any other way that fits your needs. +Since the cache is shared between jobs, if you're using different +paths for different jobs, you should also set a different `cache:key` +otherwise cache content can be overwritten. -This way, you can fine tune caching, allowing you to cache data between -different jobs or even different branches. +The `key` directive allows you to define the affinity of caching between jobs, +allowing to have a single cache for all jobs, cache per-job, cache per-branch +or any other way that fits your workflow. This way, you can fine tune caching, +allowing you to cache data between different jobs or even different branches. The `cache:key` variable can use any of the [predefined variables](../variables/README.md), and the default key, if not set, -is set as `$CI_JOB_NAME-$CI_COMMIT_REF_NAME` which translates as "per-job and +is `$CI_JOB_NAME-$CI_COMMIT_REF_NAME` which translates as "per-job and per-branch". It is the default across the project, therefore everything is shared between pipelines and jobs running on the same branch by default. @@ -757,56 +763,56 @@ NOTE: **Note:** The `cache:key` variable cannot contain the `/` character, or the equivalent URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden. -**Example configurations** - -To enable per-job caching: - -```yaml -cache: - key: "$CI_JOB_NAME" - untracked: true -``` - -To enable per-branch caching: +For example, to enable per-branch caching: ```yaml cache: key: "$CI_COMMIT_REF_SLUG" - untracked: true + paths: + - binaries/ ``` -To enable per-job and per-branch caching: +If you use **Windows Batch** to run your shell scripts you need to replace +`$` with `%`: ```yaml cache: - key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG" - untracked: true + key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%" + paths: + - binaries/ ``` -To enable per-branch and per-stage caching: +If you use **Windows PowerShell** to run your shell scripts you need to replace +`$` with `$env:`: ```yaml cache: - key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG" - untracked: true + key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG" + paths: + - binaries/ ``` -If you use **Windows Batch** to run your shell scripts you need to replace -`$` with `%`: +### `cache:untracked` + +Set `untracked: true` to cache all files that are untracked in your Git +repository: ```yaml -cache: - key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%" - untracked: true +rspec: + script: test + cache: + untracked: true ``` -If you use **Windows PowerShell** to run your shell scripts you need to replace -`$` with `$env:`: +Cache all Git untracked files and files in `binaries`: ```yaml -cache: - key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG" - untracked: true +rspec: + script: test + cache: + untracked: true + paths: + - binaries/ ``` ### `cache:policy` @@ -1150,7 +1156,7 @@ job1: ## `retry` -> [Introduced][ce-3442] in GitLab 9.5. +> [Introduced][ce-12909] in GitLab 9.5. `retry` allows you to configure how many times a job is going to be retried in case of a failure. @@ -1544,8 +1550,9 @@ capitalization, the commit will be created but the pipeline will be skipped. ## 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. +Each instance of GitLab CI has an embedded debug tool called Lint, which validates the +content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your +project namespace (e.g, `http://gitlab-example.com/gitlab-org/project-123/ci/lint`) ## Using reserved keywords @@ -1565,5 +1572,5 @@ CI with various languages. [variables]: ../variables/README.md [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983 [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447 -[ce-3442]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3442 +[ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md |