diff options
| -rw-r--r-- | doc/ci/variables/predefined_variables.md | 3 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 93 |
2 files changed, 94 insertions, 2 deletions
diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 416627740d2..a02b5e786df 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -23,6 +23,9 @@ future GitLab releases.** | `CHAT_INPUT` | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/README.md) command | | `CHAT_CHANNEL` | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/README.md) command | | `CI` | all | 0.4 | Mark that job is executed in CI environment | +| `CI_BUILDS_DIR` | all | 11.10 | The top-level directory where are builds are being executed | +| `CI_CONCURRENT_ID` | all | 11.10 | The unique ID of build execution within single executor | +| `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | The unique ID of build execution within single executor and project ID | | `CI_COMMIT_BEFORE_SHA` | 11.2 | all | The previous latest commit present on a branch before a push request. | | `CI_COMMIT_DESCRIPTION` | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | | `CI_COMMIT_MESSAGE` | 10.8 | all | The full commit message. | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index e75f7050a09..966d16a8f54 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -2341,8 +2341,33 @@ variables: GIT_STRATEGY: clone GIT_CHECKOUT: "false" script: - - git checkout master - - git merge $CI_BUILD_REF_NAME + - git checkout -B master origin/master + - git merge $CI_COMMIT_SHA +``` + +#### Git clean flags + +> Introduced in GitLab Runner 11.10 + +The `GIT_CLEAN_FLAGS` variable can be used to control a default behavior of +`git clean` after checking out the sources. You can set them globally or per-job in the +[`variables`](#variables) section. + +The `GIT_CLEAN_FLAGS` accepts all possible options of the [git clean](https://git-scm.com/docs/git-clean) +command. + +The `git clean` is disabled if `GIT_CHECKOUT: "false"` is specified. + +Consider the following predefined behavior: + +- if not specified it defaults to `-ffdx`, +- if `none` specified it makes the `git clean` command not being executed + +```yaml +variables: + GIT_CLEAN_FLAGS: -ffdx -e cache/ +script: + - ls -al cache/ ``` #### Job stages attempts @@ -2418,6 +2443,69 @@ CAUTION: **Deprecated:** `type` is deprecated, and could be removed in one of the future releases. Use [`stage`](#stage) instead. +### Custom build directories + +> [Introduced][gitlab-runner-1267] in Gitlab Runner 11.10 + +NOTE: **Note:** +This can only be used when `custom_build_dir` is enabled in the [Runner's +configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). +This is the default configuration for `docker` and `kubernetes` executor. + +By default, GitLab Runner clones the repository in unique subpath of the `$CI_BUILDS_DIR` directory, +but sometimes your project might require to have the code in a specific directory, +like the Go projects for example. In that case, you can specify the `GIT_CLONE_PATH` variable +to tell the Runner in which directory to clone the repository: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name + +test: + script: + - pwd +``` + +The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The `$CI_BUILDS_DIR` +is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) +setting. + +Consider that if you executor uses higher than `1` concurrency it might lead +to failures as multiple jobs might be working on the same directory, if the `builds_dir` +is shared between jobs. +GitLab Runner does not try to prevent that situation it is up to Administrator +and Developer to comply with the requirements of runner configuration. + +To avoid such scenario you can use unique path within `$CI_BUILDS_DIR`, as Runner +exposes two additional variables that provide a unique `ID` of concurrency: + +- `$CI_CONCURRENT_ID`: unique identifier for all jobs running within the given executor, +- `$CI_CONCURRENT_PROJECT_ID`: unique identifier for all jobs running within the given executor and project. + +The most stable configuration that should work well in any scenario and on any executor +is to use `$CI_CONCURRENT_ID`: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name + +test: + script: + - pwd +``` + +The `$CI_CONCURRENT_PROJECT_ID` should be used with the conjuction of `$CI_PROJECT_PATH` +as the `$CI_PROJECT_PATH` provides a path of repository: `group/subgroup/project`. + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH + +test: + script: + - pwd +``` + ## Special YAML features It's possible to use special YAML features like anchors (`&`), aliases (`*`) @@ -2604,3 +2692,4 @@ git push -o ci.skip [schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules" [variables]: ../variables/README.md "CI/CD variables" [push-option]: https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt +[gitlab-runner-1267]: https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267 |