diff options
Diffstat (limited to 'doc/ci')
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 15 | ||||
| -rw-r--r-- | doc/ci/docker/using_docker_images.md | 71 | ||||
| -rw-r--r-- | doc/ci/environments.md | 53 | ||||
| -rw-r--r-- | doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md | 4 | ||||
| -rw-r--r-- | doc/ci/git_submodules.md | 19 | ||||
| -rw-r--r-- | doc/ci/review_apps/index.md | 9 | ||||
| -rw-r--r-- | doc/ci/runners/README.md | 5 | ||||
| -rw-r--r-- | doc/ci/ssh_keys/README.md | 4 | ||||
| -rw-r--r-- | doc/ci/triggers/README.md | 29 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 93 |
10 files changed, 154 insertions, 148 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 63338ff632c..54a8cfe7fd8 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -381,17 +381,18 @@ environment = ["DOCKER_DRIVER=overlay2"] If you're running multiple Runners you will have to modify all configuration files. > **Notes:** -- More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). -- For more information about using OverlayFS with Docker, you can read - [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). +> +> - More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/). +> - For more information about using OverlayFS with Docker, you can read +> [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry > **Notes:** -- This feature requires GitLab 8.8 and GitLab Runner 1.2. -- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need - to pass a [personal access token][pat] instead of your password in order to - login to GitLab's Container Registry. +> - This feature requires GitLab 8.8 and GitLab Runner 1.2. +> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need +> to pass a [personal access token][pat] instead of your password in order to +> login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 71f1d69cdf4..9abedcc6acb 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -452,13 +452,14 @@ that runner. ## Define an image from a private Container Registry > **Notes:** -- This feature requires GitLab Runner **1.8** or higher -- For GitLab Runner versions **>= 0.6, <1.8** there was a partial - support for using private registries, which required manual configuration - of credentials on runner's host. We recommend to upgrade your Runner to - at least version **1.8** if you want to use private registries. -- If the repository is private you need to authenticate your GitLab Runner in the - registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. +> +> - This feature requires GitLab Runner **1.8** or higher +> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial +> support for using private registries, which required manual configuration +> of credentials on runner's host. We recommend to upgrade your Runner to +> at least version **1.8** if you want to use private registries. +> - If the repository is private you need to authenticate your GitLab Runner in the +> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. As an example, let's assume that you want to use the `registry.example.com/private/image:latest` image which is private and requires you to login into a private container registry. @@ -475,57 +476,57 @@ To configure access for `registry.example.com`, follow these steps: 1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to accomplish this: - - **First way -** Do a `docker login` on your local machine: + - **First way -** Do a `docker login` on your local machine: - ```bash - docker login registry.example.com --username my_username --password my_password - ``` + ```bash + docker login registry.example.com --username my_username --password my_password + ``` - Then copy the content of `~/.docker/config.json`. - - **Second way -** In some setups, it's possible that Docker client will use + Then copy the content of `~/.docker/config.json`. + - **Second way -** In some setups, it's possible that Docker client will use the available system keystore to store the result of `docker login`. In that case, it's impossible to read `~/.docker/config.json`, so you will need to prepare the required base64-encoded version of `${username}:${password}` manually. Open a terminal and execute the following command: - ```bash - echo -n "my_username:my_password" | base64 + ```bash + echo -n "my_username:my_password" | base64 - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` + # Example output to copy + bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= + ``` 1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: - ```json - { - "auths": { - "registry.example.com": { - "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" - } - } - } - ``` + ```json + { + "auths": { + "registry.example.com": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } + } + ``` 1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG` value, do a `docker logout` on your computer if you don't need access to the registry from it: - ```bash - docker logout registry.example.com - ``` + ```bash + docker logout registry.example.com + ``` 1. You can now use any private image from `registry.example.com` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: - ```yaml - image: my.registry.tld:5000/namespace/image:tag - ``` + ```yaml + image: my.registry.tld:5000/namespace/image:tag + ``` - In the example above, GitLab Runner will look at `my.registry.tld:5000` for the - image `namespace/image:tag`. + In the example above, GitLab Runner will look at `my.registry.tld:5000` for the + image `namespace/image:tag`. You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 8ea2e0a81dc..f1e5b00e927 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that has an environment specified and succeeds, a deployment is recorded, remembering the Git SHA and environment name. ->**Note:** -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. - ->**Note:** -Starting with GitLab 9.3, the environment URL is exposed to the Runner via -`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if -the URL was not defined there, the external URL from the environment would be -used. +> **Note:** +> 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. +> +> **Note:** +> Starting with GitLab 9.3, the environment URL is exposed to the Runner via +> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if +> the URL was not defined there, the external URL from the environment would be +> used. To sum up, with the above `.gitlab-ci.yml` we have achieved that: @@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see: - A button that re-deploys the latest deployment, meaning it runs the job defined by the environment name for that specific commit ->**Notes:** -- While you can create environments manually in the web interface, we recommend - that you define your environments in `.gitlab-ci.yml` first. They will - be automatically created for you after the first deploy. -- The environments page can only be viewed by Reporters and above. For more - information on the permissions, see the [permissions documentation][permissions]. -- Only deploys that happen after your `.gitlab-ci.yml` is properly configured - will show up in the "Environment" and "Last deployment" lists. +> **Notes:** +> +> - While you can create environments manually in the web interface, we recommend +> that you define your environments in `.gitlab-ci.yml` first. They will +> be automatically created for you after the first deploy. +> - The environments page can only be viewed by Reporters and above. For more +> information on the permissions, see the [permissions documentation][permissions]. +> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured +> will show up in the "Environment" and "Last deployment" lists. The information shown in the Environments page is limited to the latest deployments, but as you may have guessed an environment can have multiple @@ -563,13 +564,13 @@ exist, you should see something like: ## Monitoring environments ->**Notes:** +> **Notes:** > -- For the monitoring dashboard to appear, you need to: - - Have enabled the [Prometheus integration][prom] - - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) -- With GitLab 9.2, all deployments to an environment are shown directly on the - monitoring dashboard +> - For the monitoring dashboard to appear, you need to: +> - Have enabled the [Prometheus integration][prom] +> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +> - With GitLab 9.2, all deployments to an environment are shown directly on the +> monitoring dashboard If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment. 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 a2de0408797..b2c73caae2e 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 @@ -85,7 +85,7 @@ When asked, answer `Y` to fetch and install dependencies. If everything went fine, you'll get an output like this: - + Now, our project is located inside the directory with the same name we pass to `mix` command, for example, `~/GitLab/hello_gitlab_ci`. @@ -145,7 +145,7 @@ Now, we have our app running locally. We can preview it directly on our browser. not work, open [`127.0.0.1:4000`](http://127.0.0.1:4000) instead and later, configure your OS to point `localhost` to `127.0.0.1`. - + Great, now we have a local Phoenix Server running our app. diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 286f3dee665..37078230b34 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,15 +1,16 @@ # Using Git submodules with GitLab CI > **Notes:** -- GitLab 8.12 introduced a new [CI job permissions model][newperms] and you - are encouraged to upgrade your GitLab instance if you haven't done already. - If you are **not** using GitLab 8.12 or higher, you would need to work your way - around submodules in order to access the sources of e.g., `gitlab.com/group/project` - with the use of [SSH keys](ssh_keys/README.md). -- With GitLab 8.12 onward, your permissions are used to evaluate what a CI job - can access. More information about how this system works can be found in the - [Jobs permissions model](../user/permissions.md#job-permissions). -- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. +> +> - GitLab 8.12 introduced a new [CI job permissions model][newperms] and you +> are encouraged to upgrade your GitLab instance if you haven't done already. +> If you are **not** using GitLab 8.12 or higher, you would need to work your way +> around submodules in order to access the sources of e.g., `gitlab.com/group/project` +> with the use of [SSH keys](ssh_keys/README.md). +> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job +> can access. More information about how this system works can be found in the +> [Jobs permissions model](../user/permissions.md#job-permissions). +> - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. ## Configuring the `.gitmodules` file diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 28c484ddbe6..1b17f6ac5ea 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,10 +1,9 @@ # Getting started with Review Apps -> -- [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab - 8.13 and 8.14. -- Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by - [Fourchette]. +> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab +> 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by +> [Fourchette]. The basis of Review Apps is the [dynamic environments] which allow you to create a new environment (dynamically) for each one of your branches. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 8f1ff190804..7859d2ec631 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -144,9 +144,8 @@ An admin can enable/disable a specific Runner for projects: ## Protected Runners -> -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) -in GitLab 10.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) +> in GitLab 10.0. You can protect Runners from revealing sensitive information. Whenever a Runner is protected, the Runner picks only jobs created on diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 4cb05509e7b..0c3b0bf6990 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -46,7 +46,7 @@ to access it. This is where an SSH key pair comes in handy. 1. You will first need to create an SSH key pair. For more information, follow the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair). - **Do not** add a passphrase to the SSH key, or the `before_script` will\ + **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. 1. Create a new [variable](../variables/README.md#variables). @@ -175,7 +175,7 @@ Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the [content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor) above, here's what more you need to add: - ```yaml +```yaml before_script: ## ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index c213b096a14..cf92d90ba30 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,9 +1,10 @@ # Triggering pipelines through the API > **Notes**: -- [Introduced][ci-229] in GitLab CE 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#job-triggers). +> +> - [Introduced][ci-229] in GitLab CE 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#job-triggers). Triggers can be used to force a pipeline rerun of a specific `ref` (branch or tag) with an API call. @@ -49,11 +50,12 @@ The action is irreversible. ## Triggering a pipeline > **Notes**: -- Valid refs are only the branches and tags. If you pass a commit SHA as a ref, - it will not trigger a job. -- If your project is public, passing the token in plain text is probably not the - wisest idea, so you might want to use a - [variable](../variables/README.md#variables) for that purpose. +> +> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref, +> it will not trigger a job. +> - If your project is public, passing the token in plain text is probably not the +> wisest idea, so you might want to use a +> [variable](../variables/README.md#variables) for that purpose. To trigger a job you need to send a `POST` request to GitLab's API endpoint: @@ -122,11 +124,12 @@ Now, whenever a new tag is pushed on project A, the job will run and the ## Triggering a pipeline from a webhook > **Notes**: -- Introduced in GitLab 8.14. -- `ref` should be passed as part of the URL in order to take precedence over - `ref` from the webhook body that designates the branch ref that fired the - trigger in the source repository. -- `ref` should be URL-encoded if it contains slashes. +> +> - Introduced in GitLab 8.14. +> - `ref` should be passed as part of the URL in order to take precedence over +> `ref` from the webhook body that designates the branch ref that fired the +> trigger in the source repository. +> - `ref` should be URL-encoded if it contains slashes. To trigger a job from a webhook of another project you need to add the following webhook URL for Push and Tag events (change the project ID, ref and token): diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index c1ebe39e076..d89705e8ead 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -383,7 +383,7 @@ except master. ## `only` and `except` (complex) > `refs` and `kubernetes` policies introduced in GitLab 10.0 - +> > `variables` policy introduced in 10.7 CAUTION: **Warning:** @@ -583,9 +583,10 @@ The above script will: ### `when:manual` > **Notes:** -- Introduced in GitLab 8.10. -- Blocking manual actions were introduced in GitLab 9.0. -- Protected actions were introduced in GitLab 9.2. +> +> - Introduced in GitLab 8.10. +> - Blocking manual actions were introduced in GitLab 9.0. +> - Protected actions were introduced in GitLab 9.2. Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions @@ -616,11 +617,11 @@ have ability to merge to this branch. ## `environment` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.9. -- You can read more about environments and find more examples in the - [documentation about environments][environment]. +> - Introduced in GitLab 8.9. +> - You can read more about environments and find more examples in the +> [documentation about environments][environment]. `environment` is used to define that a job deploys to a specific environment. If `environment` is specified and no environment under that name exists, a new @@ -641,15 +642,15 @@ deployment to the `production` environment. ### `environment:name` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the name of an environment could be defined as a string like - `environment: production`. The recommended way now is to define it under the - `name` keyword. -- The `name` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the name of an environment could be defined as a string like +> `environment: production`. The recommended way now is to define it under the +> `name` keyword. +> - The `name` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. The `environment` name can contain: @@ -680,14 +681,14 @@ deploy to production: ### `environment:url` +> **Notes:** > -**Notes:** -- Introduced in GitLab 8.11. -- Before GitLab 8.11, the URL could be added only in GitLab's UI. The - recommended way now is to define it in `.gitlab-ci.yml`. -- The `url` parameter can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - Introduced in GitLab 8.11. +> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The +> recommended way now is to define it in `.gitlab-ci.yml`. +> - The `url` parameter can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. This is an optional value that when set, it exposes buttons in various places in GitLab which when clicked take you to the defined URL. @@ -707,12 +708,12 @@ deploy to production: ### `environment:on_stop` +> **Notes:** > -**Notes:** -- [Introduced][ce-6669] in GitLab 8.13. -- Starting with GitLab 8.14, when you have an environment that has a stop action - defined, GitLab will automatically trigger a stop action when the associated - branch is deleted. +> - [Introduced][ce-6669] in GitLab 8.13. +> - Starting with GitLab 8.14, when you have an environment that has a stop action +> defined, GitLab will automatically trigger a stop action when the associated +> branch is deleted. Closing (stoping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close @@ -763,13 +764,13 @@ The `stop_review_app` job is **required** to have the following keywords defined ### Dynamic environments +> **Notes:** > -**Notes:** -- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. -- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. -- The `name` and `url` parameters can use any of the defined CI variables, - including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). - You however cannot use variables defined under `script`. +> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. +> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15. +> - The `name` and `url` parameters can use any of the defined CI variables, +> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables). +> You however cannot use variables defined under `script`. For example: @@ -799,13 +800,13 @@ as Review Apps. You can see a simple example using Review Apps at ## `cache` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0. -- `cache` can be set globally and per-job. -- From GitLab 9.0, caching is enabled and shared between pipelines and jobs - by default. -- From GitLab 9.2, caches are restored before [artifacts](#artifacts). +> - Introduced in GitLab Runner v0.7.0. +> - `cache` can be set globally and per-job. +> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs +> by default. +> - From GitLab 9.2, caches are restored before [artifacts](#artifacts). TIP: **Learn more:** Read how caching works and find out some good practices in the @@ -967,13 +968,13 @@ skip the download step. ## `artifacts` +> **Notes:** > -**Notes:** -- Introduced in GitLab Runner v0.7.0 for non-Windows platforms. -- Windows support was added in GitLab Runner v.1.0.0. -- From GitLab 9.2, caches are restored before artifacts. -- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). -- Job artifacts are only collected for successful jobs by default. +> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. +> - Windows support was added in GitLab Runner v.1.0.0. +> - From GitLab 9.2, caches are restored before artifacts. +> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). +> - Job artifacts are only collected for successful jobs by default. `artifacts` is used to specify a list of files and directories which should be attached to the job after success. |