From 1d4fa0e9b560063136f62cef75d13a9fb7e690bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Trzci=C5=84ski?= <ayufan@ayufan.eu> Date: Thu, 4 Apr 2019 15:56:55 +0200 Subject: [PATCH] Add documentation for new big-repos features This adds documentation for: - `CI_BUILDS_DIR`, - `CI_CONCURRENT_ID`, - `CI_CONCURRENT_PROJECT_ID`, - `GIT_CLONE_PATH`, - `GIT_CLEAN_FLAGS` --- doc/ci/variables/predefined_variables.md | 3 + doc/ci/yaml/README.md | 97 +++++++++++++++++++++++- 2 files changed, 98 insertions(+), 2 deletions(-) diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 416627740d2..b429dc8c8be 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 | Top-level directory where builds are executed. | +| `CI_CONCURRENT_ID` | all | 11.10 | Unique ID of build execution within a single executor. | +| `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | Unique ID of build execution within a single executor and project. | | `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..e8e0c0e7fda 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -2341,8 +2341,35 @@ 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 is used to control the default behavior of +`git clean` after checking out the sources. You can set it globally or per-job in the +[`variables`](#variables) section. + +`GIT_CLEAN_FLAGS` accepts all possible options of the [git clean](https://git-scm.com/docs/git-clean) +command. + +`git clean` is disabled if `GIT_CHECKOUT: "false"` is specified. + +If `GIT_CLEAN_FLAGS` is: + +- Not specified, `git clean` flags default to `-ffdx`. +- Given the value `none`, `git clean` is not executed. + +For example: + +```yaml +variables: + GIT_CLEAN_FLAGS: -ffdx -e cache/ +script: + - ls -al cache/ ``` #### Job stages attempts @@ -2418,6 +2445,72 @@ CAUTION: **Deprecated:** `type` is deprecated, and could be removed in one of the future releases. Use [`stage`](#stage) instead. +## Custom build directories + +> [Introduced][https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/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 a unique subpath of the `$CI_BUILDS_DIR` directory. +However, sometimes your project might require the code in a specific directory, +but sometimes your project might require to have the code in a specific directory, +like 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 directory set in `$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. + +### Handling concurrency + +An executor using a concurrency greater than `1` might lead +to failures because multiple jobs might be working on the same directory if the `builds_dir` +is shared between jobs. +GitLab Runner does not try to prevent this situation. It is up to the administrator +and developers to comply with the requirements of Runner configuration. + +To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because Runner +exposes two additional variables that provide a unique `ID` of concurrency: + +- `$CI_CONCURRENT_ID`: Unique ID for all jobs running within the given executor. +- `$CI_CONCURRENT_PROJECT_ID`: Unique ID 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` in the `GIT_CLONE_PATH`. For example: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name + +test: + script: + - pwd +``` + +The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH` +as the `$CI_PROJECT_PATH` provides a path of a repository. That is, `group/subgroup/project`. For example: + +```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 (`*`) -- 2.30.9