流水线语法与环境变量
分享链接
作者 ：Gitfox
最后编辑：孟笑宇 于 2026-10-23 17:04:55
阅读：12
GitFox 流水线语法手册
version: 1 kind: pipeline spec: stages: - name: build type: ci spec: steps: - name: hello type: run spec: container: image: alpine script: - echo hellospec
spec 是流水线主体，包含以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
inputs |
map | 声明输入参数 |
options |
object | 流水线级选项 |
stages |
array | 阶段列表， |
spec.inputs
声明输入参数，可在表达式中通过 ${{ parameters.<名称> }} 引用。
stage
通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 阶段名称，同一流水线内唯一 |
id |
string | 阶段标识；省略时根据 name/type 自动生成 |
spec |
object | 类型相关配置 |
stage spec
当 type: ci 时，spec 支持：
| 字段 | 类型 | 说明 |
|---|---|---|
steps |
array | 步骤列表， |
envs |
map | 阶段级环境变量 |
platform |
object | 运行平台，支持 os、arch |
runtime |
object | 运行器选择，见下 |
volumes |
array | 声明卷，供步骤通过 mount 挂载 |
runtime：type 为 default（默认）或 agent。使用 agent 时通过 spec.selector 指定调度标签。
runtime: type: agent spec: selector: os: linux arch: amd64platform：
platform: os: linux arch: amd64step
通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 步骤名称 |
id |
string | 步骤标识；省略时根据 name/type 自动生成 |
type |
string | 步骤类型：run、script、plugin、background |
spec |
object | 类型相关配置 |
所有步骤都在工作目录 /gitfox 中执行（background 除外，见下）。
step 类型
run
最常用的步骤类型，在容器中执行一段 shell 脚本。
| 字段 | 类型 | 说明 |
|---|---|---|
container |
string 或 object | 容器定义，见 ， |
script |
string 或 []string | 要执行的 shell 命令 |
privileged |
bool | 是否以特权模式运行 |
脚本始终由 /bin/sh 执行。
- name: test type: run spec: container: image: golang:1.24 pull: always script: - go vet ./... - go test ./...plugin
引用平台中已注册的插件，并传入输入参数。插件在编译前会被展开为其内部的步骤。
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 插件名称 |
uses |
string | 插件名称，优先于 name |
inputs |
map | 插件输入参数 |
内置插件：
| 插件名称 | 说明 | 主要 inputs |
|---|---|---|
scm_git_clone |
Git 克隆 | repository、gitRef、cloneDepth、cloneDir |
build_go |
Go 编译 | goVersion、workspace、compileCommand |
build_maven |
Maven 编译 | jdkVersion、workspace、customCommand |
build_gradle |
Gradle 编译 | workspace、compileCommand |
build_nodejs |
NodeJS 编译 | nodeVersion、workspace、compileCommand |
- name: build type: plugin spec: name: build_go inputs: goVersion: "1.24" compileCommand: go build -o bin/app .container
run 步骤的 container 字段，既可以是镜像字符串，也可以是对象。
| 字段 | 类型 | 说明 |
|---|---|---|
image |
string | 容器镜像 |
pull |
string | 镜像拉取策略：default、always、if-not-exists、never |
container: image: hub.example.com/library/golang:1.24 pull: always简写形式：
container: hub.example.com/library/golang:1.24变量与表达式
流水线中可以使用三种语法：
| 语法 | 求值时机 | 说明 |
|---|---|---|
${{ 表达式 }} |
构建期（容器启动前） | 由流水线引擎求值并写入 YAML |
${{ }} 表达式
${{ }} 中可以使用：
| 表达式 | 说明 |
|---|---|
parameters.<名称> |
读取输入/流水线参数 |
- name: login type: run spec: container: image: docker:24 script: - docker login -u ${{ parameters.username }} -p ${{ parameters.password}} hub.example.com内置环境变量
流水线步骤中可以使用以下由平台注入的环境变量。
系统信息
| 变量 | 说明 |
|---|---|
GITFOX_SYSTEM_PROTO |
平台协议（http/https） |
GITFOX_SYSTEM_HOST |
平台主机 |
GITFOX_SYSTEM_HOSTNAME |
平台主机名 |
GITFOX_SYSTEM_VERSION |
平台版本 |
构建信息
| 变量 | 说明 |
|---|---|
GITFOX_BRANCH |
目标分支 |
GITFOX_SOURCE_BRANCH |
源分支 |
GITFOX_TARGET_BRANCH |
目标分支 |
GITFOX_COMMIT / GITFOX_COMMIT_SHA / GITFOX_COMMIT_AFTER |
当前提交 SHA |
GITFOX_COMMIT_BEFORE |
变更前提交 SHA |
GITFOX_COMMIT_REF |
提交引用 |
GITFOX_COMMIT_BRANCH |
提交所属分支 |
GITFOX_COMMIT_LINK |
提交链接 |
GITFOX_COMMIT_MESSAGE |
提交信息 |
GITFOX_COMMIT_AUTHOR |
提交作者账号 |
GITFOX_COMMIT_AUTHOR_NAME |
提交作者名称 |
GITFOX_COMMIT_AUTHOR_EMAIL |
提交作者邮箱 |
GITFOX_COMMIT_AUTHOR_AVATAR |
提交作者头像 |
GITFOX_BUILD_NUMBER |
构建序号 |
GITFOX_BUILD_PARENT |
父构建序号 |
GITFOX_BUILD_EVENT |
触发事件 |
GITFOX_BUILD_ACTION |
触发动作 |
GITFOX_BUILD_STATUS |
构建状态（失败时为 failure） |
GITFOX_BUILD_DEBUG |
是否调试模式 |
GITFOX_BUILD_CREATED / GITFOX_BUILD_STARTED / GITFOX_BUILD_FINISHED |
创建/开始/结束时间戳 |
GITFOX_BUILD_TRIGGER |
触发者 |
GITFOX_DEPLOY_TO / GITFOX_DEPLOY_ID |
部署目标/部署 ID |
GITFOX_FAILED_STAGES |
失败的 stage 列表（构建失败时） |
Pull Request 事件额外提供：
| 变量 | 说明 |
|---|---|
GITFOX_PULL_REQUEST |
Pull Request 编号 |
GITFOX_PULL_REQUEST_TITLE |
Pull Request 标题 |
Tag 事件额外提供：
| 变量 | 说明 |
|---|---|
GITFOX_TAG |
Tag 名称 |
Stage 信息
| 变量 | 说明 |
|---|---|
GITFOX_STAGE_NAME |
阶段名称 |
GITFOX_STAGE_NUMBER |
阶段序号 |
GITFOX_STAGE_TYPE |
阶段类型 |
GITFOX_STAGE_KIND |
阶段种类 |
GITFOX_STAGE_MACHINE |
执行机器 |
GITFOX_STAGE_OS / GITFOX_STAGE_ARCH / GITFOX_STAGE_VARIANT / GITFOX_STAGE_VERSION |
阶段平台信息 |
GITFOX_STAGE_STATUS |
阶段状态（失败时为 failure） |
GITFOX_STAGE_STARTED / GITFOX_STAGE_FINISHED |
阶段开始/结束时间戳 |
GITFOX_STAGE_DEPENDS_ON |
依赖的阶段 |
GITFOX_CARD_PATH |
卡片输出路径，固定为 /dev/stdout |
GITFOX_FAILED_STEPS |
失败的步骤列表（阶段失败时） |
Step 信息
| 变量 | 说明 |
|---|---|
GITFOX_STEP_NAME |
步骤名称 |
GITFOX_STEP_NUMBER |
步骤序号 |
工作区与运行器
| 变量 | 说明 |
|---|---|
GITFOX_WORKSPACE |
工作区根目录，固定为 /gitfox |
GITFOX_WORKSPACE_BASE |
工作区基础目录 |
GITFOX_WORKSPACE_PATH |
工作区相对路径 |
GITFOX_CUSTOM_ENV |
自定义环境变量文件路径，见 |
GITFOX_EXECUTION_ID |
执行 ID |
GITFOX_STAGE_ID |
阶段 ID |
GITFOX_DOCKER_NETWORK_ID |
阶段 Docker 网络 ID |
GITFOX_DOCKER_VOLUME_ID / GITFOX_DOCKER_VOLUME_PATH |
工作区卷 ID / 宿主机路径 |