gocd

使用 orbit CLI 管理 GoCD

通过 orbit CLI 全面管理 GoCD，涵盖流水线、流水线组、Agent、环境、配置仓库、服务器管理、用户、角色、授权、插件、备份、材料、制品存储、弹性 Agent 配置文件、集群配置文件、阶段、作业、服务器配置、模板、软件包、软件包仓库、通知筛选器、仪表板、访问令牌、密钥配置和服务器版本。通过 REST API 支持可自托管的 GoCD 实例，并支持多配置文件和 1Password 密钥解析。

前置条件

1. 已安装 orbit CLI——如果运行 which orbit 失败，请通过以下方式安装：
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（脚本）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. 在 ~/.config/orbit/config.yaml 中配置了 gocd 服务的配置文件
3. 有效凭据（API 令牌或基本身份验证）——可存储为 1Password（op://）或 Infisical（infisical://）引用
4. 必须设置 base_url（GoCD 始终为自托管）

快速参考

所有命令均遵循以下格式：orbit -p <profile> gocd <command> [flags]

别名：orbit -p <profile> cd <command> [flags]

所有命令均支持 -o json 和 -o yaml 结构化输出。完整命令详情和所有标志请参阅 references/commands.md。

对于使用自签名证书的自托管实例，请在服务配置中添加 tls_skip_verify: true。如需通过代理访问，请添加 proxy: socks5://host:port。

兼容 GoCD 25.x。 所有 API 版本均已根据 api.gocd.org/25.1.0 验证。主要兼容性说明：

• 仪表板会自动处理 v4 格式（GoCD 25.x：流水线名称为字符串）和较旧格式（对象嵌套在组内）。
• Agent 列表/获取可处理 free_space 为数字或 "unknown" 字符串的情况，以及 environments 为 []string 或 [{"name":"..."}] 对象（v7 格式）的情况。
• 流水线实例（pipeline get --counter N）采用三种策略回退：现代路径、旧版路径，然后提取历史记录——即使服务器因权限限制实例 API，也能正常工作。
• 作业日志在返回 404 时会显示实际阶段/作业名称，无需另外查找正确的作业名称。

命令组

分组	别名	描述
pipeline		Pipeline 的增删改查、状态、历史记录、触发、暂停/取消暂停、评论、导出、比较、锁定/解锁
pipeline-group	pg	Pipeline 组的增删改查
agent		Agent 列表、获取、启用、禁用、删除、终止任务、更新、作业历史
environment	env	环境的增删改查、修补
config-repo	cr, configrepo	配置仓库的增删改查、状态、触发、定义、预检
server		服务健康状态、维护模式
server-config	sc	站点 URL、制品配置、作业超时、邮件服务
user		用户的增删改查、批量删除、当前用户
role		安全角色的增删改查
authorization	auth-config	授权配置的增删改查
plugin		插件信息、设置的增删改查
backup		备份配置的增删改查、计划
material		材料列表、获取、使用情况、触发更新
artifact		制品存储的增删改查
cluster-profile	cp	弹性 Agent 集群配置文件的增删改查
elastic-agent-profile	eap	弹性 Agent 配置文件的增删改查、使用情况
stage		取消阶段、运行阶段
job		作业运行、控制台日志（包含 404 作业名称提示）、制品列表/下载
encrypt		加密值
template	tmpl	Pipeline 模板的增删改查
package-repo	pkg-repo	软件包仓库的增删改查
package	pkg	软件包的增删改查、使用情况
notification-filter	nf	通知筛选器的增删改查
dashboard		仪表板概览
version		服务版本信息
access-token	token	访问令牌的增删改查（用户和管理员）
secret-config	secret	密钥配置的增删改查

核心工作流

Pipeline 增删改查

# List all pipelines by group
orbit -p myprofile gocd pipeline list

# List only the pipelines in one group
orbit -p myprofile cd pipeline list --group my-group

# Create a pipeline from file (the group is auto-created if it doesn't exist)
orbit -p myprofile cd pipeline create --group my-group --from-file pipeline.yaml

# Create a large pipeline: raise the HTTP timeout and wait for it to register
# server-side (survives a client-side timeout where the server still accepted it)
orbit --timeout 5m -p myprofile cd pipeline create --group my-group --from-file pipeline.json --wait --wait-timeout 5m

# Create while cloning secure (encrypted) env vars from an existing pipeline
orbit -p myprofile cd pipeline create --group my-group --from-file pipeline.json --include-creds-from d1epap-deploy-v2

# Update a pipeline configuration (secure env vars like TF_VAR_db_password are preserved)
orbit -p myprofile cd pipeline update my-pipeline --from-file pipeline.yaml

# Safe round-trip: export config, edit, re-import (encrypted_value preserved)
orbit -p myprofile cd pipeline config my-pipeline -o json > pipeline.json
orbit -p myprofile cd pipeline update my-pipeline --from-file pipeline.json

# Copy secure env vars (e.g. Nexus creds) from one pipeline to another
orbit -p myprofile cd pipeline copy-env d1epap-deploy-v2 my-pipeline NEXUS_USERNAME NEXUS_PASSWORD

# Diff the live config against a checked-in file (catches "edited but never re-registered")
orbit -p myprofile cd pipeline diff my-pipeline --against-file pipeline.json

# Delete a pipeline (prompts in a terminal; use --yes in scripts/CI)
orbit -p myprofile cd pipeline delete my-pipeline --yes

# Check pipeline status
orbit -p myprofile cd pipeline status my-pipeline

# View pipeline run history
orbit -p myprofile gocd pipeline history my-pipeline --limit 5

# Get a specific pipeline instance
orbit -p myprofile gocd pipeline get my-pipeline --counter 42

# Get pipeline admin config (materials, stages, env vars)
orbit -p myprofile cd pipeline config my-pipeline
orbit -p myprofile cd pipeline config my-pipeline -o json

# Trigger a pipeline run (no overrides)
orbit -p myprofile cd pipeline trigger my-pipeline

# Trigger with per-run env var overrides (e.g. secret rotation, version pinning)
orbit -p myprofile cd pipeline trigger my-pipeline --env VERSION=1.2.3 --env REGION=us-east-1

# Trigger with a secure env var (value encrypted server-side)
orbit -p myprofile cd pipeline trigger my-pipeline --env "DB_PASS=s3cret" --secure-env DB_PASS

# Pin a material to a specific revision
orbit -p myprofile cd pipeline trigger my-pipeline --material abc123=a2d23c5

# Pause/unpause a pipeline
orbit -p myprofile gocd pipeline pause my-pipeline --reason "Maintenance window"
orbit -p myprofile gocd pipeline unpause my-pipeline

# Comment on a pipeline instance
orbit -p myprofile cd pipeline comment my-pipeline --counter 42 --message "Deployed to staging"

# Export pipeline configuration
orbit -p myprofile cd pipeline export my-pipeline --plugin-id yaml.config.plugin

# Compare two pipeline instances
orbit -p myprofile cd pipeline compare my-pipeline --from 1 --to 5

# Lock/unlock a pipeline
orbit -p myprofile gocd pipeline lock my-pipeline
orbit -p myprofile gocd pipeline unlock my-pipeline

Pipeline 组管理

# List pipeline groups
orbit -p myprofile gocd pipeline-group list
orbit -p myprofile cd pg list

# Get pipeline group details (names only)
orbit -p myprofile cd pg get my-group

# Get the group with every pipeline's full config in one call (no per-pipeline loop)
orbit -p myprofile cd pg get my-group --include-config -o json

# Create/update/delete pipeline groups
orbit -p myprofile cd pg create --from-file group.yaml
orbit -p myprofile cd pg update my-group --from-file group.yaml
orbit -p myprofile cd pg delete my-group

Agent 管理

# List all agents
orbit -p myprofile gocd agent list

# View agent details
orbit -p myprofile cd agent get <uuid>

# Enable/disable agents
orbit -p myprofile gocd agent enable <uuid>
orbit -p myprofile gocd agent disable <uuid>

# Update agent configuration
orbit -p myprofile cd agent update <uuid> --from-file agent.yaml

# View agent job history
orbit -p myprofile cd agent job-history <uuid>

# Kill running tasks on an agent
orbit -p myprofile cd agent kill-task <uuid>

# Delete an agent
orbit -p myprofile gocd agent delete <uuid>

环境管理

# List environments
orbit -p myprofile gocd environment list

# View environment details
orbit -p myprofile cd env get production

# Create environment with pipelines
orbit -p myprofile gocd environment create staging --pipeline my-app --pipeline my-api

# Update environment from file
orbit -p myprofile cd env update staging --from-file env.yaml

# Patch environment (add/remove pipelines and agents)
orbit -p myprofile cd env patch staging --add-pipeline my-app --remove-pipeline old-app --add-agent agent1

# Delete environment
orbit -p myprofile gocd environment delete staging

配置仓库操作

# List config repos
orbit -p myprofile gocd cr list

# Get config repo details
orbit -p myprofile cd cr get my-repo

# Create/update/delete config repos
orbit -p myprofile cd cr create --from-file repo.yaml
orbit -p myprofile cd cr update my-repo --from-file repo.yaml
orbit -p myprofile cd cr delete my-repo

# Check sync status
orbit -p myprofile cd cr status my-repo

# Trigger config repo update
orbit -p myprofile cd cr trigger my-repo

# View definitions from a config repo
orbit -p myprofile cd cr definitions my-repo

# Run preflight check
orbit -p myprofile cd cr preflight --plugin-id yaml.config.plugin --from-file pipeline.yaml

用户管理

# List users
orbit -p myprofile gocd user list

# Get user details
orbit -p myprofile cd user get admin

# Create/update/delete users
orbit -p myprofile cd user create --from-file user.yaml
orbit -p myprofile cd user update admin --from-file user.yaml
orbit -p myprofile cd user delete admin

# Bulk delete users
orbit -p myprofile cd user delete-bulk --user user1 --user user2

# View current authenticated user
orbit -p myprofile cd user current

# Update current user
orbit -p myprofile cd user update-current --from-file user.yaml

安全：角色与授权

# List roles
orbit -p myprofile gocd role list

# CRUD roles
orbit -p myprofile cd role get my-role
orbit -p myprofile cd role create --from-file role.yaml
orbit -p myprofile cd role update my-role --from-file role.yaml
orbit -p myprofile cd role delete my-role

# List authorization configs
orbit -p myprofile cd auth-config list

# CRUD authorization configs
orbit -p myprofile cd auth-config get my-auth
orbit -p myprofile cd auth-config create --from-file auth.yaml
orbit -p myprofile cd auth-config update my-auth --from-file auth.yaml
orbit -p myprofile cd auth-config delete my-auth

插件管理

# List plugins
orbit -p myprofile gocd plugin list

# Get plugin info
orbit -p myprofile cd plugin get my-plugin-id

# Plugin settings CRUD
orbit -p myprofile cd plugin get-settings my-plugin-id
orbit -p myprofile cd plugin create-settings --from-file settings.yaml
orbit -p myprofile cd plugin update-settings my-plugin-id --from-file settings.yaml

备份管理

# View backup configuration
orbit -p myprofile gocd backup get-config

# Create/delete backup config
orbit -p myprofile cd backup create-config --from-file backup.yaml
orbit -p myprofile cd backup delete-config

# Schedule a backup
orbit -p myprofile cd backup schedule

材料操作

# List materials
orbit -p myprofile gocd material list

# Get material details
orbit -p myprofile cd material get <fingerprint>

# View material usage (which pipelines use it)
orbit -p myprofile cd material usage <fingerprint>

# Trigger material update check
orbit -p myprofile cd material trigger-update <fingerprint>

制品存储管理

# List artifact stores
orbit -p myprofile gocd artifact list-store

# CRUD artifact stores
orbit -p myprofile cd artifact get-store my-store
orbit -p myprofile cd artifact create-store --from-file store.yaml
orbit -p myprofile cd artifact update-store my-store --from-file store.yaml
orbit -p myprofile cd artifact delete-store my-store

弹性 Agent 基础设施

# Cluster profiles
orbit -p myprofile cd cp list
orbit -p myprofile cd cp get my-cluster
orbit -p myprofile cd cp create --from-file cluster.yaml
orbit -p myprofile cd cp update my-cluster --from-file cluster.yaml
orbit -p myprofile cd cp delete my-cluster

# Elastic agent profiles
orbit -p myprofile cd eap list
orbit -p myprofile cd eap get my-profile
orbit -p myprofile cd eap create --from-file profile.yaml
orbit -p myprofile cd eap update my-profile --from-file profile.yaml
orbit -p myprofile cd eap delete my-profile
orbit -p myprofile cd eap usage my-profile

阶段与作业操作

# Cancel a running stage
orbit -p myprofile cd stage cancel --pipeline my-pipeline --counter 5 --stage build --stage-counter 1

# Run/re-run a stage
orbit -p myprofile cd stage run --pipeline my-pipeline --counter 5 --stage build

# Run specific jobs in a stage
orbit -p myprofile cd job run --pipeline my-pipeline --stage build --pipeline-counter 5 --stage-counter 1 --job unit-test --job integration-test

# View job console log (if 404, shows valid stage/job names on stderr)
orbit -p myprofile cd job log --pipeline my-pipeline --stage build --job compile --pipeline-counter 42

# View last 50 lines of job log
orbit -p myprofile cd job log --pipeline deploy --stage prod --job deploy-app --pipeline-counter 10 --tail 50

# List the artifacts a job produced
orbit -p myprofile cd job artifacts list --pipeline my-pipeline --stage build --job compile --pipeline-counter 42

# Download a single artifact (use -O / --output to choose the local filename)
orbit -p myprofile cd job artifacts get --pipeline my-pipeline --stage build --job compile --pipeline-counter 42 --path cruise-output/console.log

# Download a whole folder as a .zip (trailing slash on --path)
orbit -p myprofile cd job artifacts get --pipeline my-pipeline --stage build --job compile --pipeline-counter 42 --path dist/ -O dist.zip

# Download every artifact, preserving the directory tree, into ./out
orbit -p myprofile cd job artifacts download --pipeline my-pipeline --stage build --job compile --pipeline-counter 42 --dest ./out

**作业名称提示：**如果 --job 不正确，CLI 会打印 Pipeline 实例中的实际阶段/作业名称，例如 stage=plan jobs=[terraform-plan]（适用于 job log 和 job artifacts）。请先使用 pipeline get <name> --counter N 查找阶段/作业名称。

制品与制品存储：job artifacts 会获取构建生成的文件（由 GoCD 的 /files/... 端点提供）。单独的 artifact 命令用于管理制品存储配置。

服务管理

# Server health
orbit -p myprofile gocd server health

# Maintenance mode
orbit -p myprofile cd server maintenance
orbit -p myprofile cd server maintenance-on
orbit -p myprofile cd server maintenance-off

# Site URLs
orbit -p myprofile cd sc site-url get
orbit -p myprofile cd sc site-url update --url https://gocd.example.com --secure-url https://gocd.example.com

# Artifact config
orbit -p myprofile cd sc artifact-config get
orbit -p myprofile cd sc artifact-config update --from-file artifact.yaml

# Job timeout
orbit -p myprofile cd sc job-timeout get
orbit -p myprofile cd sc job-timeout update --timeout 30

# Mail server
orbit -p myprofile cd sc mail-server get
orbit -p myprofile cd sc mail-server update --from-file mail.yaml
orbit -p myprofile cd sc mail-server delete

# Encryption
orbit -p myprofile gocd encrypt my-secret-password

Pipeline 模板管理

# List templates
orbit -p myprofile gocd template list
orbit -p myprofile cd tmpl list

# Get template details
orbit -p myprofile cd tmpl get my-template

# Create/update/delete templates
orbit -p myprofile cd tmpl create --from-file template.yaml
orbit -p myprofile cd tmpl update my-template --from-file template.yaml
orbit -p myprofile cd tmpl delete my-template

软件包仓库与软件包管理

# List package repositories
orbit -p myprofile gocd package-repo list
orbit -p myprofile cd pkg-repo list

# CRUD package repositories
orbit -p myprofile cd pkg-repo get repo-id
orbit -p myprofile cd pkg-repo create --from-file repo.yaml
orbit -p myprofile cd pkg-repo update repo-id --from-file repo.yaml
orbit -p myprofile cd pkg-repo delete repo-id

# List packages
orbit -p myprofile gocd package list
orbit -p myprofile cd pkg list

# CRUD packages
orbit -p myprofile cd pkg get pkg-id
orbit -p myprofile cd pkg create --from-file package.yaml
orbit -p myprofile cd pkg update pkg-id --from-file package.yaml
orbit -p myprofile cd pkg delete pkg-id

# View package usage (which pipelines use it)
orbit -p myprofile cd pkg usage pkg-id

通知筛选器管理

# List notification filters
orbit -p myprofile gocd notification-filter list
orbit -p myprofile cd nf list

# Get/create/delete notification filters
orbit -p myprofile cd nf get 1
orbit -p myprofile cd nf create --from-file filter.yaml
orbit -p myprofile cd nf delete 1

仪表板与版本

# View dashboard overview
orbit -p myprofile gocd dashboard

# Check server version
orbit -p myprofile gocd version

访问令牌管理

# List your access tokens
orbit -p myprofile gocd access-token list
orbit -p myprofile cd token list

# Create a new token
orbit -p myprofile cd token create --description "CI token"

# Revoke a token
orbit -p myprofile cd token revoke 42 --cause "No longer needed"

# Admin: list all tokens across users
orbit -p myprofile cd token list-all

# Admin: revoke any user's token
orbit -p myprofile cd token revoke-admin 42 --cause "Security review"

密钥配置管理

# List secret configurations
orbit -p myprofile gocd secret-config list
orbit -p myprofile cd secret list

# CRUD secret configurations
orbit -p myprofile cd secret get my-secret
orbit -p myprofile cd secret create --from-file secret.yaml
orbit -p myprofile cd secret update my-secret --from-file secret.yaml
orbit -p myprofile cd secret delete my-secret

常见模式

从文件创建/更新资源

大多数增删改查命令都支持通过 --from-file 输入 YAML 或 JSON：

orbit -p myprofile cd pipeline create --group my-group --from-file pipeline.yaml
orbit -p myprofile cd cr create --from-file config-repo.json
orbit -p myprofile cd role create --from-file role.yaml

基于 ETag 的更新

对于需要乐观锁定的资源（Pipeline、Pipeline 组、环境、配置仓库、角色、授权配置、插件、集群配置文件、弹性 Agent 配置文件、制品存储），CLI 会自动处理 ETag 的获取——只需通过 --from-file 提供更新后的配置。

调整 HTTP 超时（大型 Pipeline POST 请求）

HTTP 客户端默认超时为 15s，对于复杂 Pipeline，可能短于 GoCD 管理 API 的响应延迟。可通过全局 --timeout 标志提高超时时间， 也可以通过 config.yaml 中的 http_timeout，按服务/配置文件持久设置。优先级： --timeout 标志 > 服务 http_timeout > 配置文件 http_timeout > 默认 15s。

orbit --timeout 5m -p myprofile cd pipeline create --group g --from-file p.json --wait

profiles:
  - name: myprofile
    http_timeout: 2m          # default for every service in the profile
    services:
      - name: gocd-prod
        type: gocd
        http_timeout: 5m      # overrides the profile value

转义为原始 curl 请求

如需查看（或复制）orbit 发送的确切请求，请添加 --curl-equivalent（令牌 已隐藏）。添加 --print-token 可包含有效的 bearer 令牌——它会完整打印出来，请谨慎使用。

orbit --curl-equivalent -p myprofile cd elastic-agent-profile list

调试失败的配置仓库

orbit -p myprofile cd cr status my-config-repo
orbit -p myprofile cd cr definitions my-config-repo
orbit -p myprofile cd cr trigger my-config-repo

做好维护准备

orbit -p myprofile cd agent list
orbit -p myprofile cd server maintenance-on
# ... perform maintenance ...
orbit -p myprofile cd server maintenance-off

重要说明

• GoCD API 使用带版本的 Accept 标头——CLI 会自动处理。
• 更新操作使用基于 ETag 的乐观锁定——CLI 会透明地处理。
• 仅当某个配置文件配置了多个 GoCD 服务时，才需要使用 --service 标志。
• 服务配置中必须包含 base_url（GoCD 始终是自托管的）。
• 破坏性操作会立即执行，不会要求确认；但 pipeline delete 除外，它会在交互式终端中提示确认（使用 --yes，或在脚本/CI 中以非交互方式运行，即可跳过提示）。
• 即使服务器已接受请求，大型 pipeline create 操作也可能超过 HTTP 超时时间。使用 --wait（和/或调高 --timeout），让 orbit 轮询分组并报告成功，不受客户端超时影响。如果不使用 --wait，超时错误会提示你通过 pipeline-group get 进行确认。
• 执行 pipeline create 时，如果流水线分组不存在，GoCD 会自动创建——无需先运行 pipeline-group create。
• 输出格式：table（默认）、json、yaml。