Commit d88e5224 authored by Amy Qualls's avatar Amy Qualls

Merge branch 'docs-update-only-to-rules' into 'master'

Update CI/CD examples to use rules

See merge request gitlab-org/gitlab!63996
parents 7e5275f9 665ce5e1
......@@ -99,8 +99,8 @@ build:
KANIKOCFG="${KANIKOCFG} }"
echo "${KANIKOCFG}" > /kaniko/.docker/config.json
- /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile $KANIKOPROXYBUILDARGS --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
only:
- tags
rules:
- if: $CI_COMMIT_TAG
```
## Using a registry with a custom certificate
......
......@@ -99,10 +99,10 @@ deploy_review:
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
only:
- branches
except:
- master
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: never
- if: $CI_COMMIT_BRANCH
```
In this example:
......@@ -158,8 +158,8 @@ deploy_prod:
name: production
url: https://example.com
when: manual
only:
- master
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
The `when: manual` action:
......@@ -200,8 +200,8 @@ deploy:
url: https://example.com
kubernetes:
namespace: production
only:
- master
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
......
......@@ -349,12 +349,14 @@ variable entry.
GitLab does support a [`when` keyword](../yaml/README.md#when) which is used to indicate when a job should be
run in case of (or despite) failure, but most of the logic for controlling pipelines can be found in
our very powerful [`only/except` rules system](../yaml/README.md#only--except)
(see also our [advanced syntax](../yaml/README.md#only--except)):
our very powerful [`rules` system](../yaml/README.md#rules):
```yaml
my_job:
only: [branches]
script:
- echo
rules:
- if: $CI_COMMIT_BRANCH
```
## Additional resources
......
......@@ -38,7 +38,7 @@ set of concurrently running child pipelines, but within the same project:
Child pipelines work well with other GitLab CI/CD features:
- Use [`only: changes`](yaml/README.md#onlychanges--exceptchanges) to trigger pipelines only when
- Use [`rules: changes`](yaml/README.md#ruleschanges) to trigger pipelines only when
certain files change. This is useful for monorepos, for example.
- Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal
pipelines, they can have their own behaviors and sequencing in relation to triggers.
......
......@@ -8,9 +8,6 @@ type: reference, howto
# Pipeline schedules **(FREE)**
> - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10533).
> - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10853) in GitLab 9.2.
Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
......@@ -54,31 +51,29 @@ is installed on.
### Using variables
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12328) in GitLab 9.4.
You can pass any number of arbitrary variables. They are available in
GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/README.md).
![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
### Using only and except
### Using `rules`
To configure a job to be executed only when the pipeline has been
scheduled (or the opposite), use
[only and except](../yaml/README.md#only--except) configuration keywords.
scheduled, use the [`rules`](../yaml/README.md#rules) keyword.
In the example below `make world` runs in scheduled pipelines, and `make build` runs in pipelines that are not scheduled:
In this example, `make world` runs in scheduled pipelines, and `make build`
runs in branch and tag pipelines:
```yaml
job:on-schedule:
only:
- schedules
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
script:
- make world
job:
except:
- schedules
rules:
- if: $CI_PIPELINE_SOURCE = "push"
script:
- make build
```
......
......@@ -57,8 +57,8 @@ trigger_pipeline:
stage: deploy
script:
- curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
only:
- tags
rules:
- if: $CI_COMMIT_TAG
```
Pipelines triggered that way also expose a special variable:
......@@ -83,8 +83,8 @@ build_submodule:
- apt update && apt install -y unzip
- curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
- unzip artifacts.zip
only:
- tags
rules:
- if: $CI_COMMIT_TAG
```
This allows you to use that for multi-project pipelines and download artifacts
......@@ -163,8 +163,8 @@ trigger_pipeline:
stage: deploy
script:
- 'curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"'
only:
- tags
rules:
- if: $CI_COMMIT_TAG
```
This means that whenever a new tag is pushed on project A, the job runs and the
......
......@@ -35,7 +35,7 @@ There are two places defined variables can be used. On the:
| `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment |
| `script`, `before_script`, `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) |
| `only:variables:[]`, `except:variables:[]`, `rules:if` | no | n/a | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
| `only:variables:[]`, `except:variables:[]`, `rules:if` | no | n/a | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
### `config.toml` file
......@@ -193,7 +193,6 @@ my-job:
name: review/$CI_JOB_STAGE/deploy
script:
- 'deploy staging'
only:
variables:
- $STAGING_SECRET == 'something'
rules:
- if: $STAGING_SECRET == 'something'
```
......@@ -991,8 +991,8 @@ but you can use as many as eleven. The following example has two levels of inher
```yaml
.tests:
only:
- pushes
rules:
- if: $CI_PIPELINE_SOURCE == "push"
.rspec:
extends: .tests
......@@ -1028,9 +1028,9 @@ levels. For example:
variables:
URL: "http://my-url.internal"
IMPORTANT_VAR: "the details"
only:
- main
- stable
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_BRANCH == "stable"
tags:
- production
script:
......@@ -1061,9 +1061,9 @@ rspec:
URL: "http://docker-url.internal"
IMPORTANT_VAR: "the details"
GITLAB: "is-awesome"
only:
- main
- stable
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_BRANCH == "stable"
tags:
- docker
image: alpine
......@@ -2333,8 +2333,8 @@ To protect a manual job:
name: production
url: https://example.com
when: manual
only:
- main
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
......@@ -3281,8 +3281,8 @@ Create artifacts only for tags (`default-job` doesn't create artifacts):
default-job:
script:
- mvn test -U
except:
- tags
rules:
- if: $CI_COMMIT_BRANCH
release-job:
script:
......@@ -3290,8 +3290,8 @@ release-job:
artifacts:
paths:
- target/*.war
only:
- tags
rules:
- if: $CI_COMMIT_TAG
```
You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`:
......@@ -4370,7 +4370,10 @@ job:
description: 'Release description'
```
It is also possible to create any unique tag, in which case `only: tags` is not mandatory.
It is also possible for the release job to automatically create a new unique tag. In that case,
do not use [`rules`](#rules) or [`only`](#only--except) to configure the job to
only run for tags.
A semantic versioning example:
```yaml
......@@ -4626,8 +4629,8 @@ pages:
artifacts:
paths:
- public
only:
- main
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
View the [GitLab Pages user documentation](../../user/project/pages/index.md).
......
......@@ -111,8 +111,8 @@ production:
environment:
name: production
url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
only:
- main
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
Content of `.gitlab-ci.yml`:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment