From ef10f4c53139ead567b12a2daf8832f02240d0fa Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Thu, 25 May 2017 20:29:12 +0800 Subject: Add docs for protected variables --- doc/ci/variables/README.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 0d4d08106f8..2f2023c02ae 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -11,6 +11,7 @@ this order: 1. [Trigger variables][triggers] (take precedence over all) 1. [Secret variables](#secret-variables) +1. [Protected variables](#protected-variables) 1. YAML-defined [job-level variables](../yaml/README.md#job-variables) 1. YAML-defined [global variables](../yaml/README.md#variables) 1. [Deployment variables](#deployment-variables) @@ -153,9 +154,26 @@ storing things like passwords, secret keys and credentials. Secret variables can be added by going to your project's **Settings ➔ Pipelines**, then finding the section called -**Secret Variables**. +**Secret and protected variables**. -Once you set them, they will be available for all subsequent jobs. +Once you set them, they will be available for all subsequent pipelines. + +## Protected variables + +>**Notes:** +- This feature requires GitLab Runner 0.4.0 or higher. +- A protected variable is a secret variable which is protected. + +All secret variables could be protected. Whenever a secret variable is +protected, it would only be securely passed to pipelines running on the +protected branches or protected tags. The other pipelines would not get any +protected variables. + +Protected variables can be added by going to your project's +**Settings ➔ Pipelines**, then finding the section called +**Secret and protected variables**, and check *Protected*. + +Once you set them, they will be available for all subsequent pipelines. ## Deployment variables @@ -381,7 +399,6 @@ export CI_REGISTRY_USER="gitlab-ci-token" export CI_REGISTRY_PASSWORD="longalfanumstring" ``` -[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 [runner]: https://docs.gitlab.com/runner/ [triggered]: ../triggers/README.md [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger -- cgit v1.2.1 From 88ba7a034be6c2a93c495edd1d1db08ec6d98bb3 Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Thu, 25 May 2017 22:58:51 +0800 Subject: Pass external_url from environment if job doesn't have one Also update the document and add a changelog entry --- doc/ci/environments.md | 6 ++++++ doc/ci/variables/README.md | 1 + 2 files changed, 7 insertions(+) (limited to 'doc/ci') diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 169e0fbae3d..3393030210e 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -94,6 +94,12 @@ the name given in `.gitlab-ci.yml` (with any variables expanded), while the second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, etc. +>**Note:** +Starting with GitLab 9.3, the environment URL is exposed to the Runner via +`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if +the URL was not defined there, the external URL from the environment would be +used. + To sum up, with the above `.gitlab-ci.yml` we have achieved that: - All branches will run the `test` and `build` jobs. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 0d4d08106f8..e4e4e1da250 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -43,6 +43,7 @@ future GitLab releases.** | **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | | **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job | | **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. | +| **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job | | **CI_JOB_ID** | 9.0 | all | The unique id of the current job that GitLab CI uses internally | | **CI_JOB_MANUAL** | 8.12 | all | The flag to indicate that job was manually started | | **CI_JOB_NAME** | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | -- cgit v1.2.1 From 9cc918a5caca931887026d258ea1dcd6499d7c2f Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Fri, 26 May 2017 15:35:30 +0800 Subject: Use be_truthy and add back missing link --- doc/ci/variables/README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 2f2023c02ae..b431cb41f4c 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -399,6 +399,7 @@ export CI_REGISTRY_USER="gitlab-ci-token" export CI_REGISTRY_PASSWORD="longalfanumstring" ``` +[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 [runner]: https://docs.gitlab.com/runner/ [triggered]: ../triggers/README.md [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger -- cgit v1.2.1 From 6914aeaeb78015f2178dd1a612f90ddb150408d8 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Wed, 31 May 2017 13:13:37 +0200 Subject: Update docs related to protected actions --- doc/ci/yaml/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index da20076da52..2df03196f80 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -591,7 +591,7 @@ Optional manual actions have `allow_failure: true` set by default. **Manual actions are considered to be write actions, so permissions for protected branches are used when user wants to trigger an action. In other words, in order to trigger a manual action assigned to a branch that the -pipeline is running for, user needs to have ability to push to this branch.** +pipeline is running for, user needs to have ability to merge to this branch.** ### environment -- cgit v1.2.1 From c4dded593a9df770dd08051fc645f713ca295f13 Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Wed, 31 May 2017 22:45:51 +0800 Subject: Update docs and use protected secret variable as the name --- doc/ci/variables/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index b431cb41f4c..602e2aa5df1 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -154,24 +154,23 @@ storing things like passwords, secret keys and credentials. Secret variables can be added by going to your project's **Settings ➔ Pipelines**, then finding the section called -**Secret and protected variables**. +**Secret variables**. Once you set them, they will be available for all subsequent pipelines. -## Protected variables +## Protected secret variables >**Notes:** -- This feature requires GitLab Runner 0.4.0 or higher. -- A protected variable is a secret variable which is protected. +- This feature requires GitLab 9.3 or higher, and GitLab Runner 0.4.0 or higher. -All secret variables could be protected. Whenever a secret variable is +Secret variables could be protected. Whenever a secret variable is protected, it would only be securely passed to pipelines running on the -protected branches or protected tags. The other pipelines would not get any +[protected branches] or [protected tags]. The other pipelines would not get any protected variables. Protected variables can be added by going to your project's **Settings ➔ Pipelines**, then finding the section called -**Secret and protected variables**, and check *Protected*. +**Secret variables**, and check *Protected*. Once you set them, they will be available for all subsequent pipelines. @@ -403,3 +402,5 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" [runner]: https://docs.gitlab.com/runner/ [triggered]: ../triggers/README.md [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger +[protected branches]: ../../user/project/protected_branches.md +[protected tags]: ../../user/project/protected_tags.md -- cgit v1.2.1 From 76e738fc0ec65513cb4d92a8206109184c74a381 Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Wed, 31 May 2017 22:52:37 +0800 Subject: Fix doc table of contents --- doc/ci/variables/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 602e2aa5df1..71f2088be74 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -11,7 +11,7 @@ this order: 1. [Trigger variables][triggers] (take precedence over all) 1. [Secret variables](#secret-variables) -1. [Protected variables](#protected-variables) +1. [Protected secret variables](#protected-secret-variables) 1. YAML-defined [job-level variables](../yaml/README.md#job-variables) 1. YAML-defined [global variables](../yaml/README.md#variables) 1. [Deployment variables](#deployment-variables) -- cgit v1.2.1 From 2ff3dcaddea075a559163cf3280b0139ca34bd4d Mon Sep 17 00:00:00 2001 From: Jan Christophersen Date: Wed, 31 May 2017 17:53:28 +0000 Subject: Add Documentation for GIT_CHECKOUT variable --- doc/ci/yaml/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'doc/ci') diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2df03196f80..fab5d14ac54 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1105,6 +1105,36 @@ variables: GIT_STRATEGY: none ``` +## Git Checkout + +> Introduced in GitLab Runner 9.3 + +The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either +`clone` or `fetch` to specify whether a `git checkout` should be run. If not +specified, it defaults to true. Like `GIT_STRATEGY`, it can be set in either the +global [`variables`](#variables) section or the [`variables`](#job-variables) +section for individual jobs. + +If set to `false`, the Runner will: + +- when doing `fetch` - update the repository and leave working copy on + the current revision, +- when doing `clone` - clone the repository and leave working copy on the + default branch. + +Having this setting set to `true` will mean that for both `clone` and `fetch` +strategies the Runner will checkout the working copy to a revision related +to the CI pipeline: + +```yaml +variables: + GIT_STRATEGY: clone + GIT_CHECKOUT: false +script: + - git checkout master + - git merge $CI_BUILD_REF_NAME +``` + ## Git Submodule Strategy > Requires GitLab Runner v1.10+. -- cgit v1.2.1 From fb70cf077cbc3b4fe07fad930be67331d2e57817 Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Thu, 1 Jun 2017 16:39:24 +0800 Subject: Merge two items into one in the doc --- doc/ci/variables/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 71f2088be74..0a031578a18 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -10,8 +10,7 @@ The variables can be overwritten and they take precedence over each other in this order: 1. [Trigger variables][triggers] (take precedence over all) -1. [Secret variables](#secret-variables) -1. [Protected secret variables](#protected-secret-variables) +1. [Secret variables](#secret-variables) or [protected secret variables](#protected-secret-variables) 1. YAML-defined [job-level variables](../yaml/README.md#job-variables) 1. YAML-defined [global variables](../yaml/README.md#variables) 1. [Deployment variables](#deployment-variables) -- cgit v1.2.1 From 0ab8c852db118701ae5a1d105c1da74a0b88f60f Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Thu, 1 Jun 2017 21:22:38 +0800 Subject: Just mention which GitLab version is required Feedback: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11688/diffs#note_31277454 --- doc/ci/variables/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 0a031578a18..76ad7c564a3 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -160,7 +160,7 @@ Once you set them, they will be available for all subsequent pipelines. ## Protected secret variables >**Notes:** -- This feature requires GitLab 9.3 or higher, and GitLab Runner 0.4.0 or higher. +This feature requires GitLab 9.3 or higher. Secret variables could be protected. Whenever a secret variable is protected, it would only be securely passed to pipelines running on the -- cgit v1.2.1 From 3f80281d9c07e47cb5cf921add9f5933763ad3df Mon Sep 17 00:00:00 2001 From: vanadium23 Date: Thu, 1 Jun 2017 08:04:16 +0300 Subject: Add slugify project path to CI enviroment variables --- doc/ci/variables/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 76ad7c564a3..ad897d5cf1a 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -56,9 +56,10 @@ future GitLab releases.** | **CI_PIPELINE_TRIGGERED** | all | all | The flag to indicate that job was [triggered] | | **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run | | **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally | -| **CI_PROJECT_NAME** | 8.10 | 0.5 | The project name that is currently being built | +| **CI_PROJECT_NAME** | 8.10 | 0.5 | The project name that is currently being built (actually it is project folder name) | | **CI_PROJECT_NAMESPACE** | 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built | | **CI_PROJECT_PATH** | 8.10 | 0.5 | The namespace with project name | +| **CI_PROJECT_PATH_SLUG** | 9.3 | all | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | | **CI_PROJECT_URL** | 8.10 | 0.5 | The HTTP address to access project | | **CI_REGISTRY** | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry | | **CI_REGISTRY_IMAGE** | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project | -- cgit v1.2.1 From 846b478d3c276765f8f1d5b9aa3a1222c198e030 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien?= Date: Sun, 4 Jun 2017 06:14:42 +0000 Subject: Resolve "Documentation of `.gitlab-ci.yml` states incorrect example for variables" --- doc/ci/variables/README.md | 2 +- doc/ci/yaml/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 76ad7c564a3..656e261dff8 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -122,7 +122,7 @@ global defined variables in your job, define an empty array: ```yaml job_name: - variables: [] + variables: {} ``` You are able to use other variables inside your variable definition (or escape them with `$$`): diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fab5d14ac54..2c9aa437932 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -438,7 +438,7 @@ in your job, define an empty array: ```yaml job_name: - variables: [] + variables: {} ``` Job variables priority is defined in the [variables documentation][variables]. -- cgit v1.2.1 From 144f0e0d12c287e034d9f86326c86f2b1bad55ef Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Mon, 5 Jun 2017 06:26:34 +0300 Subject: Backport CI codeclimate example doc change from EE Signed-off-by: Dmitriy Zaporozhets --- doc/ci/examples/code_climate.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md index bd53f80ce14..c6b9e2065cf 100644 --- a/doc/ci/examples/code_climate.md +++ b/doc/ci/examples/code_climate.md @@ -1,11 +1,11 @@ # Analyze project code quality with Code Climate CLI -This example shows how to run [Code Climate CLI][cli] on your code by using\ +This example shows how to run [Code Climate CLI][cli] on your code by using GitLab CI and Docker. -First, you need GitLab Runner with [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +First, you need GitLab Runner with [docker-in-docker executor][dind]. -Once you setup the Runner add new job to `.gitlab-ci.yml`: +Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called `codeclimate`: ```yaml codeclimate: @@ -25,4 +25,10 @@ codeclimate: This will create a `codeclimate` job in your CI pipeline and will allow you to download and analyze the report artifact in JSON format. +For GitLab [Enterprise Edition Starter][ee] users, this information can be automatically +extracted and shown right in the merge request widget. [Learn more on code quality +diffs in merge requests](../../user/project/merge_requests/code_quality_diff.md). + [cli]: https://github.com/codeclimate/codeclimate +[dind]: ../docker/using_docker_build.md#use-docker-in-docker-executor +[ee]: https://about.gitlab.com/gitlab-ee/ -- cgit v1.2.1 From 30f4f6b1fb8890e106883a84454121a56c9723e0 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Mon, 5 Jun 2017 14:10:25 +0300 Subject: Fix link to ee code quality doc Signed-off-by: Dmitriy Zaporozhets --- doc/ci/examples/code_climate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ci') diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md index c6b9e2065cf..a047e809788 100644 --- a/doc/ci/examples/code_climate.md +++ b/doc/ci/examples/code_climate.md @@ -27,7 +27,7 @@ download and analyze the report artifact in JSON format. For GitLab [Enterprise Edition Starter][ee] users, this information can be automatically extracted and shown right in the merge request widget. [Learn more on code quality -diffs in merge requests](../../user/project/merge_requests/code_quality_diff.md). +diffs in merge requests](http://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.md). [cli]: https://github.com/codeclimate/codeclimate [dind]: ../docker/using_docker_build.md#use-docker-in-docker-executor -- cgit v1.2.1 From c4878a762fe9cc90022277e5f559fa0c169e09e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tor=20Bechmann=20Yamamoto-S=C3=B8rensen?= Date: Tue, 6 Jun 2017 16:55:24 +0900 Subject: Update explanation of job-level variable override to fit example --- doc/ci/variables/README.md | 2 +- doc/ci/yaml/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 56ff245f9f9..23c93c59604 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -120,7 +120,7 @@ The YAML-defined variables are also set to all created tune them. Variables can be defined at a global level, but also at a job level. To turn off -global defined variables in your job, define an empty array: +global defined variables in your job, define an empty hash: ```yaml job_name: diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2c9aa437932..dd4b589d37c 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -434,7 +434,7 @@ but allows you to define job-specific variables. When the `variables` keyword is used on a job level, it overrides the global YAML job variables and predefined ones. To turn off global defined variables -in your job, define an empty array: +in your job, define an empty hash: ```yaml job_name: -- cgit v1.2.1 From 1d0219a52660f4b242a085c1a34311714bb384cf Mon Sep 17 00:00:00 2001 From: John Spaetzel Date: Fri, 14 Apr 2017 19:01:52 -0400 Subject: Add PowerShell to CI variable docs --- doc/ci/variables/README.md | 34 ++++++++++++++++++++++++++++++---- doc/ci/yaml/README.md | 19 +++++++++++++++++++ 2 files changed, 49 insertions(+), 4 deletions(-) (limited to 'doc/ci') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 56ff245f9f9..04ce3cbcaa8 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -345,20 +345,45 @@ All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. In most cases `bash` or `sh` is used to execute the job script. -To access the variables (predefined and user-defined) in a `bash`/`sh` environment, -prefix the variable name with the dollar sign (`$`): +To access environment variables, use the syntax for your Runner's [shell][shellexecutors]. -``` +| Shell | Usage | +|----------------------|-----------------| +| bash/sh | `$variable` | +| windows batch | `%variable%` | +| PowerShell | `$env:variable` | + +To access environment variables in bash, prefix the variable name with (`$`): + +```yaml job_name: script: - echo $CI_JOB_ID ``` +To access environment variables in **Windows Batch**, surround the variable +with (`%`): + +```yaml +job_name: + script: + - echo %CI_JOB_ID% +``` + +To access environment variables in a **Windows PowerShell** environment, prefix +the variable name with (`$env:`): + +```yaml +job_name: + script: + - echo $env:CI_JOB_ID +``` + You can also list all environment variables with the `export` command, but be aware that this will also expose the values of all the secret variables you set, in the job log: -``` +```yaml job_name: script: - export @@ -405,3 +430,4 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger [protected branches]: ../../user/project/protected_branches.md [protected tags]: ../../user/project/protected_tags.md +[shellexecutors]: https://docs.gitlab.com/runner/executors/ diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2c9aa437932..52d7a33fc9d 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -297,6 +297,15 @@ cache: untracked: true ``` +If you use **Windows PowerShell** to run your shell scripts you need to replace +`$` with `$env:`: + +```yaml +cache: + key: "$env:CI_JOB_STAGE/$env:CI_COMMIT_REF_NAME" + untracked: true +``` + ## Jobs `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job @@ -909,6 +918,16 @@ job: untracked: true ``` +If you use **Windows PowerShell** to run your shell scripts you need to replace +`$` with `$env:`: + +```yaml +job: + artifacts: + name: "$env:CI_JOB_STAGE_$env:CI_COMMIT_REF_NAME" + untracked: true +``` + #### artifacts:when > Introduced in GitLab 8.9 and GitLab Runner v1.3.0. -- cgit v1.2.1