diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-10-22 11:31:16 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-10-22 11:31:16 +0000 |
| commit | 905c1110b08f93a19661cf42a276c7ea90d0a0ff (patch) | |
| tree | 756d138db422392c00471ab06acdff92c5a9b69c /doc/ci | |
| parent | 50d93f8d1686950fc58dda4823c4835fd0d8c14b (diff) | |
| download | gitlab-ce-905c1110b08f93a19661cf42a276c7ea90d0a0ff.tar.gz | |
Add latest changes from gitlab-org/gitlab@12-4-stable-ee
Diffstat (limited to 'doc/ci')
38 files changed, 531 insertions, 302 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index cc1c85d1a53..5286764d178 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -85,7 +85,7 @@ GitLab CI/CD supports numerous configuration options: | [Job artifacts](../user/project/pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | | [Schedule pipelines](../user/project/pipelines/schedules.md) | Schedule pipelines to run as often as you need. | -| [Custom path for `.gitlab-ci.yml`](../user/project/pipelines/settings.md#custom-ci-config-path) | Define a custom path for the CI/CD configuration file. | +| [Custom path for `.gitlab-ci.yml`](../user/project/pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. | | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.| | [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | | [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. | @@ -113,7 +113,7 @@ Its feature set is listed on the table below according to DevOps stages. | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the performance impact of pending code changes. | | [CI services](services/README.md) | Link Docker containers with your base image.| | [Code Quality](../user/project/merge_requests/code_quality.md) **(STARTER)** | Analyze your source code quality. | -| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. | +| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | | [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | | [JUnit tests](junit_test_reports.md) | Identify script failures directly on merge requests. | | [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | @@ -161,9 +161,9 @@ See also: The following articles explain reasons to use GitLab CI/CD for your CI/CD infrastructure: -- [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/) -- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/) -- [5 Teams that made the switch to GitLab CI/CD](https://about.gitlab.com/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/) +- [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/blog/2016/10/17/gitlab-ci-oohlala/) +- [Building our web-app on GitLab CI](https://about.gitlab.com/blog/2016/07/22/building-our-web-app-on-gitlab-ci/) +- [5 Teams that made the switch to GitLab CI/CD](https://about.gitlab.com/blog/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/) See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 558229187f1..6b8e7fa2ad5 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -12,8 +12,9 @@ content of a previous job. It can be particularly useful when you are developing software that depends on other libraries which are fetched via the internet during build time. -If caching is enabled, it's shared between pipelines and jobs by default, -starting from GitLab 9.0. +If caching is enabled, it's shared between pipelines and jobs at the project +level by default, starting from GitLab 9.0. Caches are not shared across +projects. Make sure you read the [`cache` reference](../yaml/README.md#cache) to learn how it is defined in `.gitlab-ci.yml`. @@ -202,7 +203,7 @@ For more fine tuning, read also about the The most common use case of cache is to preserve contents between subsequent runs of jobs for things like dependencies and commonly used libraries -(Nodejs packages, PHP packages, rubygems, python libraries, etc.), +(Nodejs packages, PHP packages, rubygems, Python libraries, etc.), so they don't have to be re-fetched from the public internet. NOTE: **Note:** @@ -268,7 +269,7 @@ test: ### Caching Python dependencies Assuming your project is using [pip](https://pip.pypa.io/en/stable/) to install -the python dependencies, the following example defines `cache` globally so that +the Python dependencies, the following example defines `cache` globally so that all jobs inherit it. Python libraries are installed in a virtualenv under `venv/`, pip's cache is defined under `.cache/pip/` and both are cached per-branch: @@ -490,8 +491,8 @@ job B: To fix that, use different `keys` for each job. In another case, let's assume you have more than one Runners assigned to your -project, but the distributed cache is not enabled. We want the second time the -pipeline is run, `job A` and `job B` to re-use their cache (which in this case +project, but the distributed cache is not enabled. The second time the +pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case will be different): ```yaml @@ -517,7 +518,7 @@ job B: ``` In that case, even if the `key` is different (no fear of overwriting), you -might experience the cached files to "get cleaned" before each stage if the +might experience that the cached files "get cleaned" before each stage if the jobs run on different Runners in the subsequent pipelines. ## Clearing the cache diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index 40357608da4..234e7f4ed80 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -19,7 +19,7 @@ GitLab ChatOps is built upon two existing features: - [GitLab CI/CD](../README.md). - [Slack Slash Commands](../../user/project/integrations/slack_slash_commands.md). -A new `run` action has been added to the [slash commands](../../integration/slash_commands.md), which takes two arguments: a `<job name>` to execute and the `<job arguments>`. When executed, ChatOps will look up the specified job name and attempt to match it to a corresponding job in [.gitlab-ci.yml](../yaml/README.md). If a matching job is found on `master`, a pipeline containing just that job is scheduled. Two additional [CI/CD variables](../variables/README.md#predefined-environment-variables) are passed to the job: `CHAT_INPUT` contains any additional arguments, and `CHAT_CHANNEL` is set to the name of channel the action was triggered in. +A new `run` action has been added to the [slash commands](../../integration/slash_commands.md), which takes two arguments: a `<job name>` to execute and the `<job arguments>`. When executed, ChatOps will look up the specified job name and attempt to match it to a corresponding job in [`.gitlab-ci.yml`](../yaml/README.md). If a matching job is found on `master`, a pipeline containing just that job is scheduled. Two additional [CI/CD variables](../variables/README.md#predefined-environment-variables) are passed to the job: `CHAT_INPUT` contains any additional arguments, and `CHAT_CHANNEL` is set to the name of channel the action was triggered in. After the job has finished, its output is sent back to Slack provided it has completed within 30 minutes. If a job takes more than 30 minutes to run it must use the Slack API to manually send data back to a channel. diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index db647530fcd..35e2117c285 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -7,7 +7,7 @@ type: index, howto >[Introduced][ee-4642] in [GitLab Premium][eep] 10.6. NOTE: **Note:** -This feature [is available for free](https://about.gitlab.com/2019/09/09/ci-cd-github-extended-again/) to +This feature [is available for free](https://about.gitlab.com/blog/2019/09/09/ci-cd-github-extended-again/) to GitLab.com users until March 22nd, 2020. GitLab CI/CD can be used with: @@ -100,7 +100,6 @@ requests and not on branches you can add `except: [branches]` to the job specs. [Read more](https://gitlab.com/gitlab-org/gitlab/issues/24089#workaround). [ee-4642]: https://gitlab.com/gitlab-org/gitlab/merge_requests/4642 -[ee-4642]: https://gitlab.com/gitlab-org/gitlab/merge_requests/4642 [eep]: https://about.gitlab.com/pricing/ [mirroring]: ../../workflow/repository_mirroring.md [settings]: ../../user/project/settings/index.md#sharing-and-permissions diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 23604e8f898..7215dec287e 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -73,4 +73,4 @@ A directed acyclic graph is a complicated feature, and as of the initial MVC the are certain use cases that you may need to work around. For more information: - [`needs` requirements and limitations](../yaml/README.md#requirements-and-limitations). -- Related epic [gitlab-org#1716](https://gitlab.com/groups/gitlab-org/-/epics/1716). +- Related epic [tracking planned improvements](https://gitlab.com/groups/gitlab-org/-/epics/1716). diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index a60ede2c8f8..f4bb7cd7d9f 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -117,10 +117,10 @@ not without its own challenges: history. Concurrent jobs work fine because every build gets it's own instance of Docker engine so they won't conflict with each other. But this also means jobs can be slower because there's no caching of layers. -- By default, `docker:dind` uses `--storage-driver vfs` which is the slowest - form offered. To use a different driver, see - [Using the overlayfs driver](#using-the-overlayfs-driver). -- Since the `docker:dind` container and the runner container don't share their +- By default, Docker 17.09 and higher uses `--storage-driver overlay2` which is + the recommended storage driver. See [Using the overlayfs driver](#using-the-overlayfs-driver) + for details. +- Since the `docker:19.03.1-dind` container and the Runner container don't share their root filesystem, the job's working directory can be used as a mount point for child containers. For example, if you have files you want to share with a child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH` @@ -155,7 +155,7 @@ docker-in-docker service and [GitLab.com Shared Runners](../../user/gitlab_com/index.html#shared-runners) support this. -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install). +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and `privileged` mode: @@ -218,13 +218,10 @@ support this. # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # # Note that if you're using the Kubernetes executor, the variable - # should be set to tcp://localhost:2376/ because of how the + # should be set to tcp://localhost:2376 because of how the # Kubernetes executor connects services to the job container - # DOCKER_HOST: tcp://localhost:2376/ + # DOCKER_HOST: tcp://localhost:2376 # - # When using dind, it's wise to use the overlayfs driver for - # improved performance. - DOCKER_DRIVER: overlay2 # Specify to Docker where to create the certificates, Docker will # create them automatically on boot, and will create # `/certs/client` that will be shared between the service and job @@ -283,15 +280,12 @@ variables: # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services # # Note that if you're using the Kubernetes executor, the variable should be set to - # tcp://localhost:2375/ because of how the Kubernetes executor connects services + # tcp://localhost:2375 because of how the Kubernetes executor connects services # to the job container - # DOCKER_HOST: tcp://localhost:2375/ + # DOCKER_HOST: tcp://localhost:2375 # - # For non-Kubernetes executors, we use tcp://docker:2375/ - DOCKER_HOST: tcp://docker:2375/ - # When using dind, it's wise to use the overlayfs driver for - # improved performance. - DOCKER_DRIVER: overlay2 + # For non-Kubernetes executors, we use tcp://docker:2375 + DOCKER_HOST: tcp://docker:2375 # # This will instruct Docker not to start over TLS. DOCKER_TLS_CERTDIR: "" @@ -317,12 +311,12 @@ container so that Docker is available in the context of that image. NOTE: **Note:** If you bind the Docker socket [when using GitLab Runner 11.11 or newer](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1261), -you can no longer use `docker:dind` as a service because volume bindings +you can no longer use `docker:19.03.1-dind` as a service because volume bindings are done to the services as well, making these incompatible. In order to do that, follow the steps: -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install). +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: @@ -332,14 +326,14 @@ In order to do that, follow the steps: --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ - --docker-image "docker:stable" \ + --docker-image "docker:19.03.1" \ --docker-volumes /var/run/docker.sock:/var/run/docker.sock ``` The above command will register a new Runner to use the special - `docker:stable` image which is provided by Docker. **Notice that it's using - the Docker daemon of the Runner itself, and any containers spawned by docker - commands will be siblings of the Runner rather than children of the runner.** + `docker:19.03.1` image which is provided by Docker. **Notice that it's using + the Docker daemon of the Runner itself, and any containers spawned by Docker + commands will be siblings of the Runner rather than children of the Runner.** This may have complications and limitations that are unsuitable for your workflow. The above command will create a `config.toml` entry similar to this: @@ -351,7 +345,7 @@ In order to do that, follow the steps: executor = "docker" [runners.docker] tls_verify = false - image = "docker:stable" + image = "docker:19.03.1" privileged = false disable_cache = false volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] @@ -360,10 +354,11 @@ In order to do that, follow the steps: ``` 1. You can now use `docker` in the build script (note that you don't need to - include the `docker:dind` service as when using the Docker in Docker executor): + include the `docker:19.03.1-dind` service as when using the Docker in Docker + executor): ```yaml - image: docker:stable + image: docker:19.03.1 before_script: - docker info @@ -417,14 +412,15 @@ any image that's used with the `--cache-from` argument must first be pulled Here's a simple `.gitlab-ci.yml` file showing how Docker caching can be utilized: ```yaml -image: docker:stable +image: docker:19.03.1 services: - - docker:dind + - docker:19.03.1-dind variables: - DOCKER_HOST: tcp://docker:2375 - DOCKER_DRIVER: overlay2 + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" before_script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY @@ -526,7 +522,7 @@ Some things you should be aware of: longer, but means you don’t get stuck without security patches to base images. - Doing an explicit `docker pull` before each `docker run` fetches the latest image that was just built. This is especially important if you are - using multiple runners that cache images locally. Using the git SHA in your + using multiple runners that cache images locally. Using the Git SHA in your image tag makes this less necessary since each job will be unique and you shouldn't ever have a stale image. However, it's still possible to have a stale image if you re-build a given commit after a dependency has changed. @@ -597,7 +593,6 @@ assuming you have it configured with [TLS enabled](#tls-enabled): # `/certs/client` that will be shared between the service and # build container. DOCKER_TLS_CERTDIR: "/certs" - DOCKER_DRIVER: overlay2 stage: build script: - docker build -t my-docker-image . @@ -618,37 +613,36 @@ If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.y could look like: ```yaml - build: - image: docker:stable - services: - - docker:dind - variables: - DOCKER_HOST: tcp://docker:2375 - DOCKER_DRIVER: overlay2 - stage: build - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $CI_REGISTRY/group/project/image:latest . - - docker push $CI_REGISTRY/group/project/image:latest +build: + image: docker:19.03.1 + stage: build + services: + - docker:19.03.1-dind + variables: + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $CI_REGISTRY/group/project/image:latest . + - docker push $CI_REGISTRY/group/project/image:latest ``` You can also make use of [other variables](../variables/README.md) to avoid hardcoding: ```yaml -services: - - docker:dind - -variables: - DOCKER_HOST: tcp://docker:2375 - DOCKER_DRIVER: overlay2 - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - -before_script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - build: + image: docker:19.03.1 stage: build + services: + - docker:19.03.1-dind + variables: + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG ``` @@ -667,9 +661,9 @@ when needed. Changes to `master` also get tagged as `latest` and deployed using an application-specific deploy script: ```yaml -image: docker:stable +image: docker:19.03.1 services: - - docker:dind + - docker:19.03.1-dind stages: - build @@ -678,8 +672,9 @@ stages: - deploy variables: - DOCKER_HOST: tcp://docker:2375 - DOCKER_DRIVER: overlay2 + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 56200142055..dcf4d8dde2d 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -28,18 +28,28 @@ either: - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations respectively. +NOTE: **Note:** +This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable +pipelines that are run from an [external integration](../user/project/integrations/project_services.md#services). + ## Per-project user setting -The setting to enable or disable GitLab CI/CD can be found under your project's -**Settings > General > Permissions**. Choose one of "Disabled", "Only team members" -or "Everyone with access" and hit **Save changes** for the settings to take effect. +The setting to enable or disable GitLab CI/CD Pipelines can be found in your project in +**Settings > General > Visibility, project features, permissions**. If the project +visibility is set to: + +- **Private**, only project members can access pipelines. +- **Internal** or **Public**, pipelines can be made accessible to either + project members only or everyone with access. + +Press **Save changes** for the settings to take effect. - + ## Site-wide admin setting You can disable GitLab CI/CD site-wide, by modifying the settings in `gitlab.yml` -and `gitlab.rb` for source and Omnibus installations respectively. +for source installations, and `gitlab.rb` for Omnibus installations. Two things to note: diff --git a/doc/ci/environments.md b/doc/ci/environments.md index d3a8689551a..cef95c8e22a 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -131,15 +131,27 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following: job will deploy our code to a staging server while the deployment will be recorded in an environment named `staging`. -> Starting with GitLab 8.15, the environment name is exposed to the Runner in -> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is -> 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. -> -> Starting with GitLab 9.3, the environment URL is exposed to the Runner via -> `$CI_ENVIRONMENT_URL`. The URL is expanded from `.gitlab-ci.yml`, or if -> the URL was not defined there, the external URL from the environment is used. +#### Environment variables and Runner + +Starting with GitLab 8.15, the environment name is exposed to the Runner in +two forms: + +- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any variables + expanded). +- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URLs, + DNS, etc. + +If you change the name of an existing environment, the: + +- `$CI_ENVIRONMENT_NAME` variable will be updated with the new environment name. +- `$CI_ENVIRONMENT_SLUG` variable will remain unchanged to prevent unintended side + effects. + +Starting with GitLab 9.3, the environment URL is exposed to the Runner via +`$CI_ENVIRONMENT_URL`. The URL is expanded from either: + +- `.gitlab-ci.yml`. +- The external URL from the environment if not defined in `.gitlab-ci.yml`. ### Configuring manual deployments @@ -679,7 +691,7 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scoping environments with specs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -> - [Scoping for environment variables was moved to Core](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/30779) to Core in Gitlab 12.2. +> - [Scoping for environment variables was moved to Core](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/30779) to Core in GitLab 12.2. You can limit the environment scope of a variable by defining which environments it can be available for. @@ -736,7 +748,7 @@ Re-using variables defined inside `script` as part of the environment name will Below are some links you may find interesting: - [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment) -- [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) +- [A blog post on Deployments & Environments](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md) - [Deploy Boards for your applications running on Kubernetes](../user/project/deploy_boards.md) **(PREMIUM)** diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 73f7a555b9c..d2333f7e468 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -11,9 +11,9 @@ implement [GitLab CI/CD](../README.md) for your specific use case. Examples are available in several forms. As a collection of: - `.gitlab-ci.yml` [template files](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/lib/gitlab/ci/templates) maintained in GitLab. When you create a new file via the UI, - GitLab will give you the option to choose one of these templates. This will allow you to quickly bootstrap your project for CI/CD. + GitLab will give you the option to choose one of these templates. This will allow you to start using CI/CD with your project quickly. If your favorite programming language or framework are missing, we would love your help by sending a merge request with a new `.gitlab-ci.yml` to this project. -- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. Projects include demonstrations of [multi-project pipelines](https://gitlab.com/gitlab-examples/multi-project-pipelines) and using [Review Apps with a static site served by nginx](https://gitlab.com/gitlab-examples/review-apps-nginx/). +- Repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. Projects include demonstrations of [multi-project pipelines](https://gitlab.com/gitlab-examples/multi-project-pipelines) and using [Review Apps with a static site served by NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx/). - Examples and [other resources](#other-resources) listed below. ## CI/CD examples @@ -59,10 +59,10 @@ Note that older articles and videos may not reflect the state of the latest GitL For examples of setting up GitLab CI/CD for cloud-based environments, see: -- [How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/) +- [How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/blog/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/) - [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) -- [How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/) -- [How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/) +- [How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/) +- [How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/blog/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/) - [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) See also the following video overviews: @@ -74,32 +74,32 @@ See also the following video overviews: For some customer experiences with GitLab CI/CD, see: -- [How Verizon Connect reduced datacenter deploys from 30 days to under 8 hours with GitLab](https://about.gitlab.com/2019/02/14/verizon-customer-story/) -- [How Wag! cut their release process from 40 minutes to just 6](https://about.gitlab.com/2019/01/16/wag-labs-blog-post/) -- [How Jaguar Land Rover embraced CI to speed up their software lifecycle](https://about.gitlab.com/2018/07/23/chris-hill-devops-enterprise-summit-talk/) +- [How Verizon Connect reduced datacenter deploys from 30 days to under 8 hours with GitLab](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) +- [How Wag! cut their release process from 40 minutes to just 6](https://about.gitlab.com/blog/2019/01/16/wag-labs-blog-post/) +- [How Jaguar Land Rover embraced CI to speed up their software lifecycle](https://about.gitlab.com/blog/2018/07/23/chris-hill-devops-enterprise-summit-talk/) ### Getting started For some examples to help get you started, see: -- [GitLab CI/CD's 2018 highlights](https://about.gitlab.com/2019/01/21/gitlab-ci-cd-features-improvements/) -- [A beginner's guide to continuous integration](https://about.gitlab.com/2018/01/22/a-beginners-guide-to-continuous-integration/) +- [GitLab CI/CD's 2018 highlights](https://about.gitlab.com/blog/2019/01/21/gitlab-ci-cd-features-improvements/) +- [A beginner's guide to continuous integration](https://about.gitlab.com/blog/2018/01/22/a-beginners-guide-to-continuous-integration/) ### Implementing GitLab CI/CD For examples of others who have implemented GitLab CI/CD, see: -- [How to streamline interactions between multiple repositories with multi-project pipelines](https://about.gitlab.com/2018/10/31/use-multiproject-pipelines-with-gitlab-cicd/) -- [How we used GitLab CI to build GitLab faster](https://about.gitlab.com/2018/05/02/using-gitlab-ci-to-build-gitlab-faster/) -- [Test all the things in GitLab CI with Docker by example](https://about.gitlab.com/2018/02/05/test-all-the-things-gitlab-ci-docker-examples/) -- [A Craftsman looks at continuous integration](https://about.gitlab.com/2018/01/17/craftsman-looks-at-continuous-integration/) -- [Go tools and GitLab: How to do continuous integration like a boss](https://about.gitlab.com/2017/11/27/go-tools-and-gitlab-how-to-do-continuous-integration-like-a-boss/) -- [GitBot – automating boring Git operations with CI](https://about.gitlab.com/2017/11/02/automating-boring-git-operations-gitlab-ci/) -- [How to use GitLab CI for Vue.js](https://about.gitlab.com/2017/09/12/vuejs-app-gitlab/) +- [How to streamline interactions between multiple repositories with multi-project pipelines](https://about.gitlab.com/blog/2018/10/31/use-multiproject-pipelines-with-gitlab-cicd/) +- [How we used GitLab CI to build GitLab faster](https://about.gitlab.com/blog/2018/05/02/using-gitlab-ci-to-build-gitlab-faster/) +- [Test all the things in GitLab CI with Docker by example](https://about.gitlab.com/blog/2018/02/05/test-all-the-things-gitlab-ci-docker-examples/) +- [A Craftsman looks at continuous integration](https://about.gitlab.com/blog/2018/01/17/craftsman-looks-at-continuous-integration/) +- [Go tools and GitLab: How to do continuous integration like a boss](https://about.gitlab.com/blog/2017/11/27/go-tools-and-gitlab-how-to-do-continuous-integration-like-a-boss/) +- [GitBot – automating boring Git operations with CI](https://about.gitlab.com/blog/2017/11/02/automating-boring-git-operations-gitlab-ci/) +- [How to use GitLab CI for Vue.js](https://about.gitlab.com/blog/2017/09/12/vuejs-app-gitlab/) - Video: [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195) -- [Dockerizing GitLab Review Apps](https://about.gitlab.com/2017/07/11/dockerizing-review-apps/) -- [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/) -- [Demo: CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/) +- [Dockerizing GitLab Review Apps](https://about.gitlab.com/blog/2017/07/11/dockerizing-review-apps/) +- [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/blog/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/) +- [Demo: CI/CD with GitLab in action](https://about.gitlab.com/blog/2017/03/13/ci-cd-demo/) ### Migrating to GitLab from third-party CI tools @@ -109,17 +109,17 @@ For examples of others who have implemented GitLab CI/CD, see: To see how you can integrate GitLab CI/CD with third-party systems, see: -- [Streamline and shorten error remediation with Sentry’s new GitLab integration](https://about.gitlab.com/2019/01/25/sentry-integration-blog-post/) -- [How to simplify your smart home configuration with GitLab CI/CD](https://about.gitlab.com/2018/08/02/using-the-gitlab-ci-slash-cd-for-smart-home-configuration-management/) -- [Demo: GitLab + Jira + Jenkins](https://about.gitlab.com/2018/07/30/gitlab-workflow-with-jira-jenkins/) -- [Introducing Auto Breakfast from GitLab (sort of)](https://about.gitlab.com/2018/06/29/introducing-auto-breakfast-from-gitlab/) +- [Streamline and shorten error remediation with Sentry’s new GitLab integration](https://about.gitlab.com/blog/2019/01/25/sentry-integration-blog-post/) +- [How to simplify your smart home configuration with GitLab CI/CD](https://about.gitlab.com/blog/2018/08/02/using-the-gitlab-ci-slash-cd-for-smart-home-configuration-management/) +- [Demo: GitLab + Jira + Jenkins](https://about.gitlab.com/blog/2018/07/30/gitlab-workflow-with-jira-jenkins/) +- [Introducing Auto Breakfast from GitLab (sort of)](https://about.gitlab.com/blog/2018/06/29/introducing-auto-breakfast-from-gitlab/) ### Mobile development For help with using GitLab CI/CD for mobile application development, see: -- [How to publish Android apps to the Google Play Store with GitLab and fastlane](https://about.gitlab.com/2019/01/28/android-publishing-with-gitlab-and-fastlane/) -- [Setting up GitLab CI for Android projects](https://about.gitlab.com/2018/10/24/setting-up-gitlab-ci-for-android-projects/) -- [Working with YAML in GitLab CI from the Android perspective](https://about.gitlab.com/2017/11/20/working-with-yaml-gitlab-ci-android/) -- [How to use GitLab CI and MacStadium to build your macOS or iOS projects](https://about.gitlab.com/2017/05/15/how-to-use-macstadium-and-gitlab-ci-to-build-your-macos-or-ios-projects/) -- [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) +- [How to publish Android apps to the Google Play Store with GitLab and fastlane](https://about.gitlab.com/blog/2019/01/28/android-publishing-with-gitlab-and-fastlane/) +- [Setting up GitLab CI for Android projects](https://about.gitlab.com/blog/2018/10/24/setting-up-gitlab-ci-for-android-projects/) +- [Working with YAML in GitLab CI from the Android perspective](https://about.gitlab.com/blog/2017/11/20/working-with-yaml-gitlab-ci-android/) +- [How to use GitLab CI and MacStadium to build your macOS or iOS projects](https://about.gitlab.com/blog/2017/05/15/how-to-use-macstadium-and-gitlab-ci-to-build-your-macos-or-ios-projects/) +- [Setting up GitLab CI for iOS projects](https://about.gitlab.com/blog/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md index 1d4c9221cf2..49f4a14c5ac 100644 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md @@ -16,14 +16,14 @@ description: "Continuous Deployment of a Spring Boot application to Cloud Foundr In this article, we'll demonstrate how to deploy a [Spring Boot](https://projects.spring.io/spring-boot/) application to [Cloud Foundry (CF)](https://www.cloudfoundry.org/) with GitLab CI/CD using the [Continuous -Deployment](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-deployment) +Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-deployment) method. All the code for this project can be found in this [GitLab repo](https://gitlab.com/gitlab-examples/spring-gitlab-cf-deploy-demo). In case you're interested in deploying Spring Boot applications to Kubernetes -using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/). +using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/blog/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/). ## Requirements diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 26b10c7eeaf..afe02e0a7d8 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -46,7 +46,7 @@ staging: - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY ``` -In the above example we use Dpl to deploy `my-app-staging` to Heroku server with api-key stored in `HEROKU_STAGING_API_KEY` secure variable. +In the above example we use Dpl to deploy `my-app-staging` to Heroku server with API key stored in `HEROKU_STAGING_API_KEY` secure variable. To use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers). diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 79b3cbd0c69..c9c78c9a4e4 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -46,7 +46,7 @@ All these operations will put all files into a `build` folder, which is ready to You have multiple options: rsync, scp, sftp and so on. For now, we will use scp. -To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitlab.example/your-project-name/variables_). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** ssh key of your server. +To make this work, you need to add a GitLab CI/CD Variable (accessible on `gitlab.example/your-project-name/variables`). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** SSH key of your server. ### Security tip @@ -98,7 +98,7 @@ Here's the breakdown: 1. We will connect via `ssh` and create a new `_tmp` folder 1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder 1. We will connect again via `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`. -1. We connect to ssh and remove the `_old` folder +1. We connect to SSH and remove the `_old` folder What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed). diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index 44d3ec8046c..e1c59f3b025 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -22,7 +22,7 @@ and the basics of game development. Our [demo game](http://gitlab-game-demo.s3-website-us-east-1.amazonaws.com/) consists of a simple spaceship traveling in space that shoots by clicking the mouse in a given direction. -Creating a strong CI/CD pipeline at the beginning of developing another game, [Dark Nova](http://darknova.io/), +Creating a strong CI/CD pipeline at the beginning of developing another game, [Dark Nova](https://www.darknova.io), was essential for the fast pace the team worked at. This tutorial will build upon my [previous introductory article](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) and go through the following steps: @@ -254,7 +254,7 @@ pipeline to include running the tests along with the existing build job. To ensure our changes don't break the build and all tests still pass, we utilize Continuous Integration (CI) to run these checks automatically for every push. -Read through this article to understand [Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), +Read through this article to understand [Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), and how these methods are leveraged by GitLab. From the [last tutorial](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) we already have a `.gitlab-ci.yml` file set up for building our app from every push. We need to set up a new CI job for testing, which GitLab CI/CD will run after the build job using our generated artifacts from gulp. @@ -390,7 +390,7 @@ We have our codebase built and tested on every push. To complete the full pipeli let's set up [free web hosting with AWS S3](https://aws.amazon.com/s/dm/optimization/server-side-test/free-tier/free_np/) and a job through which our build artifacts get deployed. GitLab also has a free static site hosting service we could use, [GitLab Pages](https://about.gitlab.com/product/pages/), however Dark Nova specifically uses other AWS tools that necessitates using `AWS S3`. -Read through this article that describes [deploying to both S3 and GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) +Read through this article that describes [deploying to both S3 and GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) and further delves into the principles of GitLab CI/CD than discussed in this article. ### Set up S3 Bucket @@ -509,7 +509,7 @@ deploy: Within the [demo repository](https://gitlab.com/blitzgren/gitlab-game-demo) you can also find a handful of boilerplate code to get [Typescript](https://www.typescriptlang.org/), [Mocha](https://mochajs.org/), [Gulp](https://gulpjs.com/) and [Phaser](https://phaser.io) all playing -together nicely with GitLab CI/CD, which is the result of lessons learned while making [Dark Nova](http://darknova.io/). +together nicely with GitLab CI/CD, which is the result of lessons learned while making [Dark Nova](https://www.darknova.io). Using a combination of free and open source software, we have a full CI/CD pipeline, a game foundation, and unit tests, all running and deployed at every push to master - with shockingly little code. Errors can be easily debugged through GitLab's build logs, and within minutes of a successful commit, @@ -527,6 +527,6 @@ Here are some ideas to further investigate that can speed up or improve your pip - [Yarn](https://yarnpkg.com) instead of npm - Set up a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) image that can preload dependencies and tools (like AWS CLI) -- Forward a [custom domain](https:/docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) to your game's S3 static website +- Forward a [custom domain](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) to your game's S3 static website - Combine jobs if you find it unnecessary for a small project -- Avoid the queues and set up your own [custom GitLab CI/CD runner](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) +- Avoid the queues and set up your own [custom GitLab CI/CD runner](https://about.gitlab.com/blog/2016/03/01/gitlab-runner-with-docker/) diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 38d0d86ffa2..17fb6f9a7c9 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -28,7 +28,7 @@ layers of your application, from the frontend to the database. In this article, we will discuss how to write such end-to-end tests, and how to set up GitLab CI/CD to automatically run these tests against your new code, on a branch-by-branch basis. For the scope of this article, we will walk you -through the process of setting up GitLab CI/CD for end-to-end testing Javascript-based applications +through the process of setting up GitLab CI/CD for end-to-end testing JavaScript-based applications with WebdriverIO, but the general strategy should carry over to other languages. We assume you are familiar with GitLab, [GitLab CI/CD](../../README.md), [Review Apps](../../review_apps/index.md), and running your app locally, e.g., on `localhost:8000`. @@ -47,14 +47,14 @@ infrastructure is up and running, and that your units of code work well together [Selenium](http://www.seleniumhq.org/) is a piece of software that can control web browsers, e.g., to make them visit a specific URL or interact with elements on the page. It can be programmatically controlled from a variety of programming languages. In this article we're going to be using the -[WebdriverIO](http://webdriver.io/) Javascript bindings, but the general concept should carry over +[WebdriverIO](https://webdriver.io/) JavaScript bindings, but the general concept should carry over pretty well to [other programming languages supported by Selenium](http://docs.seleniumhq.org/about/platforms.jsp#programming-languages). ## Writing tests You can write tests using -[several testing frameworks supported by WebdriverIO](http://webdriver.io/guide/testrunner/frameworks.html). +[several testing frameworks supported by WebdriverIO](https://webdriver.io/guide/testrunner/frameworks.html). We will be using [Jasmine](https://jasmine.github.io/) here: ```javascript @@ -79,14 +79,14 @@ multiple tests, such as making sure you are logged in. The function `it` defines an individual test. -[The `browser` object](http://webdriver.io/guide/testrunner/browserobject.html) is WebdriverIO's -special sauce. It provides most of [the WebdriverIO API methods](http://webdriver.io/api.html) that are the key to +[The `browser` object](https://webdriver.io/guide/testrunner/browserobject.html) is WebdriverIO's +special sauce. It provides most of [the WebdriverIO API methods](https://webdriver.io/api.html) that are the key to steering the browser. In this case, we can use -[`browser.url`](http://webdriver.io/api/protocol/url.html) to visit `/page-that-does-not-exist` to -hit our 404 page. We can then use [`browser.getUrl`](http://webdriver.io/api/property/getUrl.html) +[`browser.url`](https://webdriver.io/api/protocol/url.html) to visit `/page-that-does-not-exist` to +hit our 404 page. We can then use [`browser.getUrl`](https://webdriver.io/api/property/getUrl.html) to verify that the current page is indeed at the location we specified. To interact with the page, we can simply pass CSS selectors to -[`browser.element`](http://webdriver.io/api/protocol/element.html) to get access to elements on the +[`browser.element`](https://webdriver.io/api/protocol/element.html) to get access to elements on the page and to interact with them - for example, to click on the link back to the home page. The simple test shown above @@ -107,9 +107,9 @@ you can use [the Webpack Dev Server WebdriverIO plugin](https://www.npmjs.com/pa that automatically starts a development server before executing the tests. The WebdriverIO documentation has -[an overview of all configuration options](http://webdriver.io/guide/getstarted/configuration.html), but the +[an overview of all configuration options](https://webdriver.io/guide/getstarted/configuration.html), but the easiest way to get started is to start with -[WebdriverIO's default configuration](http://webdriver.io/guide/testrunner/configurationfile.html), which +[WebdriverIO's default configuration](https://webdriver.io/guide/testrunner/configurationfile.html), which provides an overview of all available options. The two options that are going to be most relevant now are the `specs` option, which is an array of paths to your tests, and the `baseUrl` option, which points to where your app is running. And finally, we will need to tell WebdriverIO in which browsers we would like to run our @@ -182,7 +182,7 @@ e2e:chrome: Now that we have a job to run the end-to-end tests in, we need to tell WebdriverIO how to connect to the Selenium servers running alongside it. We've already cheated a bit above by -passing the value of the [`host`](http://webdriver.io/guide/getstarted/configuration.html#host) +passing the value of the [`host`](https://webdriver.io/guide/getstarted/configuration.html#host) option as an argument to `npm run confidence-check` on the command line. However, we still need to tell WebdriverIO which browser is available for it to use. @@ -248,7 +248,7 @@ production project, see: - [Flockademic's `.gitlab-ci.yml`](https://gitlab.com/Flockademic/Flockademic/blob/dev/.gitlab-ci.yml) - [Flockademic's tests](https://gitlab.com/Flockademic/Flockademic/tree/dev/__e2e__) -There's plenty more that WebdriverIO can do. For example, you can configure a [`screenshotPath`](http://webdriver.io/guide/getstarted/configuration.html#screenshotPath) to tell WebdriverIO to take +There's plenty more that WebdriverIO can do. For example, you can configure a [`screenshotPath`](https://webdriver.io/guide/getstarted/configuration.html#screenshotPath) to tell WebdriverIO to take a screenshot when tests are failing. Then tell GitLab CI/CD to store those [artifacts](../../yaml/README.md#artifacts), and you'll be able to see what went wrong within GitLab. diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index d79821ff258..a7ed4ca3514 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -15,7 +15,7 @@ last_updated: 2019-03-06 GitLab features our applications with Continuous Integration, and it is possible to easily deploy the new code changes to the production server whenever we want. -In this tutorial, we'll show you how to initialize a [Laravel](http://laravel.com/) application and set up our [Envoy](https://laravel.com/docs/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). +In this tutorial, we'll show you how to initialize a [Laravel](https://laravel.com) application and set up our [Envoy](https://laravel.com/docs/master/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). We assume you have a basic experience with Laravel, Linux servers, and you know how to use GitLab. @@ -25,11 +25,11 @@ It has a great community with a [fantastic documentation](https://laravel.com/do Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication and many others. We will use [Envoy](https://laravel.com/docs/master/envoy) as an SSH task runner based on PHP. -It uses a clean, minimal [Blade syntax](https://laravel.com/docs/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/artisan). +It uses a clean, minimal [Blade syntax](https://laravel.com/docs/master/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/master/artisan). ## Initialize our Laravel app on GitLab -We assume [you have installed a new laravel project](https://laravel.com/docs/installation#installation), so let's start with a unit test, and initialize Git for the project. +We assume [you have installed a new laravel project](https://laravel.com/docs/master/installation#installation), so let's start with a unit test, and initialize Git for the project. ### Unit Test @@ -82,12 +82,12 @@ git push -u origin master ## Configure the production server Before we begin setting up Envoy and GitLab CI/CD, let's quickly make sure the production server is ready for deployment. -We have installed LEMP stack which stands for Linux, Nginx, MySQL and PHP on our Ubuntu 16.04. +We have installed LEMP stack which stands for Linux, NGINX, MySQL and PHP on our Ubuntu 16.04. ### Create a new user Let's now create a new user that will be used to deploy our website and give it -the needed permissions using [Linux ACL](https://serversforhackers.com/video/linux-acls): +the needed permissions using [Linux ACL](https://serversforhackers.com/c/linux-acls): ```bash # Create user deployer @@ -151,11 +151,11 @@ git clone git@gitlab.example.com:<USERNAME>/laravel-sample.git Answer **yes** if asked `Are you sure you want to continue connecting (yes/no)?`. It adds GitLab.com to the known hosts. -### Configuring Nginx +### Configuring NGINX Now, let's make sure our web server configuration points to the `current/public` rather than `public`. -Open the default Nginx server block configuration file by typing: +Open the default NGINX server block configuration file by typing: ```bash sudo nano /etc/nginx/sites-available/default @@ -179,7 +179,7 @@ You may replace the app's name in `/var/www/app/current/public` with the folder So we have our Laravel app ready for production. The next thing is to use Envoy to perform the deploy. -To use Envoy, we should first install it on our local machine [using the given instructions by Laravel](https://laravel.com/docs/envoy/#introduction). +To use Envoy, we should first install it on our local machine [using the given instructions by Laravel](https://laravel.com/docs/master/envoy/#introduction). ### How Envoy works @@ -216,7 +216,7 @@ Our deployment plan is to clone the latest release from GitLab repository, insta #### @setup directive -The first step of our deployment process is to define a set of variables within [@setup](https://laravel.com/docs/envoy/#setup) directive. +The first step of our deployment process is to define a set of variables within [@setup](https://laravel.com/docs/master/envoy/#setup) directive. You may change the `app` to your application's name: ```php @@ -241,7 +241,7 @@ You may change the `app` to your application's name: #### @story directive -The [@story](https://laravel.com/docs/envoy/#stories) directive allows us define a list of tasks that can be run as a single task. +The [@story](https://laravel.com/docs/master/envoy/#stories) directive allows us define a list of tasks that can be run as a single task. Here we have three tasks called `clone_repository`, `run_composer`, `update_symlinks`. These variables are usable to making our task's codes more cleaner: ```php @@ -391,10 +391,10 @@ git push origin master ## Continuous Integration with GitLab We have our app ready on GitLab, and we also can deploy it manually. -But let's take a step forward to do it automatically with [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) method. +But let's take a step forward to do it automatically with [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) method. We need to check every commit with a set of automated tests to become aware of issues at the earliest, and then, we can deploy to the target environment if we are happy with the result of the tests. -[GitLab CI/CD](../../README.md) allows us to use [Docker](https://docker.com/) engine to handle the process of testing and deploying our app. +[GitLab CI/CD](../../README.md) allows us to use [Docker](https://www.docker.com) engine to handle the process of testing and deploying our app. In the case you're not familiar with Docker, refer to [How to Automate Docker Deployments](http://paislee.io/how-to-automate-docker-deployments/). To be able to build, test, and deploy our app with GitLab CI/CD, we need to prepare our work environment. @@ -431,7 +431,7 @@ RUN curl --silent --show-error https://getcomposer.org/installer | php -- --inst RUN composer global require "laravel/envoy=~1.0" ``` -We added the [official PHP 7.1 Docker image](https://hub.docker.com/r/_/php/), which consist of a minimum installation of Debian Jessie with PHP pre-installed, and works perfectly for our use case. +We added the [official PHP 7.1 Docker image](https://hub.docker.com/_/php), which consist of a minimum installation of Debian Jessie with PHP pre-installed, and works perfectly for our use case. We used `docker-php-ext-install` (provided by the official PHP Docker image) to install the PHP extensions we need. @@ -469,7 +469,7 @@ Congratulations! You just pushed the first Docker image to the GitLab Registry,  >**Note:** -You can also [use GitLab CI/CD](https://about.gitlab.com/2016/05/23/gitlab-container-registry/#use-with-gitlab-ci) to build and push your Docker images, rather than doing that on your machine. +You can also [use GitLab CI/CD](https://about.gitlab.com/blog/2016/05/23/gitlab-container-registry/#use-with-gitlab-ci) to build and push your Docker images, rather than doing that on your machine. We'll use this image further down in the `.gitlab-ci.yml` configuration file to handle the process of testing and deploying our app. @@ -557,7 +557,7 @@ GitLab CI/CD allows us to use [environment variables](../../yaml/README.md#varia We defined MySQL as our database management system, which comes with a superuser root created by default. So we should adjust the configuration of MySQL instance by defining `MYSQL_DATABASE` variable as our database name and `MYSQL_ROOT_PASSWORD` variable as the password of `root`. -Find out more about MySQL variables at the [official MySQL Docker Image](https://hub.docker.com/r/_/mysql/). +Find out more about MySQL variables at the [official MySQL Docker Image](https://hub.docker.com/_/mysql). Also set the variables `DB_HOST` to `mysql` and `DB_USERNAME` to `root`, which are Laravel specific variables. We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md#how-services-are-linked-to-the-job). @@ -605,7 +605,7 @@ The job `deploy_production` will deploy the app to the production server. To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md#ssh-keys-when-using-the-docker-executor). If the SSH keys have added successfully, we can run Envoy. -As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well. +As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well. The [environment](../../yaml/README.md#environment) keyword tells GitLab that this job deploys to the `production` environment. The `url` keyword is used to generate a link to our application on the GitLab Environments page. The `only` keyword tells GitLab CI that the job should be executed only when the pipeline is building the `master` branch. @@ -634,7 +634,7 @@ deploy_production: - master ``` -You may also want to add another job for [staging environment](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments), to final test your application before deploying to production. +You may also want to add another job for [staging environment](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/), to final test your application before deploying to production. ### Turn on GitLab CI/CD diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index f9d185f187c..34d53f67adc 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -72,7 +72,7 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/). First install [Docker Engine](https://docs.docker.com/installation/). -To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner). +To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner/index.html). You can use public runners available on `gitlab.com` or you can register your own: ```sh @@ -86,6 +86,6 @@ gitlab-runner register \ --docker-postgres latest ``` -With the command above, you create a runner that uses the [python:3.5](https://hub.docker.com/r/_/python/) image and uses a [postgres](https://hub.docker.com/r/_/postgres/) database. +With the command above, you create a runner that uses the [`python:3.5`](https://hub.docker.com/_/python) image and uses a [PostgreSQL](https://hub.docker.com/_/postgres) database. To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password. diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 79d54b52b5a..9a4fbfcce6d 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -77,6 +77,6 @@ gitlab-runner register \ --docker-postgres latest ``` -With the command above, you create a Runner that uses the [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses a [postgres](https://hub.docker.com/r/_/postgres/) database. +With the command above, you create a Runner that uses the [ruby:2.2](https://hub.docker.com/_/ruby) image and uses a [postgres](https://hub.docker.com/_/postgres) database. To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index 0e595e1a0be..a81568d6cd4 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -205,7 +205,7 @@ when running our Phoenix in our `localhost`. As our project is still fresh, we don't have any data on our database, so, the `migrations` directory will be empty. - Without `.gitkeep`, git will not upload this empty directory and we'll got an error when running our + Without `.gitkeep`, Git will not upload this empty directory and we'll got an error when running our test on GitLab. > **Note:** If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir. @@ -412,8 +412,8 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams [mix-ecto]: https://hexdocs.pm/ecto/Mix.Tasks.Ecto.Create.html "mix and Ecto" [iex]: https://elixir-lang.org/getting-started/introduction.html#interactive-mode "Interactive Mode" [ci-lint]: https://gitlab.com/ci/lint "CI Lint Tool" -[ci-reasons]: https://about.gitlab.com/2015/02/03/7-reasons-why-you-should-be-using-ci/ "7 Reasons Why You Should Be Using CI" -[ci-guide]: https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/ "Getting Started With GitLab And GitLab CI/CD" +[ci-reasons]: https://about.gitlab.com/blog/2015/02/03/7-reasons-why-you-should-be-using-ci/ "7 Reasons Why You Should Be Using CI" +[ci-guide]: https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/ "Getting Started With GitLab And GitLab CI/CD" [ci-docs]: ../../README.md "GitLab CI/CD Documentation" [skipping-jobs]: ../../yaml/README.md#skipping-jobs "Skipping Jobs" [gitlab-runners]: ../../runners/README.md "GitLab Runners Documentation" diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index c1d4f784ddd..361e526ed96 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -30,7 +30,7 @@ Two things need to be configured for the interactive web terminal to work: NOTE: **Note:** Interactive web terminals are not yet supported by -[`gitlab-runner` helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-runner/index.html), +[`gitlab-runner` Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-runner/index.html), but support [is planned](https://gitlab.com/gitlab-org/charts/gitlab-runner/issues/79). ## Debugging a running job diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index 4389b2ce015..a644a89eee4 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -190,6 +190,7 @@ according to each stage (Verify, Package, Release). - Store Docker images with [Container Registry](../../user/packages/container_registry/index.md). - Store NPM packages with [NPM Registry](../../user/packages/npm_registry/index.md). **(PREMIUM)** - Store Maven artifacts with [Maven Repository](../../user/packages/maven_repository/index.md). **(PREMIUM)** + - Store Conan packages with [Conan Repository](../../user/packages/conan_repository/index.md). **(PREMIUM)** 1. **Release**: - Continuous Deployment, automatically deploying your app to production. - Continuous Delivery, manually click to deploy your app to production. diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 2c3bdcf30d6..321d0d2778f 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -202,7 +202,7 @@ can provide any variables they like. #### `triggers` / `cron` -Because GitLab is integrated tightly with git, SCM polling options for triggers are not needed. We support an easy to use +Because GitLab is integrated tightly with Git, SCM polling options for triggers are not needed. We support an easy to use [syntax for scheduling pipelines](../../user/project/pipelines/schedules.md). #### `tools` diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index b1359537fca..ce998502b69 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -111,7 +111,7 @@ machines, and have an existing worktree that you can re-use for builds. For exact parameters accepted by [`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags), see the documentation -for [git clean](https://git-scm.com/docs/git-clean). The available parameters +for [`git clean`](https://git-scm.com/docs/git-clean). The available parameters are dependent on Git version. ## Fork-based workflow diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index e29a13e87af..a49279f1932 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -151,13 +151,13 @@ parent project. This means you cannot completely trust the pipeline result, because, technically, external contributors can disguise their pipeline results by tweaking their GitLab Runner in the forked project. -There are multiple reasons about why GitLab doesn't allow those pipelines to be +There are multiple reasons why GitLab doesn't allow those pipelines to be created in the parent project, but one of the biggest reasons is security concern. External users could steal secret variables from the parent project by modifying `.gitlab-ci.yml`, which could be some sort of credentials. This should not happen. We're discussing a secure solution of running pipelines for merge requests -that submitted from forked projects, +that are submitted from forked projects, see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-foss/issues/23902). ## Additional predefined variables diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png Binary files differdeleted file mode 100644 index 6d4b66824e1..00000000000 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png +++ /dev/null diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png Binary files differnew file mode 100644 index 00000000000..6f0752bb940 --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index e1c5848af03..3a0848fcd08 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -20,7 +20,7 @@ GitLab can run pipelines for merge requests on this merged result. That is, where the source and target branches are combined into a new ref and a pipeline for this ref validates the result prior to merging. - + There are some cases where creating a combined ref is not possible or not wanted. For example, a source branch that has conflicts with the target branch @@ -93,6 +93,17 @@ To check these feature flag values, please ask administrator to execute the foll > Feature.enable(:ci_use_merge_request_ref) # Enable the feature flag. ``` +### Intermittently pipelines fail by `fatal: reference is not a tree:` error + +Since pipelines for merged results are a run on a merge ref of a merge request +(`refs/merge-requests/<iid>/merge`), the git-reference could be overwritten at an +unexpected timing, for example, when a source or target branch is advanced. +In this case, the pipeline fails because of `fatal: reference is not a tree:` error, +which indicates that the checkout-SHA is not found in the merge ref. + +This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines.md#persistent-pipeline-refs). +You should be able to create pipelines at any timings without concerning the error. + ## Using Merge Trains **(PREMIUM)** By enabling [Pipelines for merged results](#pipelines-for-merged-results-premium), diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index 767058376ca..f2a7902c9ca 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -122,6 +122,12 @@ is unavailable when Follow [this issue](https://gitlab.com/gitlab-org/gitlab/issues/12267) to track progress on this issue. +### Merge Train Pipeline cannot be retried + +A Merge Train pipeline cannot be retried because the merge request is dropped from the merge train upon failure. For this reason, the retry button does not appear next to the pipeline icon. + +In the case of pipeline failure, you should [re-enqueue](#how-to-add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline. + ### Merge Train disturbs your workflow First of all, please check if [merge immediately](#immediately-merge-a-merge-request-with-a-merge-train) diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 8ae38db5c96..093d334e937 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -5,7 +5,7 @@ type: reference # Multi-project pipelines **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2121) in -[GitLab Premium 9.3](https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs). +[GitLab Premium 9.3](https://about.gitlab.com/blog/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs). When you set up [GitLab CI/CD](README.md) across multiple projects, you can visualize the entire pipeline, including all cross-project inter-dependencies. @@ -24,7 +24,7 @@ and when hovering or tapping (on touchscreen devices) they will expand and be sh  Multi-project pipelines are useful for larger products that require cross-project inter-dependencies, such as those -adopting a [microservices architecture](https://about.gitlab.com/2016/08/16/trends-in-version-control-land-microservices/). +adopting a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). For a demonstration of how cross-functional development teams can use cross-pipeline triggering to trigger multiple pipelines for different microservices projects, see @@ -115,8 +115,12 @@ staging: branch: stable-11-2 ``` -Use a `project` keyword to specify full path to a downstream project. Use -a `branch` keyword to specify a branch name. +Use: + +- The `project` keyword to specify the full path to a downstream project. +- The `branch` keyword to specify the name of a branch in the project specified by `project`. + [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/10126), variable expansion is + supported. GitLab will use a commit that is currently on the HEAD of the branch when creating a downstream pipeline. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index de9bac76281..e5f2701c6ae 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -204,7 +204,7 @@ the following (you can even use them interchangeably): - A colon (`:`). NOTE: **Note:** -More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab-foss/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`. +More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`. #### How grouping works @@ -283,11 +283,11 @@ You can also access pipelines for a merge request by navigating to its **Pipelin When you access a pipeline, you can see the related jobs for that pipeline. -Clicking on an individual job will show you its job trace, and allow you to: +Clicking on an individual job will show you its job log, and allow you to: - Cancel the job. - Retry the job. -- Erase the job trace. +- Erase the job log. ### Seeing the failure reason for jobs @@ -379,6 +379,8 @@ This functionality is only available: ## Most Recent Pipeline +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3. + There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch. ## Security on protected branches @@ -405,3 +407,32 @@ branches, avoiding untrusted code to be executed on the protected runner and preserving deployment keys and other credentials from being unintentionally accessed. In order to ensure that jobs intended to be executed on protected runners will not use regular runners, they must be tagged accordingly. + +## Persistent pipeline refs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17043) in GitLab 12.4. + +Previously, you'd have encountered unexpected pipeline failures when you force-pushed +a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow: + +1. A user creates a feature branch named `example` and pushes it to a remote repository. +1. A new pipeline starts running on the `example` branch. +1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository. +1. A new pipeline starts running on the `example` branch again, however, + the previous pipeline (2) fails because of `fatal: reference is not a tree:` error. + +This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record) +from the `example` branch that the commit history has already been overwritten by the force-push. +Similarly, [Pipelines for merged results](merge_request_pipelines/pipelines_for_merged_results/index.md) +might have failed intermittently due to [the same reason](merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error). + +As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively. +To illustrate its life cycle: + +1. A pipeline is created on a feature branch named `example`. +1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`, + which retains the checkout-SHA of the associated pipeline record. + This persistent ref stays intact during the pipeline execution, + even if the commit history of the `example` branch has been overwritten by force-push. +1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA. +1. When the pipeline finished, its persistent ref is cleaned up in a background process. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 0822b01d553..10a898be900 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -22,7 +22,7 @@ GitLab offers a [continuous integration][ci] service. If you and configure your GitLab project to use a [Runner], then each commit or push triggers your CI [pipeline]. -The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs +The `.gitlab-ci.yml` file tells the GitLab Runner what to do. By default it runs a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to use all three stages; stages with no jobs are simply ignored. @@ -126,7 +126,7 @@ a "CI Lint" button to go to this page under **CI/CD ➔ Pipelines** and **Pipelines ➔ Jobs** in your project. For more information and a complete `.gitlab-ci.yml` syntax, please read -[the reference documentation on .gitlab-ci.yml](../yaml/README.md). +[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md). ### Push `.gitlab-ci.yml` to GitLab @@ -235,7 +235,7 @@ Visit the [examples README][examples] to see a list of examples using GitLab CI with various languages. [runner-install]: https://docs.gitlab.com/runner/install/ -[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ +[blog-ci]: https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ [examples]: ../examples/README.md [ci]: https://about.gitlab.com/product/continuous-integration/ [yaml]: ../yaml/README.md diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 7a1e6e4e1b8..da92fadafc4 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -24,8 +24,8 @@ In the above example: - A Review App is built every time a commit is pushed to `topic branch`. - The reviewer fails two reviews before passing the third review. -- Once the review as passed, `topic branch` is merged into `master` where it's deploy to staging. -- After been approved in staging, the changes that were merged into `master` are deployed in to production. +- Once the review has passed, `topic branch` is merged into `master` where it is deployed to staging. +- After having been approved in staging, the changes that were merged into `master` are deployed in to production. ## How Review Apps work diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index f7d1a3e88a2..4011ae4df70 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -365,8 +365,8 @@ We're always looking for contributions that can mitigate these ### Resetting the registration token for a Project If you think that registration token for a Project was revealed, you should -reset them. It's recommended because such token can be used to register another -Runner to the Project. It may be next used to obtain the values of secret +reset them. It's recommended because such a token can be used to register another +Runner to the Project. It may then be used to obtain the values of secret variables or clone the project code, that normally may be unavailable for the attacker. @@ -379,10 +379,10 @@ To reset the token: 1. After the page is refreshed, expand the **Runners settings** section and check the registration token - it should be changed. -From now on the old token is not valid anymore and will not allow to register -a new Runner to the project. If you are using any tools to provision and -register new Runners, you should now update the token that is used to the -new value. +From now on the old token is no longer valid and will not register +any new Runners to the project. If you are using any tools to provision and +register new Runners, the tokens used in those tools should be updated to reflect the +value of the new token. ## Determining the IP address of a Runner diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index 8b227154b06..ccb92fa94d7 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -30,7 +30,7 @@ Host: redis And that's it. Redis will now be available to be used within your testing framework. -You can also use any other docker image available on [Docker Hub][hub-redis]. +You can also use any other docker image available on [Docker Hub](https://hub.docker.com/_/redis). For example, to use Redis 2.8 the service becomes `redis:2.8`. ## Use Redis with the Shell executor @@ -62,12 +62,9 @@ Host: localhost ## Example project -We have set up an [Example Redis Project][redis-example-repo] for your convenience +We have set up an [Example Redis Project](https://gitlab.com/gitlab-examples/redis) for your convenience that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few moments the changes will be picked by a public runner and the job will begin. - -[hub-redis]: https://hub.docker.com/r/_/redis/ -[redis-example-repo]: https://gitlab.com/gitlab-examples/redis diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index b6aebd3bd78..bee1501aed8 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -25,18 +25,18 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) ## How it works -1. Create a new SSH key pair locally with [ssh-keygen](http://linux.die.net/man/1/ssh-keygen) +1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) 1. Add the private key as a [variable](../variables/README.md) to your project -1. Run the [ssh-agent](http://linux.die.net/man/1/ssh-agent) during job to load +1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load the private key. 1. Copy the public key to the servers you want to have access to (usually in `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) if you are accessing a private GitLab repository. NOTE: **Note:** -The private key will not be displayed in the job trace, unless you enable -[debug tracing](../variables/README.md#debug-tracing). You might also want to +The private key will not be displayed in the job log, unless you enable +[debug logging](../variables/README.md#debug-logging). You might also want to check the [visibility of your pipelines](../../user/project/pipelines/settings.md#visibility-of-pipelines). ## SSH keys when using the Docker executor diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index d2efae8ebef..82cbd40c4c6 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -6,7 +6,7 @@ type: tutorial > **Notes**: > -> - [Introduced](https://about.gitlab.com/2015/08/22/gitlab-7-14-released/) in GitLab 7.14. +> - [Introduced](https://about.gitlab.com/blog/2015/08/22/gitlab-7-14-released/) in GitLab 7.14. > - GitLab 8.12 has a completely redesigned job permissions system. Read all > about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#pipeline-triggers). @@ -157,7 +157,7 @@ curl --request POST \ You can also benefit by using triggers in your `.gitlab-ci.yml`. Let's say that you have two projects, A and B, and you want to trigger a rebuild on the `master` branch of project B whenever a tag on project A is created. This is the job you -need to add in project's A `.gitlab-ci.yml`: +need to add in project A's `.gitlab-ci.yml`: ```yaml build_docs: diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 5e871ec7958..5d86d382aa8 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,5 +1,4 @@ --- -table_display_block: true type: reference --- @@ -263,12 +262,13 @@ export CI_JOB_TOKEN="abcde-1234ABCD5678ef" export CI_PIPELINE_ID="1000" export CI_PIPELINE_IID="10" export CI_PAGES_DOMAIN="gitlab.io" -export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-ce" +export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-foss" export CI_PROJECT_ID="34" export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-foss" -export CI_PROJECT_NAME="gitlab-ce" +export CI_PROJECT_NAME="gitlab-foss" +export CI_PROJECT_TITLE="GitLab FOSS" export CI_PROJECT_NAMESPACE="gitlab-org" -export CI_PROJECT_PATH="gitlab-org/gitlab-ce" +export CI_PROJECT_PATH="gitlab-org/gitlab-foss" export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-foss" export CI_REGISTRY="registry.example.com" export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-foss" @@ -568,7 +568,7 @@ Below you can find supported syntax reference: Precedence of operators follows standard Ruby 2.5 operation [precedence](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html). -## Debug tracing +## Debug logging > Introduced in GitLab Runner 1.7. @@ -576,24 +576,24 @@ CAUTION: **Warning:** Enabling debug tracing can have severe security implications. The output **will** contain the content of all your variables and any other secrets! The output **will** be uploaded to the GitLab server and made visible -in job traces! +in job logs! By default, GitLab Runner hides most of the details of what it is doing when -processing a job. This behavior keeps job traces short, and prevents secrets -from being leaked into the trace unless your script writes them to the screen. +processing a job. This behavior keeps job logs short, and prevents secrets +from being leaked into the log unless your script writes them to the screen. If a job isn't working as expected, this can make the problem difficult to investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`. Available on GitLab Runner v1.7+, this feature enables the shell's execution -trace, resulting in a verbose job trace listing all commands that were run, +log, resulting in a verbose job log listing all commands that were run, variables that were set, etc. Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should -also [erase](../pipelines.md#accessing-individual-jobs) all generated job traces +also [erase](../pipelines.md#accessing-individual-jobs) all generated job logs before making them visible again. -To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`: +To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`: ```yaml job_name: @@ -601,7 +601,7 @@ job_name: CI_DEBUG_TRACE: "true" ``` -Example truncated output with debug trace set to true: +Example truncated output with `CI_DEBUG_TRACE` set to `true`: ```bash ... @@ -708,6 +708,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_PROJECT_ID=17893 ++ export CI_PROJECT_NAME=ci-debug-trace ++ CI_PROJECT_NAME=ci-debug-trace +++ export 'CI_PROJECT_TITLE="GitLab FOSS' +++ CI_PROJECT_TITLE='GitLab FOSS' ++ export CI_PROJECT_PATH=gitlab-examples/ci-debug-trace ++ CI_PROJECT_PATH=gitlab-examples/ci-debug-trace ++ export CI_PROJECT_NAMESPACE=gitlab-examples diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index e3ff3385f97..20e70d212b0 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -40,13 +40,14 @@ future GitLab releases.** | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit - the full first line of the message | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | -| `CI_DEBUG_TRACE` | all | 1.7 | Whether [debug tracing](README.md#debug-tracing) is enabled | +| `CI_DEBUG_TRACE` | all | 1.7 | Whether [debug logging (tracing)](README.md#debug-logging) is enabled | | `CI_DEPLOY_PASSWORD` | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | `CI_DEPLOY_USER` | 10.8 | all | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | | `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. | | `CI_ENVIRONMENT_SLUG` | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. | | `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Only present if [`environment:url`](../yaml/README.md#environmenturl) is set. | +| `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the default branch for the project. | | `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` | @@ -60,12 +61,12 @@ future GitLab releases.** | `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)** | | `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | -| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)** | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | @@ -87,7 +88,8 @@ future GitLab releases.** | `CI_PIPELINE_URL` | 11.1 | 0.5 | Pipeline details URL | | `CI_PROJECT_DIR` | all | all | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. | | `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 (actually it is project folder name) | +| `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project that is currently being built. For example, if the project URL is `gitlab.example.com/group-name/project-1`, the `CI_PROJECT_NAME` would be `project-1`. | +| `CI_PROJECT_TITLE` | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | | `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. | @@ -108,7 +110,7 @@ future GitLab releases.** | `CI_RUNNER_VERSION` | all | 10.6 | GitLab Runner version that is executing the current job | | `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of GitLab Runner's token used to authenticate new job requests. Used as Runner's unique ID | | `CI_SERVER` | all | all | Mark that job is executed in CI environment | -| `CI_SERVER_HOST` | 12.1 | all | Host component of the GitLab instance URL, without protocol and port (like gitlab.example.com) | +| `CI_SERVER_HOST` | 12.1 | all | Host component of the GitLab instance URL, without protocol and port (like `gitlab.example.com`) | | `CI_SERVER_NAME` | all | all | The name of CI server that is used to coordinate jobs | | `CI_SERVER_REVISION` | all | all | GitLab revision that is used to schedule jobs | | `CI_SERVER_VERSION` | all | all | GitLab version that is used to schedule jobs | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 5c747688bb1..4569e9ff9b6 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -20,7 +20,7 @@ We have complete examples of configuring pipelines: - For a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md). - For a collection of examples, see [GitLab CI/CD Examples](../examples/README.md). -- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab-ce`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/.gitlab-ci.yml). +- To see a large `.gitlab-ci.yml` file used in an enterprise, see the [`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml). NOTE: **Note:** If you have a [mirrored repository where GitLab pulls from](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), @@ -56,7 +56,7 @@ Jobs are picked up by [Runners](../runners/README.md) and executed within the environment of the Runner. What is important, is that each job is run independently from each other. -### Validate the .gitlab-ci.yml +### Validate the `.gitlab-ci.yml` Each instance of GitLab CI has an embedded debug tool called Lint, which validates the content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your @@ -107,17 +107,17 @@ The following table lists available parameters for jobs: | [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, and `environment:action`. | | [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, and `cache:policy`. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, and `artifacts:reports:junit`.<br><br>In GitLab [Enterprise Edition](https://about.gitlab.com/pricing/), these are available: `artifacts:reports:codequality`, `artifacts:reports:sast`, `artifacts:reports:dependency_scanning`, `artifacts:reports:container_scanning`, `artifacts:reports:dast`, `artifacts:reports:license_management`, `artifacts:reports:performance` and `artifacts:reports:metrics`. | -| [`dependencies`](#dependencies) | Other jobs that a job depends on so that you can pass artifacts between them. | +| [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`coverage`](#coverage) | Code coverage settings for a given job. | | [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. | -| [`timeout`](#timeout) | Define a custom timeout that would take precedence over the project-wide one. | +| [`timeout`](#timeout) | Define a custom job-level timeout that takes precedence over the project-wide setting. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`trigger`](#trigger-premium) | Defines a downstream pipeline trigger. | | [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | | [`extends`](#extends) | Configuration entries that this job is going to inherit from. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`variables`](#variables) | Define job variables on a job level. | -| [interruptible](#interruptible) | Defines if a job can be canceled when made redundant by a newer run | +| [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | NOTE: **Note:** Parameters `types` and `type` are [deprecated](#deprecated-parameters). @@ -187,7 +187,7 @@ Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-ima For: -- Simple definition examples, see [Define `image` and `services` from .gitlab-ci.yml](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). - Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. #### `image:name` @@ -208,7 +208,7 @@ Used to specify a [service Docker image](../docker/using_docker_images.md#what-i For: -- Simple definition examples, see [Define `image` and `services` from .gitlab-ci.yml](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). +- Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). - Detailed usage information, refer to [Docker integration](../docker/README.md) documentation. - For example services, see [GitLab CI Services](../services/README.md). @@ -242,10 +242,10 @@ For more information, see see [Available settings for `services`](../docker/usin `before_script` is used to define the command that should be run before all jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts). -This can be an array or a multi-line string. +This must be an an array. `after_script` is used to define the command that will be run after all -jobs, including failed ones. This has to be an array or a multi-line string. +jobs, including failed ones. This must be an an array. Scripts specified in `before_script` are: @@ -318,6 +318,17 @@ There are also two edge cases worth mentioning: `test` and `deploy` are allowed to be used as job's stage by default. 1. If a job doesn't specify a `stage`, the job is assigned the `test` stage. +#### `.pre` and `.post` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31441) in GitLab 12.4. + +The following stages are available to every pipeline: + +- `.pre`, which is guaranteed to always be the first stage in a pipeline. +- `.post`, which is guaranteed to always be the last stage in a pipeline. + +User-defined stages are executed after `.pre` and before `.post`. + ### `stage` `stage` is defined per-job and relies on [`stages`](#stages) which is defined @@ -330,6 +341,10 @@ stages: - test - deploy +job 0: + stage: .pre + script: make something useful before build stage + job 1: stage: build script: make build dependencies @@ -345,6 +360,10 @@ job 3: job 4: stage: deploy script: make deploy + +job 5: + stage: .post + script: make something useful at the end of pipeline ``` #### Using your own Runners @@ -379,8 +398,8 @@ In addition, `only` and `except` allow the use of special keywords: | **Value** | **Description** | | --------- | ---------------- | -| `branches` | When a git reference of a pipeline is a branch. | -| `tags` | When a git reference of a pipeline is a tag. | +| `branches` | When a Git reference of a pipeline is a branch. | +| `tags` | When a Git reference of a pipeline is a tag. | | `api` | When pipeline has been triggered by a second pipelines API (not triggers API). | | `external` | When using CI services other than GitLab. | | `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. | @@ -436,13 +455,13 @@ repository and not forks: ```yaml job: only: - - branches@gitlab-org/gitlab-ce + - branches@gitlab-org/gitlab except: - - master@gitlab-org/gitlab-ce - - /^release/.*$/@gitlab-org/gitlab-ce + - master@gitlab-org/gitlab + - /^release/.*$/@gitlab-org/gitlab ``` -The above example will run `job` for all branches on `gitlab-org/gitlab-ce`, +The above example will run `job` for all branches on `gitlab-org/gitlab`, except `master` and those with names prefixed with `release/`. If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by @@ -530,15 +549,15 @@ single conjoined expression. That is: With `only`, individual keys are logically joined by an AND: -> (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active) +> (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active) `except` is implemented as a negation of this complete expression: -> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)) +> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)) This, more intuitively, means the keys join by an OR. A functionally equivalent expression: -> (any of refs) OR (any of variables) OR (any of changes) OR (if kubernetes is active) +> (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active) #### `only:refs`/`except:refs` @@ -612,7 +631,7 @@ Learn more about [variables expressions](../variables/README.md#environment-vari > `changes` policy [introduced][ce-19232] in GitLab 11.4. Using the `changes` keyword with `only` or `except` makes it possible to define if -a job should be created based on files modified by a git push event. +a job should be created based on files modified by a Git push event. For example: @@ -627,8 +646,8 @@ docker build: - more_scripts/*.{rb,py,sh} ``` -In the scenario above, when pushing multiple commits to GitLab to an existing -branch, GitLab creates and triggers the `docker build` job, provided that one of the +In the scenario above, when pushing commits to an existing branch in GitLab, +it creates and triggers the `docker build` job, provided that one of the commits contains changes to any of the following: - The `Dockerfile` file. @@ -636,7 +655,13 @@ commits contains changes to any of the following: - Any of the files and subdirectories inside the `dockerfiles` directory. - Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory. -You can also use glob patterns to match multiple files in either the root directory of the repo, or in _any_ directory within the repo. For example: +CAUTION: **Warning:** +If using `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), +undesired behavior could result if you do not [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). + +You can also use glob patterns to match multiple files in either the root directory +of the repo, or in _any_ directory within the repo, but they must be wrapped +in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example: ```yaml test: @@ -647,10 +672,8 @@ test: - "**/*.sql" ``` -NOTE: **Note:** -In the example above, the expressions are wrapped double quotes because they are glob patterns. GitLab will fail to parse `.gitlab-ci.yml` files with unwrapped glob patterns. - -The following example will skip the CI job if a change is detected in any file in the root directory of the repo with a `.md` extension: +The following example will skip the `build` job if a change is detected in any file +in the root directory of the repo with a `.md` extension: ```yaml build: @@ -661,22 +684,20 @@ build: ``` CAUTION: **Warning:** -There are some caveats when using this feature with new branches and tags. See -the section below. - -##### Using `changes` with new branches and tags +There are some points to be aware of when +[using this feature with new branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests). -When pushing a **new** branch or a **new** tag to GitLab, the policy always -evaluates to true and GitLab will create a job. This feature is not connected -with merge requests yet and, because GitLab is creating pipelines before a user -can create a merge request, it is unknown what the target branch is at this point. - -##### Using `changes` with `merge_requests` +##### Using `only:changes` with pipelines for merge requests With [pipelines for merge requests](../merge_request_pipelines/index.md), it is possible to define a job to be created based on files modified in a merge request. +In order to deduce the correct base SHA of the source branch, we recommend combining +this keyword with `only: merge_requests`. This way, file differences are correctly +calculated from any further commits, thus all changes in the merge requests are properly +tested in pipelines. + For example: ```yaml @@ -694,6 +715,42 @@ In the scenario above, if a merge request is created or updated that changes either files in `service-one` directory or the `Dockerfile`, GitLab creates and triggers the `docker build service one` job. +Note that if [pipelines for merge requests](../merge_request_pipelines/index.md) is +combined with `only: change`, but `only: merge_requests` is omitted, there could be +unwanted behavior. + +For example: + +```yaml +docker build service one: + script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . + only: + changes: + - Dockerfile + - service-one/**/* +``` + +In the example above, a pipeline could fail due to changes to a file in `service-one/**/*`. +A later commit could then be pushed that does not include any changes to this file, +but includes changes to the `Dockerfile`, and this pipeline could pass because it is only +testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**, +that **passed**, and will show the merge request as mergable, despite the earlier +failed pipeline caused by a change that was not yet corrected. + +With this configuration, care must be taken to check that the most recent pipeline +properly corrected any failures from previous pipelines. + +##### Using `only:changes` without pipelines for merge requests + +Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines +run on branches or tags that don't have an explicit association with a merge request. +In this case, a previous SHA is used to calculate the diff, which equivalent to `git diff HEAD~`. +This could result in some unexpected behavior, including: + +- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. +- When pushing a new commit, the changed files are calculated using the previous commit + as the base SHA. + ### `rules` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/29011) in GitLab 12.3. @@ -707,6 +764,7 @@ Available rule clauses include: (similar to [`only:variables`](#onlyvariablesexceptvariables)). - [`changes`](#ruleschanges) (same as [`only:changes`](#onlychangesexceptchanges)). +- [`exists`](#rulesexists) For example, using `if`. This configuration specifies that `job` should be built and run for every pipeline on merge requests targeting `master`, regardless of @@ -716,7 +774,7 @@ the status of other builds: job: script: "echo Hello, Rules!" rules: - - if: '$CI_MERGE_REQUEST_TARGET_BRANCH == "master"' + - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: always - if: '$VAR =~ /pattern/' when: manual @@ -742,11 +800,11 @@ evaluated should be conjoined into a single expression using `&&` or `||`. For e job: script: "echo Hello, Rules!" rules: - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' # This rule will be evaluated when: always - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH =~ /^feature/' # This rule will only be evaluated if the target branch is not "master" + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' # This rule will only be evaluated if the target branch is not "master" when: manual - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH' # If neither of the first two match but the simple presence does, we set to "on_success" by default + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # If neither of the first two match but the simple presence does, we set to "on_success" by default ``` If none of the provided rules match, the job will be set to `when:never`, and @@ -779,9 +837,44 @@ In this example, a job either set to: - Run manually if `Dockerfile` has changed OR `$VAR == "string value"`. - `when:on_success` by the last rule, where no earlier clauses evaluate to true. +#### `rules:exists` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16574) in GitLab 12.4. + +`exists` accepts an array of paths and will match if any of these paths exist +as files in the repository. + +For example: + +```yaml +job: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - exists: + - Dockerfile +``` + +You can also use glob patterns to match multiple files in any directory within +the repository. + +For example: + +```yaml +job: + script: bundle exec rspec + rules: + - exists: + - spec/**.rb +``` + +NOTE: **Note:** +For performance reasons, using `exists` with patterns is limited to 10000 +checks. After the 10000th check, rules with patterned globs will always match. + #### Complex rule clauses -To conjoin `if` and `changes` clauses with an AND, use them in the same rule. +To conjoin `if`, `changes`, and `exists` clauses with an AND, use them in the +same rule. In the following example: @@ -805,6 +898,7 @@ The only clauses currently available are: - `if` - `changes` +- `exists` Keywords such as `branches` or `refs` that are currently available for `only`/`except` are not yet available in `rules` as they are being individually @@ -837,7 +931,7 @@ docker build: Additional job configuration may be added to rules in the future. If something useful isn't available, please -[open an issue](https://www.gitlab.com/gitlab-org/gitlab-foss/issues). +[open an issue](https://www.gitlab.com/gitlab-org/gitlab/issues). ### `tags` @@ -1011,7 +1105,52 @@ Manual actions are considered to be write actions, so permissions for [protected branches](../../user/project/protected_branches.md) are used when a 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, the user needs to -have the ability to merge to this branch. +have the ability to merge to this branch. It is possible to use protected environments +to more strictly [protect manual deployments](#protecting-manual-jobs-premium) from being +run by unauthorized users. + +NOTE: **Note:** +Using `when:manual` and `trigger` together results in the error `jobs:#{job-name} when +should be on_success, on_failure or always`, because `when:manual` prevents triggers +being used. + +##### Protecting manual jobs **(PREMIUM)** + +It's possible to use [protected environments](../environments/protected_environments.md) +to define a precise list of users authorized to run a manual job. By allowing only +users associated with a protected environment to trigger manual jobs, it is possible +to implement some special use cases, such as: + +- More precisely limiting who can deploy to an environment. +- Enabling a pipeline to be blocked until an approved user "approves" it. + +To do this, you must: + +1. Add an `environment` to the job. For example: + + ```yaml + deploy_prod: + stage: deploy + script: + - echo "Deploy to production server" + environment: + name: production + url: https://example.com + when: manual + only: + - master + ``` + +1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments), + select the environment (`production` in the example above) and add the users, roles or groups + that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in + this list will be able to trigger this manual job, as well as GitLab administrators + who are always able to use protected environments. + +Additionally, if a manual job is defined as blocking by adding `allow_failure: false`, +the next stages of the pipeline will not run until the manual job is triggered. This +can be used as a way to have a defined list of users allowed to "approve" later pipeline +stages by triggering the blocking manual job. #### `when:delayed` @@ -1047,7 +1186,7 @@ You can stop the active timer of a delayed job by clicking the **Unschedule** bu This job will never be executed in the future unless you execute the job manually. You can start a delayed job immediately by clicking the **Play** button. -GitLab runner will pick your job soon and start the job. +GitLab Runner will pick your job soon and start the job. ### `environment` @@ -1241,15 +1380,15 @@ Read how caching works and find out some good practices in the [caching dependencies documentation](../caching/index.md). `cache` is used to specify a list of files and directories which should be -cached between jobs. You can only use paths that are within the project -workspace. +cached between jobs. You can only use paths that are within the local working +copy. If `cache` is defined outside the scope of jobs, it means it is set globally and all jobs will use that definition. #### `cache:paths` -Use the `paths` directive to choose which files or directories will be cached. +Use the `paths` directive to choose which files or directories will be cached. You can only specify paths within your `$CI_PROJECT_DIR`. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and [filepath.Match](https://golang.org/pkg/path/filepath/#Match). Cache all files in `binaries` that end in `.apk` and the `.config` file: @@ -1412,10 +1551,10 @@ be available for download in the GitLab UI. #### `artifacts:paths` -You can only use paths that are within the project workspace. +You can only use paths that are within the local working copy. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and [filepath.Match](https://golang.org/pkg/path/filepath/#Match). -To pass artifacts between different jobs, see [dependencies](#dependencies). +To restrict which jobs a specific job will fetch artifacts from, see [dependencies](#dependencies). Send all files in `binaries` and `.config`: @@ -1759,10 +1898,9 @@ be automatically shown in merge requests. > Introduced in GitLab 8.6 and GitLab Runner v1.1.1. -This feature should be used in conjunction with [`artifacts`](#artifacts) and -allows you to define the artifacts to pass between different jobs. - -Note that `artifacts` from all previous [stages](#stages) are passed by default. +By default, all [`artifacts`](#artifacts) from all previous [stages](#stages) +are passed, but you can use the `dependencies` parameter to define a limited +list of jobs (or no jobs) to fetch artifacts from. To use this feature, define `dependencies` in context of the job and pass a list of all previous jobs from which the artifacts should be downloaded. @@ -1892,14 +2030,14 @@ This example creates three paths of execution: - For self-managed instances, the limit is: - Five by default (`ci_dag_limit_needs` feature flag is enabled). - 50 if the `ci_dag_limit_needs` feature flag is disabled. -- It is impossible for now to have `needs: []` (empty needs), - the job always needs to depend on something, unless this is the job - in the first stage (see [gitlab-ce#65504](https://gitlab.com/gitlab-org/gitlab-foss/issues/65504)). +- It is impossible for now to have `needs: []` (empty needs), the job always needs to + depend on something, unless this is the job in the first stage. However, support for + an empty needs array [is planned](https://gitlab.com/gitlab-org/gitlab/issues/30631). - If `needs:` refers to a job that is marked as `parallel:`. the current job will depend on all parallel jobs created. -- `needs:` is similar to `dependencies:` in that it needs to use jobs from - prior stages, meaning it is impossible to create circular - dependencies or depend on jobs in the current stage (see [gitlab-ce#65505](https://gitlab.com/gitlab-org/gitlab-foss/issues/65505)). +- `needs:` is similar to `dependencies:` in that it needs to use jobs from prior stages, + meaning it is impossible to create circular dependencies. Depending on jobs in the + current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/issues/30632). - Related to the above, stages must be explicitly defined for all jobs that have the keyword `needs:` or are referred to by one. @@ -1996,9 +2134,11 @@ Possible values for `when` are: - `missing_dependency_failure`: Retry if a dependency was missing. - `runner_unsupported`: Retry if the runner was unsupported. -### timeout +### `timeout` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14887) in GitLab 12.3. -`timeout` allows you to configure a timeout for a specific job: +`timeout` allows you to configure a timeout for a specific job. For example: ```yaml build: @@ -2010,6 +2150,10 @@ test: timeout: 3h 30m ``` +The job-level timeout can exceed the +[project-level timeout](../../user/project/pipelines/settings.md#timeout) but can not +exceed the Runner-specific timeout. + ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22631) in GitLab 11.5. @@ -2068,6 +2212,11 @@ created. Learn more about [multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml). +NOTE: **Note:** +Using a `trigger` with `when:manual` together results in the error `jobs:#{job-name} +when should be on_success, on_failure or always`, because `when:manual` prevents +triggers being used. + #### Simple `trigger` syntax The most simple way to configure a downstream trigger to use `trigger` keyword @@ -2104,19 +2253,19 @@ staging: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/23464) in GitLab 12.3. -`interruptible` is used to indicate that a job should be canceled if made redundant by a newer run of the same job. Defaults to `false`. +`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`. This value will only be used if the [automatic cancellation of redundant pipelines feature](../../user/project/pipelines/settings.md#auto-cancel-pending-pipelines) is enabled. When enabled, a pipeline on the same branch will be canceled when: - It is made redundant by a newer pipeline run. -- Either all jobs are set as interruptible, or any uninterruptible jobs are not yet pending. +- Either all jobs are set as interruptible, or any uninterruptible jobs have not started. Pending jobs are always considered interruptible. TIP: **Tip:** -Set jobs as uninterruptible that should behave atomically and should never be canceled once started. +Set jobs as interruptible that can be safely canceled once started (for instance, a build job). Here is a simple example: @@ -2124,23 +2273,33 @@ Here is a simple example: stages: - stage1 - stage2 + - stage3 step-1: stage: stage1 script: - - echo "Can be canceled" - + - echo "Can be canceled." + interruptible: true + step-2: stage: stage2 script: - - echo "Can not be canceled" - interruptible: false + - echo "Can not be canceled." + +step-3: + stage: stage3 + script: + - echo "Because step-2 can not be canceled, this step will never be canceled, even though set as interruptible." + interruptible: true ``` In the example above, a new pipeline run will cause an existing running pipeline to be: - Canceled, if only `step-1` is running or pending. -- Not canceled, once `step-2` becomes pending. +- Not canceled, once `step-2` starts running. + +NOTE: **Note:** +Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state. ### `include` @@ -2243,7 +2402,7 @@ or template includes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53445) in GitLab 11.7. `include:template` can be used to include `.gitlab-ci.yml` templates that are -[shipped with GitLab](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/lib/gitlab/ci/templates). +[shipped with GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). For example: @@ -2284,9 +2443,13 @@ or public project, or template is allowed. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/56836) in GitLab 11.9. Nested includes allow you to compose a set of includes. -A total of 50 includes is allowed. +A total of 100 includes is allowed. Duplicate includes are considered a configuration error. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/28212) in GitLab 12.4. + +A hard limit of 30 seconds was set for resolving all files. + #### `include` examples Here are a few more `include` examples. @@ -2722,14 +2885,14 @@ unspecified, the default from project settings will be used. There are three possible values: `clone`, `fetch`, and `none`. `clone` is the slowest option. It clones the repository from scratch for every -job, ensuring that the project workspace is always pristine. +job, ensuring that the local working copy is always pristine. ```yaml variables: GIT_STRATEGY: clone ``` -`fetch` is faster as it re-uses the project workspace (falling back to `clone` +`fetch` is faster as it re-uses the local working copy (falling back to `clone` if it doesn't exist). `git clean` is used to undo any changes made by the last job, and `git fetch` is used to retrieve commits made since the last job ran. @@ -2738,11 +2901,11 @@ variables: GIT_STRATEGY: fetch ``` -`none` also re-uses the project workspace, but skips all Git operations +`none` also re-uses the local working copy, but skips all Git operations (including GitLab Runner's pre-clone script, if present). It is mostly useful for jobs that operate exclusively on artifacts (e.g., `deploy`). Git repository data may be present, but it is certain to be out of date, so you should only -rely on files brought into the project workspace from cache or artifacts. +rely on files brought into the local working copy from cache or artifacts. ```yaml variables: @@ -2829,7 +2992,7 @@ 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) +`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. @@ -2944,7 +3107,7 @@ default: ## Custom build directories -> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267) in Gitlab Runner 11.10 +> [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 @@ -3205,13 +3368,8 @@ all updated Merge Requests will have a pipeline created when using If your commit message contains `[ci skip]` or `[skip ci]`, using any capitalization, the commit will be created but the pipeline will be skipped. -Alternatively, one can pass the `ci.skip` [Git push option][push-option] if -using Git 2.10 or newer: - -```sh -git push --push-option=ci.skip # using git 2.10+ -git push -o ci.skip # using git 2.18+ -``` +Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd) +if using Git 2.10 or newer. <!-- ## Troubleshooting |
