diff options
Diffstat (limited to 'doc/ci/yaml/README.md')
| -rw-r--r-- | doc/ci/yaml/README.md | 74 |
1 files changed, 53 insertions, 21 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index a73598df812..ad3ebd144df 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -70,7 +70,7 @@ There are a few reserved `keywords` that **cannot** be used as job names: | image | no | Use docker image, covered in [Use Docker](../docker/README.md) | | services | no | Use docker services, covered in [Use Docker](../docker/README.md) | | stages | no | Define build stages | -| types | no | Alias for `stages` | +| types | no | Alias for `stages` (deprecated) | | before_script | no | Define commands that run before each job's script | | after_script | no | Define commands that run after each job's script | | variables | no | Define build variables | @@ -130,6 +130,8 @@ There are also two edge cases worth mentioning: ### types +> Deprecated, and will be removed in 10.0. Use [stages](#stages) instead. + Alias for [stages](#stages). ### variables @@ -151,7 +153,7 @@ thus allowing to fine tune them. Variables can be also defined on a [job level](#job-variables). Except for the user defined variables, there are also the ones set up by the -Runner itself. One example would be `CI_BUILD_REF_NAME` which has the value of +Runner itself. One example would be `CI_COMMIT_REF_NAME` which has the value of the branch or tag name for which project is built. Apart from the variables you can set in `.gitlab-ci.yml`, there are also the so called secret variables which can be set in GitLab's UI. @@ -166,10 +168,11 @@ which can be set in GitLab's UI. 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.** +**By default caching is enabled and shared between pipelines and jobs, +starting from GitLab 9.0** -If `cache` is defined outside the scope of the jobs, it means it is set -globally and all jobs will use its definition. +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`: @@ -202,7 +205,7 @@ rspec: - binaries/ ``` -Locally defined cache overwrites globally defined options. The following `rspec` +Locally defined cache overrides globally defined options. The following `rspec` job will cache only `binaries/`: ```yaml @@ -213,10 +216,15 @@ 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. + The cache is provided on a best-effort basis, so don't expect that the cache will be always present. For implementation details, please check GitLab Runner. @@ -233,6 +241,9 @@ different jobs or even different branches. The `cache:key` variable can use any of the [predefined variables](../variables/README.md). +The default key is **default** across the project, therefore everything is +shared between each pipelines and jobs by default, starting from GitLab 9.0. + --- **Example configurations** @@ -241,7 +252,7 @@ To enable per-job caching: ```yaml cache: - key: "$CI_BUILD_NAME" + key: "$CI_JOB_NAME" untracked: true ``` @@ -249,7 +260,7 @@ To enable per-branch caching: ```yaml cache: - key: "$CI_BUILD_REF_NAME" + key: "$CI_COMMIT_REF_NAME" untracked: true ``` @@ -257,7 +268,7 @@ To enable per-job and per-branch caching: ```yaml cache: - key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME" + key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME" untracked: true ``` @@ -265,7 +276,7 @@ To enable per-branch and per-stage caching: ```yaml cache: - key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME" + key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME" untracked: true ``` @@ -274,7 +285,7 @@ If you use **Windows Batch** to run your shell scripts you need to replace ```yaml cache: - key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%" + key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%" untracked: true ``` @@ -545,13 +556,30 @@ The above script will: Manual actions are a special type of job that are not executed automatically; they need to be explicitly started by a user. Manual actions can be started -from pipeline, build, environment, and deployment views. You can execute the -same manual action multiple times. +from pipeline, build, environment, and deployment views. An example usage of manual actions is deployment to production. Read more at the [environments documentation][env-manual]. +Manual actions can be either optional or blocking. Blocking manual action will +block execution of the pipeline at stage this action is defined in. It is +possible to resume execution of the pipeline when someone executes a blocking +manual actions by clicking a _play_ button. + +When pipeline is blocked it will not be merged if Merge When Pipeline Succeeds +is set. Blocked pipelines also do have a special status, called _manual_. + +Manual actions are non-blocking by default. If you want to make manual action +blocking, it is necessary to add `allow_failure: false` to the job's definition +in `.gitlab-ci.yml`. + +Optional manual actions have `allow_failure: true` set by default. + +**Statuses of optional actions do not contribute to overall pipeline status.** + +> Blocking manual actions were introduced in GitLab 9.0 + ### environment > @@ -711,12 +739,12 @@ deploy as review app: stage: deploy script: make deploy environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` The `deploy as review app` job will be marked as deployment to dynamically -create the `review/$CI_BUILD_REF_NAME` environment, where `$CI_BUILD_REF_NAME` +create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` 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 @@ -822,7 +850,7 @@ To create an archive with a name of the current job: ```yaml job: artifacts: - name: "$CI_BUILD_NAME" + name: "$CI_JOB_NAME" ``` To create an archive with a name of the current branch or tag including only @@ -831,7 +859,7 @@ the files that are untracked by Git: ```yaml job: artifacts: - name: "$CI_BUILD_REF_NAME" + name: "$CI_COMMIT_REF_NAME" untracked: true ``` @@ -841,7 +869,7 @@ tag including only the files that are untracked by Git: ```yaml job: artifacts: - name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}" + name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}" untracked: true ``` @@ -850,7 +878,7 @@ To create an archive with a name of the current [stage](#stages) and branch name ```yaml job: artifacts: - name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}" + name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}" untracked: true ``` @@ -862,7 +890,7 @@ If you use **Windows Batch** to run your shell scripts you need to replace ```yaml job: artifacts: - name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%" + name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%" untracked: true ``` @@ -1003,6 +1031,9 @@ job: ### coverage +**Notes:** +- [Introduced][ce-7447] in GitLab 8.17. + `coverage` allows you to configure how code coverage will be extracted from the job output. @@ -1015,7 +1046,7 @@ A simple example: ```yaml job1: - coverage: /Code coverage: \d+\.\d+/ + coverage: '/Code coverage: \d+\.\d+/' ``` ## Git Strategy @@ -1361,3 +1392,4 @@ CI with various languages. [ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669 [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 |