diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-03-16 13:32:03 +0300 |
---|---|---|
committer | Lin Jen-Shin <godfat@godfat.org> | 2017-03-16 13:38:13 +0300 |
commit | 3fa67889122c9969fdc7c3eef0ab0537478136fe (patch) | |
tree | abc944de68cdec0b98cdd2369ec4597f62da1450 /doc | |
parent | 09924098d836909811ce96bb219823676d0a92f8 (diff) |
Merge branch 'zj-rename-ci-vars' into 'master'
Futher rename the CI variables
See merge request !9851
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ci/docker/using_docker_build.md | 14 | ||||
-rw-r--r-- | doc/ci/environments.md | 38 | ||||
-rw-r--r-- | doc/ci/review_apps/index.md | 2 | ||||
-rw-r--r-- | doc/ci/variables/README.md | 52 | ||||
-rw-r--r-- | doc/ci/yaml/README.md | 26 | ||||
-rw-r--r-- | doc/user/project/new_ci_build_permissions_model.md | 4 |
6 files changed, 68 insertions, 68 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 8620984d40d..b3c9fe275c4 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -298,14 +298,14 @@ could look like: - docker:dind stage: build script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com - docker build -t registry.example.com/group/project:latest . - docker push registry.example.com/group/project:latest ``` You have to use the special `gitlab-ci-token` user created for you in order to push to the Registry connected to your project. Its password is provided in the -`$CI_BUILD_TOKEN` variable. This allows you to automate building and deployment +`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment of your Docker images. You can also make use of [other variables](../variables/README.md) to avoid hardcoding: @@ -315,10 +315,10 @@ services: - docker:dind variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_BUILD_REF_NAME + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME before_script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN $CI_REGISTRY + - docker login -u gitlab-ci-token -p $CI_COMMIT_TOKEN $CI_REGISTRY build: stage: build @@ -328,7 +328,7 @@ build: ``` Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied -to this project, and `$CI_BUILD_REF_NAME` would be resolved to the branch or +to this project, and `$CI_COMMIT_REF_NAME` would be resolved to the branch or tag name for this particular job. We also declare our own variable, `$IMAGE_TAG`, combining the two to save us some typing in the `script` section. @@ -350,11 +350,11 @@ stages: - deploy variables: - CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_BUILD_REF_NAME + CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_COMMIT_REF_NAME CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project:latest before_script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com build: stage: build diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 3c31ba45d3d..b28f3e13eae 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -263,7 +263,7 @@ This works just like any other terminal - you'll be in the container created by your deployment, so you can run shell commands and get responses in real time, check the logs, try out configuration or code tweaks, etc. You can open multiple terminals to the same environment - they each get their own shell -session - and even a multiplexer like `screen` or `tmux`! +session - and even a multiplexer like `screen` or `tmux`! >**Note:** Container-based deployments often lack basic tools (like an editor), and may @@ -295,7 +295,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -306,22 +306,22 @@ deploy_review: Let's break it down in pieces. The job's name is `deploy_review` and it runs on the `deploy` stage. The `script` at this point is fictional, you'd have to use your own based on your deployment. Then, we set the `environment` with the -`environment:name` being `review/$CI_BUILD_REF_NAME`. Now that's an interesting +`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting one. Since the [environment name][env-name] can contain slashes (`/`), we can use this pattern to distinguish between dynamic environments and the regular ones. -So, the first part is `review`, followed by a `/` and then `$CI_BUILD_REF_NAME` -which takes the value of the branch name. Since `$CI_BUILD_REF_NAME` itself may +So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME` +which takes the value of the branch name. Since `$CI_COMMIT_REF_NAME` itself may also contain `/`, or other characters that would be invalid in a domain name or URL, we use `$CI_ENVIRONMENT_SLUG` in the `environment:url` so that the environment can get a specific and distinct URL for each branch. In this case, -given a `$CI_BUILD_REF_NAME` of `100-Do-The-Thing`, the URL will be something +given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something like `https://100-do-the-4f99a2.example.com`. Again, the way you set up the web server to serve these requests is based on your setup. -You could also use `$CI_BUILD_REF_SLUG` in `environment:url`, e.g.: -`https://$CI_BUILD_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` +You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`, e.g.: +`https://$CI_COMMIT_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique, but if you're using a workflow like [GitLab Flow][gitlab-flow], collisions are very unlikely, and you may prefer environment names to be more closely based on the branch name - the example @@ -356,7 +356,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -387,16 +387,16 @@ deploy_prod: A more realistic example would include copying files to a location where a webserver (NGINX) could then read and serve. The example below will copy the -`public` directory to `/srv/nginx/$CI_BUILD_REF_SLUG/public`: +`public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`: ```yaml review_app: stage: deploy script: - - rsync -av --delete public /srv/nginx/$CI_BUILD_REF_SLUG + - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG environment: - name: review/$CI_BUILD_REF_NAME - url: https://$CI_BUILD_REF_SLUG.example.com + name: review/$CI_COMMIT_REF_NAME + url: https://$CI_COMMIT_REF_SLUG.example.com ``` It is assumed that the user has already setup NGINX and GitLab Runner in the @@ -526,7 +526,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review only: @@ -542,7 +542,7 @@ stop_review: - echo "Remove review app" when: manual environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME action: stop ``` @@ -568,13 +568,13 @@ You can read more in the [`.gitlab-ci.yml` reference][onstop]. As we've seen in the [dynamic environments](#dynamic-environments), you can prepend their name with a word, then followed by a `/` and finally the branch -name which is automatically defined by the `CI_BUILD_REF_NAME` variable. +name which is automatically defined by the `CI_COMMIT_REF_NAME` variable. In short, environments that are named like `type/foo` are presented under a group named `type`. -In our minimal example, we name the environments `review/$CI_BUILD_REF_NAME` -where `$CI_BUILD_REF_NAME` is the branch name: +In our minimal example, we name the environments `review/$CI_COMMIT_REF_NAME` +where `$CI_COMMIT_REF_NAME` is the branch name: ```yaml deploy_review: @@ -582,7 +582,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME ``` In that case, if you visit the Environments page, and provided the branches diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index c679ea4e298..28c484ddbe6 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -80,7 +80,7 @@ The process of adding Review Apps in your workflow would look like: 1. [Install][install-runner] and [configure][conf-runner] a Runner that does the deployment. 1. Set up a job in `.gitlab-ci.yml` that uses the predefined - [predefined CI environment variable][variables] `${CI_BUILD_REF_NAME}` to + [predefined CI environment variable][variables] `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. 1. Optionally set a job that [manually stops][manual-env] the Review Apps. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 03e6b5303c5..5baff9cc6ba 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -236,18 +236,18 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI=true ++ export CI_DEBUG_TRACE=false ++ CI_DEBUG_TRACE=false -++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_REF_NAME=master -++ CI_BUILD_REF_NAME=master -++ export CI_BUILD_ID=7046507 -++ CI_BUILD_ID=7046507 -++ export CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git -++ CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git -++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_REF_NAME=master +++ CI_COMMIT_REF_NAME=master +++ export CI_JOB_ID=7046507 +++ CI_JOB_ID=7046507 +++ export CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx ++ export CI_PROJECT_ID=1796893 ++ CI_PROJECT_ID=1796893 ++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace @@ -266,20 +266,20 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI=true ++ export GITLAB_CI=true ++ GITLAB_CI=true -++ export CI_BUILD_ID=7046507 -++ CI_BUILD_ID=7046507 -++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_REF_NAME=master -++ CI_BUILD_REF_NAME=master -++ export CI_BUILD_NAME=debug_trace -++ CI_BUILD_NAME=debug_trace -++ export CI_BUILD_STAGE=test -++ CI_BUILD_STAGE=test +++ export CI_JOB_ID=7046507 +++ CI_JOB_ID=7046507 +++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_REF_NAME=master +++ CI_COMMIT_REF_NAME=master +++ export CI_COMMIT_NAME=debug_trace +++ CI_JOB_NAME=debug_trace +++ export CI_JOB_STAGE=test +++ CI_JOB_STAGE=test ++ export CI_SERVER_NAME=GitLab ++ CI_SERVER_NAME=GitLab ++ export CI_SERVER_VERSION=8.14.3-ee diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 49fa8761e5e..ad3ebd144df 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -153,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. @@ -252,7 +252,7 @@ To enable per-job caching: ```yaml cache: - key: "$CI_BUILD_NAME" + key: "$CI_JOB_NAME" untracked: true ``` @@ -260,7 +260,7 @@ To enable per-branch caching: ```yaml cache: - key: "$CI_BUILD_REF_NAME" + key: "$CI_COMMIT_REF_NAME" untracked: true ``` @@ -268,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 ``` @@ -276,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 ``` @@ -285,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 ``` @@ -739,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 @@ -850,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 @@ -859,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 ``` @@ -869,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 ``` @@ -878,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 ``` @@ -890,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 ``` diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 5f631f63050..b559d132590 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -119,7 +119,7 @@ And then the users could also use it in their CI jobs all Docker related commands to interact with GitLab Container Registry. For example: ``` -docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com +docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com ``` Using single token had multiple security implications: @@ -208,7 +208,7 @@ This is how an example usage can look like: ``` test: script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN $CI_REGISTRY + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY - docker pull $CI_REGISTRY/group/other-project:latest - docker run $CI_REGISTRY/group/other-project:latest ``` |