diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-06-22 12:10:06 +0000 |
---|---|---|
committer | Rémy Coutable <remy@rymai.me> | 2016-06-22 15:45:15 +0200 |
commit | f81259d1364f5f486e001294823d057be6405b53 (patch) | |
tree | 5a4532a932538f77b497c7c7c9d4383b203ec1f3 | |
parent | bdaced56b4086579ab6d28c9d20b886584b2f8c9 (diff) | |
download | gitlab-ce-f81259d1364f5f486e001294823d057be6405b53.tar.gz |
Merge branch 'ci-git' into 'master'
Document `GIT_STRATEGY` and `GIT_DEPTH`
## What does this MR do?
Documents `GIT_STRATEGY` and `GIT_DEPTH`. Also fixes the TOC since the anchors weren't working.
## Are there points in the code the reviewer needs to double check?
The TOC and the location of the new entries.
## Why was this MR needed?
## What are the relevant issue numbers?
https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/merge_requests/188
## Screenshots (if relevant)
![image](/uploads/eccfd60199d81e6588c13aab817f0eb5/image.png)
![image](/uploads/bbbffe61db64ef17f1fa52907275f3d4/image.png)
/cc @axil @ayufan
See merge request !4720
Signed-off-by: Rémy Coutable <remy@rymai.me>
-rw-r--r-- | CHANGELOG | 1 | ||||
-rw-r--r-- | doc/ci/yaml/README.md | 103 |
2 files changed, 81 insertions, 23 deletions
diff --git a/CHANGELOG b/CHANGELOG index 11791afd776..0b80d5a0aa7 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -3,6 +3,7 @@ Please view this file on the master branch, on stable branches it's out of date. v 8.9.1 (unreleased) - Refactor labels documentation. !3347 - Fix some CI wording in documentation. !4660 + - Document `GIT_STRATEGY` and `GIT_DEPTH`. !4720 - Fix MR-auto-close text added to description. !4836 - Fix typo in export failure email. !4847 diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index b134b5cd5d3..ef9feb683ef 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -13,32 +13,34 @@ If you want a quick introduction to GitLab CI, follow our **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - [.gitlab-ci.yml](#gitlab-ci-yml) - - [image and services](#image-and-services) - - [before_script](#before_script) - - [after_script](#after_script) - - [stages](#stages) - - [types](#types) - - [variables](#variables) - - [cache](#cache) - - [cache:key](#cache-key) + - [image and services](#image-and-services) + - [before_script](#before_script) + - [after_script](#after_script) + - [stages](#stages) + - [types](#types) + - [variables](#variables) + - [cache](#cache) + - [cache:key](#cache-key) - [Jobs](#jobs) - - [script](#script) - - [stage](#stage) - - [job variables](#job-variables) - - [only and except](#only-and-except) - - [tags](#tags) - - [when](#when) - - [environment](#environment) - - [artifacts](#artifacts) - - [artifacts:name](#artifacts-name) - - [artifacts:when](#artifacts-when) - - [artifacts:expire_in](#artifacts-expire_in) - - [dependencies](#dependencies) - - [before_script and after_script](#before_script-and-after_script) + - [script](#script) + - [stage](#stage) + - [only and except](#only-and-except) + - [job variables](#job-variables) + - [tags](#tags) + - [when](#when) + - [environment](#environment) + - [artifacts](#artifacts) + - [artifacts:name](#artifactsname) + - [artifacts:when](#artifactswhen) + - [artifacts:expire_in](#artifactsexpire_in) + - [dependencies](#dependencies) + - [before_script and after_script](#before_script-and-after_script) +- [Git Strategy](#git-strategy) +- [Shallow cloning](#shallow-cloning) - [Hidden jobs](#hidden-jobs) - [Special YAML features](#special-yaml-features) - - [Anchors](#anchors) -- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ci-yml) + - [Anchors](#anchors) +- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ciyml) - [Skipping builds](#skipping-builds) - [Examples](#examples) @@ -821,6 +823,61 @@ job: - execute this after my script ``` +## Git Strategy + +>**Note:** +Introduced in GitLab 8.9 as an experimental feature. May change in future +releases or be removed completely. + +You can set the `GIT_STRATEGY` used for getting recent application code. `clone` +is slower, but makes sure you have a clean directory before every build. `fetch` +is faster. `GIT_STRATEGY` can be specified in the global `variables` section or +in the `variables` section for individual jobs. If it's not specified, then the +default from project settings will be used. + +``` +variables: + GIT_STRATEGY: clone +``` + +or + +``` +variables: + GIT_STRATEGY: fetch +``` + +## Shallow cloning + +>**Note:** +Introduced in GitLab 8.9 as an experimental feature. May change in future +releases or be removed completely. + +You can specify the depth of fetching and cloning using `GIT_DEPTH`. This allows +shallow cloning of the repository which can significantly speed up cloning for +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. + +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 +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. + +Builds 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: +``` +variables: + GIT_DEPTH: "3" +``` + ## Hidden jobs >**Note:** |