Skip to content
代码片段 群组 项目
未验证 提交 2ee74dff 编辑于 作者: Marcel Amirault's avatar Marcel Amirault 提交者： GitLab
浏览文件

Remove deprecated only except details 

Only and except are deprecated and should not be used
or promoted in the docs as a standard option anymore.
This MR also removes version references that are more than
2 major versions out of date.
上级 5ffaa7ea
No related branches found
No related tags found
无相关合并请求
隐藏空白变更内容
行内 左右并排
doc/ci/jobs/job_control.md
+ 3
− 243
浏览文件 @ 2ee74dff
...@@ -21,8 +21,6 @@ earlier jobs it depends on finish running. ...@@ -21,8 +21,6 @@ earlier jobs it depends on finish running.
## Specify when jobs run with `rules` ## Specify when jobs run with `rules`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
Use [`rules`](../yaml/index.md#rules) to include or exclude jobs in pipelines. Use [`rules`](../yaml/index.md#rules) to include or exclude jobs in pipelines.
Rules are evaluated in order until the first match. When a match is found, the job Rules are evaluated in order until the first match. When a match is found, the job
...@@ -157,7 +155,6 @@ If the `Dockerfile` file or any file in `/docker/scripts` has changed **and** `$ ...@@ -157,7 +155,6 @@ If the `Dockerfile` file or any file in `/docker/scripts` has changed **and** `$
then the job runs manually and is allowed to fail. then the job runs manually and is allowed to fail.
You can use [parentheses](#group-variable-expressions-together-with-parentheses) with `&&` and `||` to build more complicated variable expressions. You can use [parentheses](#group-variable-expressions-together-with-parentheses) with `&&` and `||` to build more complicated variable expressions.
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3:
```yaml ```yaml
job1: job1:
...@@ -167,10 +164,6 @@ job1: ...@@ -167,10 +164,6 @@ job1:
- if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE - if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
``` ```
WARNING:
[Before GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/230938),
rules that use both `||` and `&&` may evaluate with an unexpected order of operations.
### Avoid duplicate pipelines ### Avoid duplicate pipelines
If a job uses `rules`, a single action, like pushing a commit to a branch, can trigger If a job uses `rules`, a single action, like pushing a commit to a branch, can trigger
...@@ -274,7 +267,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: ...@@ -274,7 +267,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
| `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). |
| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). | | `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). |
| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **Build > Pipelines** section. | | `web` | For pipelines created by selecting **Run pipeline** in the GitLab UI, from the project's **Build > Pipelines** section. |
| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | | `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). |
The following example runs the job as a manual job in scheduled pipelines or in push The following example runs the job as a manual job in scheduled pipelines or in push
...@@ -321,9 +314,6 @@ Other commonly used variables for `if` clauses: ...@@ -321,9 +314,6 @@ Other commonly used variables for `if` clauses:
### Variables in `rules:changes` ### Variables in `rules:changes`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7.
You can use CI/CD variables in `rules:changes` expressions to determine when You can use CI/CD variables in `rules:changes` expressions to determine when
to add jobs to a pipeline: to add jobs to a pipeline:
...@@ -370,208 +360,6 @@ job2: ...@@ -370,208 +360,6 @@ job2:
- echo "It also runs for merge requests." - echo "It also runs for merge requests."
``` ```
## Specify when jobs run with `only` and `except`
NOTE:
`only` and `except` are not being actively developed. [`rules`](#specify-when-jobs-run-with-rules)
is the preferred keyword to control when to add jobs to pipelines.
You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except)
to control when to add jobs to pipelines.
- Use `only` to define when a job runs.
- Use `except` to define when a job **does not** run.
### `only:refs` / `except:refs` examples
You can use `only` or `except` with:
- Specific keywords. See the full list in the [`only`/`except` syntax reference](../yaml/index.md#onlyrefs--exceptrefs).
- Branch names. Avoid branch names that are exactly the same as a specific keyword.
For example, jobs configured to run for the `tags` keyword (tag pipelines)
would also run for a branch named `tags`.
- Regex patterns to specify a range of branch names.
The following examples omit `refs` because `only` or `except` used without `refs`
is the same as [`only:refs` / `except/refs`](../yaml/index.md#onlyrefs--exceptrefs).
For example:
```yaml
job:
# use special keywords
only:
- tags
- triggers
- schedules
```
In this example, `job` runs only for:
- Git tags
- [Triggers](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines)
- [Scheduled pipelines](../pipelines/schedules.md)
To execute jobs only for the parent repository and not forks:
```yaml
job:
only:
- branches@gitlab-org/gitlab
except:
- main@gitlab-org/gitlab
- /^release/.*$/@gitlab-org/gitlab
```
This example runs `job` for all branches on `gitlab-org/gitlab`,
except `main` and branches that start with `release/`.
### `only: variables` / `except: variables` examples
You can use [`except:variables`](../yaml/index.md#onlyvariables--exceptvariables) to exclude jobs based on a commit message:
```yaml
end-to-end:
script: rake test:end-to-end
except:
variables:
- $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
```
You can use [parentheses](#group-variable-expressions-together-with-parentheses) with `&&` and `||`
to build more complicated variable expressions:
```yaml
job1:
script:
- echo This rule uses parentheses.
only:
variables:
- ($CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
```
When multiple entries are specified in `only:variables`, the job runs when at least one of them evaluates to `true`.
You can use `&&` in a single entry when multiple conditions must be satisfied at the same time.
### `only:changes` / `except:changes` examples
You can skip a job if a change is detected in any file with a
`.md` extension in the root directory of the repository:
```yaml
build:
script: npm run build
except:
changes:
- "*.md"
```
If you change multiple files, but only one file ends in `.md`,
the `build` job is still skipped. The job does not run for any of the files.
With some configurations that use `changes`, [jobs or pipelines might run unexpectedly](job_troubleshooting.md#jobs-or-pipelines-run-unexpectedly-when-using-changes)
#### Use `only:changes` with merge request pipelines
With [merge request pipelines](../pipelines/merge_request_pipelines.md),
it's possible to define a job to be created based on files modified
in a merge request.
Use this keyword with `only: [merge_requests]` so GitLab can find the correct base
SHA of the source branch. File differences are correctly calculated from any further
commits, and all changes in the merge requests are properly tested in pipelines.
For example:
```yaml
docker build service one:
script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
only:
refs:
- merge_requests
changes:
- Dockerfile
- service-one/**/*
```
In this scenario, if a merge request changes
files in the `service-one` directory or the `Dockerfile`, GitLab creates
the `docker build service one` job.
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 this example, the pipeline might fail because of changes to a file in `service-one/**/*`.
A later commit that doesn't have changes in `service-one/**/*`
but does have changes to the `Dockerfile` can pass. The job
only tests the changes to the `Dockerfile`.
GitLab checks the **most recent pipeline** that **passed**. If the merge request is mergeable,
it doesn't matter that an earlier pipeline failed because of a change that has not been corrected.
When you use this configuration, ensure that the most recent pipeline
properly corrects any failures from previous pipelines.
### Combine multiple keywords with `only` or `except`
If you use multiple keywords with `only` or `except`, the keywords are evaluated
as a single conjoined expression. That is:
- `only` includes the job if **all** of the keys have at least one condition that matches.
- `except` excludes the job if **any** of the keys have at least one condition that matches.
With `only`, individual keys are logically joined by an `AND`. A job is added to
the pipeline if the following is true:
- `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)`
In the following example, the `test` job is only created when **all** of the following are true:
- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `main`.
- The `variables` keyword matches.
- The `kubernetes` service is active on the project.
```yaml
test:
script: npm run test
only:
refs:
- main
- schedules
variables:
- $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/
kubernetes: active
```
With `except`, individual keys are logically joined by an `OR`. A job is **not**
added if the following is true:
- `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)`
In the following example, the `test` job is **not** created when **any** of the following are true:
- The pipeline runs for the `main` branch.
- There are changes to the `README.md` file in the root directory of the repository.
```yaml
test:
script: npm run test
except:
refs:
- main
changes:
- "README.md"
```
## Create a job that must be run manually ## Create a job that must be run manually
You can require that a job doesn't run unless a user starts it. This is called a **manual job**. You can require that a job doesn't run unless a user starts it. This is called a **manual job**.
...@@ -653,7 +441,7 @@ To protect a manual job: ...@@ -653,7 +441,7 @@ To protect a manual job:
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments), 1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
select the environment (`production` in this example) and add the users, roles or groups select the environment (`production` in this example) and add the users, roles or groups
that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
this list can trigger this manual job, as well as GitLab administrators this list can trigger this manual job, and GitLab administrators
who are always able to use protected environments. who are always able to use protected environments.
You can use protected environments with blocking manual jobs to have a list of users You can use protected environments with blocking manual jobs to have a list of users
...@@ -663,8 +451,6 @@ by authorized users. ...@@ -663,8 +451,6 @@ by authorized users.
## Run a job after a delay ## Run a job after a delay
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4.
Use [`when: delayed`](../yaml/index.md#when) to execute scripts after a waiting period, or if you want to avoid Use [`when: delayed`](../yaml/index.md#when) to execute scripts after a waiting period, or if you want to avoid
jobs immediately entering the `pending` state. jobs immediately entering the `pending` state.
...@@ -734,8 +520,6 @@ Test Boosters reports usage statistics to the author. ...@@ -734,8 +520,6 @@ Test Boosters reports usage statistics to the author.
### Run a one-dimensional matrix of parallel jobs ### Run a one-dimensional matrix of parallel jobs
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) in GitLab 13.5.
You can create a one-dimensional matrix of parallel jobs: You can create a one-dimensional matrix of parallel jobs:
```yaml ```yaml
...@@ -753,8 +537,6 @@ You can also [create a multi-dimensional matrix](../yaml/index.md#parallelmatrix ...@@ -753,8 +537,6 @@ You can also [create a multi-dimensional matrix](../yaml/index.md#parallelmatrix
### Run a matrix of parallel trigger jobs ### Run a matrix of parallel trigger jobs
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/270957) in GitLab 13.10.
You can run a [trigger](../yaml/index.md#trigger) job multiple times in parallel in a single pipeline, You can run a [trigger](../yaml/index.md#trigger) job multiple times in parallel in a single pipeline,
but with different variable values for each instance of the job. but with different variable values for each instance of the job.
...@@ -931,7 +713,7 @@ types the variables can control for: ...@@ -931,7 +713,7 @@ types the variables can control for:
- Branch pipelines that run for Git `push` events to a branch, like new commits or tags. - Branch pipelines that run for Git `push` events to a branch, like new commits or tags.
- Tag pipelines that run only when a new Git tag is pushed to a branch. - Tag pipelines that run only when a new Git tag is pushed to a branch.
- [Merge request pipelines](../pipelines/merge_request_pipelines.md) that run for changes - [Merge request pipelines](../pipelines/merge_request_pipelines.md) that run for changes
to a merge request, like new commits or selecting the **Run pipeline** button to a merge request, like new commits or selecting **Run pipeline**
in a merge request's pipelines tab. in a merge request's pipelines tab.
- [Scheduled pipelines](../pipelines/schedules.md). - [Scheduled pipelines](../pipelines/schedules.md).
...@@ -991,25 +773,8 @@ matching only a substring of the tag name or branch name. ...@@ -991,25 +773,8 @@ matching only a substring of the tag name or branch name.
For example, `/^issue-.*$/` is equivalent to `/^issue-/`, For example, `/^issue-.*$/` is equivalent to `/^issue-/`,
while just `/issue/` would also match a branch called `severe-issues`. while just `/issue/` would also match a branch called `severe-issues`.
### `only` / `except` regex syntax
In GitLab 11.9.4, GitLab began internally converting the regexp used
in `only` and `except` keywords to [RE2](https://github.com/google/re2/wiki/Syntax).
[RE2](https://github.com/google/re2/wiki/Syntax) limits the set of available features
due to computational complexity, and some features, like negative lookaheads, became unavailable.
Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html)
are now supported.
From GitLab 11.9.7 to GitLab 14.9, GitLab provided a feature flag to let you
use unsafe regexp syntax. We've fully migrated to RE2 now, and that feature
flag is no longer available.
## CI/CD variable expressions ## CI/CD variable expressions
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/index.md#onlyvariables--exceptvariables)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/index.md#rules)
Use variable expressions to control which jobs are created in a pipeline after changes Use variable expressions to control which jobs are created in a pipeline after changes
are pushed to GitLab. You can use variable expressions with: are pushed to GitLab. You can use variable expressions with:
...@@ -1125,8 +890,6 @@ regex-job2: ...@@ -1125,8 +890,6 @@ regex-job2:
### Join variable expressions together with `&&` or `||` ### Join variable expressions together with `&&` or `||`
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62867) in GitLab 12.0
You can join multiple expressions using `&&` (and) or `||` (or), for example: You can join multiple expressions using `&&` (and) or `||` (or), for example:
- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"` - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
...@@ -1138,9 +901,6 @@ so `&&` is evaluated before `||`. ...@@ -1138,9 +901,6 @@ so `&&` is evaluated before `||`.
#### Group variable expressions together with parentheses #### Group variable expressions together with parentheses
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/238174) in GitLab 13.5.
You can use parentheses to group expressions together. Parentheses take precedence over You can use parentheses to group expressions together. Parentheses take precedence over
`&&` and `||`, so expressions enclosed in parentheses are evaluated first, and the `&&` and `||`, so expressions enclosed in parentheses are evaluated first, and the
result is used for the rest of the expression. result is used for the rest of the expression.
......
doc/ci/yaml/index.md
+ 2
− 13
浏览文件 @ 2ee74dff
...@@ -5513,9 +5513,6 @@ You can use `only` and `except` to control when to add jobs to pipelines. ...@@ -5513,9 +5513,6 @@ You can use `only` and `except` to control when to add jobs to pipelines.
- Use `only` to define when a job runs. - Use `only` to define when a job runs.
- Use `except` to define when a job **does not** run. - Use `except` to define when a job **does not** run.
See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except)
for more details and examples.
#### `only:refs` / `except:refs` #### `only:refs` / `except:refs`
NOTE: NOTE:
...@@ -5532,8 +5529,7 @@ pipeline based on branch names or pipeline types. ...@@ -5532,8 +5529,7 @@ pipeline based on branch names or pipeline types.
**Possible inputs**: An array including any number of: **Possible inputs**: An array including any number of:
- Branch names, for example `main` or `my-feature-branch`. - Branch names, for example `main` or `my-feature-branch`.
- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax) - Regular expressions that match against branch names, for example `/^feature-.*/`.
that match against branch names, for example `/^feature-.*/`.
- The following keywords: - The following keywords:
| **Value** | **Description** | | **Value** | **Description** |
...@@ -5635,10 +5631,6 @@ deploy: ...@@ -5635,10 +5631,6 @@ deploy:
- $STAGING - $STAGING
``` ```
**Related topics**:
- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples).
#### `only:changes` / `except:changes` #### `only:changes` / `except:changes`
`only:variables` and `except:variables` `only:variables` and `except:variables`
...@@ -5656,7 +5648,7 @@ Use `changes` in pipelines with the following refs: ...@@ -5656,7 +5648,7 @@ Use `changes` in pipelines with the following refs:
- `branches` - `branches`
- `external_pull_requests` - `external_pull_requests`
- `merge_requests` (see additional details about [using `only:changes` with merge request pipelines](../jobs/job_control.md#use-onlychanges-with-merge-request-pipelines)) - `merge_requests`
**Keyword type**: Job keyword. You can use it only as part of a job. **Keyword type**: Job keyword. You can use it only as part of a job.
...@@ -5700,9 +5692,6 @@ docker build: ...@@ -5700,9 +5692,6 @@ docker build:
**Related topics**: **Related topics**:
- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples).
- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#require-a-successful-pipeline-for-merge),
you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-merge-request-pipelines).
- [Jobs or pipelines can run unexpectedly when using `only: changes`](../jobs/job_troubleshooting.md#jobs-or-pipelines-run-unexpectedly-when-using-changes). - [Jobs or pipelines can run unexpectedly when using `only: changes`](../jobs/job_troubleshooting.md#jobs-or-pipelines-run-unexpectedly-when-using-changes).
#### `only:kubernetes` / `except:kubernetes` #### `only:kubernetes` / `except:kubernetes`
......
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或