gitlab-ci.yml关键字（五）tags 、only 、when

news2025/11/5 0:05:44

only / except

使用only / except 关键字来控制何时创建作业

用于only定义作业何时运行
用于except定义作业何时不运行（除此之外都运行）

only:refs/except:refs

使用only:refs和except:refs关键字来控制何时根据分支名来创建作业

示例

分支名称，例如mainor my-feature-branch。
匹配分支名称的正则表达式/^feature-.*/
以下关键字

value	desc
api	对于由管道 API触发的管道。
branches	当管道的 Git 引用是一个分支时。
chat	对于使用GitLab ChatOps命令创建的管道。
external	当您使用 GitLab 以外的 CI 服务时。
merge_requests	对于创建或更新合并请求时创建的管道。启用合并请求管道、合并结果管道和合并
pipelines	对于使用带有, 或关键字的 API创建的多项目管道。CI_JOB_TOKENtrigger
pushes	对于由事件触发的管道git push，包括分支和标签。
tags	当管道的 Git 引用是tag时。
triggers	对于使用触发器令牌创建的管道。

job1:
  script: echo
  only:
    - main
    - /^issue-.*$/
    - merge_requests

job2:
  script: echo
  except:
    - main
    - /^stable-branch.*$/

如果作业不使用only、except或rules，则默认only设置为branches 和tags。
例如，job1和job2是等价的：

job1:
  script: echo "test"

job2:
  script: echo "test"
  only:
    - branches
    - tags

only:variables/except:variables

only:variables与except:variables可以根据CI/CD中的变量来动态地将作业添加到流水线中。下面的例子就是使用变量来控制作业的运行。

示例

variables:
  TYPE: 'running'

testCode:
  stage: test
  script: 
    - echo "只有在type变量为running时才会运行流水线"
  only:
    variables:
      - $TYPE == 'running'

在这里插入图片描述
使用时可以配置多个only：variables的条件判断，只要有一条符合条件，作业就会被创建到流水线中。

only:changes/except:changes

当 Git push 修改文件时，使用changes关键字来判断是否修改了指定目录/文件下的内容。以此来判断是否新建任务。比如我们一般在修改了src文件下的内容之后才会执行代码扫描。

一些常用的值：

文件路径
个目录的通配符路径，例如path/to/directory/，或一个目录及其所有子目录，例如path/to/directory/**/。
具有相同扩展名或多个扩展名的所有文件的通配符glob路径，例如*.md或path/to/directory/*.{rb,py,sh}.
根目录或所有目录中文件的通配符路径，用双引号引起来。例如".json"或"**/.json"。

testCode:
  stage: test
  script: 
    - echo "只有在分支修改了src文件夹之后才会执行流水线"
  only:
    refs:
      - branches
    changes:
      - src/*

在这里插入图片描述

push_audit:
  stage: test
  except:
    refs:
      - master
  script:
	- echo "当分支是master时不运行，其余场景都运行"

when

使用when来配置作业运行的条件。如果未在作业中定义，则默认值为when: on_success.
一些可能的取值：

on_success（默认）：当早期阶段的所有任务都成功运行或者有配置allow_failure: true.时运行当前任务
manual：在Gitlab UI中手动触发任务
always：无论早期阶段的作业状态如何，都运行作业。也可用于workflow:rules.
on_failure：仅当至少一个早期阶段的作业失败时才运行该作业
delayed：将作业的执行延迟指定的持续时间
never: 不要运行作业。只能在rules节或中使用workflow: rules

示例

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
  environment: production

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

在此示例中，脚本：