gocd

orbit CLI による GoCD

orbit CLI を通じて GoCD を包括的に管理できます。パイプライン、パイプライングループ、エージェント、環境、設定リポジトリ、サーバー管理、ユーザー、ロール、認可、プラグイン、バックアップ、マテリアル、アーティファクトストア、エラスティックエージェントプロファイル、クラスタープロファイル、ステージ、ジョブ、サーバー設定、テンプレート、パッケージ、パッケージリポジトリ、通知フィルター、ダッシュボード、アクセストークン、シークレット設定、サーバーバージョンに対応しています。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：パイプライン名が文字列）と旧形式（グループ内にオブジェクトがネストされる形式）の両方を自動的に処理します。
• エージェントの一覧表示／取得は、free_space が数値または文字列 "unknown" のどちらでも、また environments が []string または [{"name":"..."}] オブジェクト（v7 形式）のどちらでも処理します。
• パイプラインインスタンス（pipeline get --counter N）は、3 つの方法（新しいパス、旧パス、履歴からの抽出）を順に試します。インスタンス API が権限によって制限されているサーバーでも動作します。
• ジョブログは、404 の場合に実際のステージ名／ジョブ名を表示するため、正しいジョブ名を別途調べる必要はありません。

コマンドグループ

グループ	エイリアス	説明
pipeline		パイプラインの CRUD、ステータス、履歴、トリガー、一時停止／再開、コメント、エクスポート、比較、ロック／ロック解除
pipeline-group	pg	パイプライングループの CRUD
agent		エージェントの一覧表示、取得、有効化、無効化、削除、タスクの強制終了、更新、ジョブ履歴
environment	env	環境の CRUD、パッチ適用
config-repo	cr、configrepo	設定リポジトリの CRUD、ステータス、トリガー、定義、事前チェック
server		サーバーのヘルス状態、メンテナンスモード
server-config	sc	サイト URL、アーティファクト設定、ジョブのタイムアウト、メールサーバー
user		ユーザーの CRUD、一括削除、現在のユーザー
role		セキュリティロールの CRUD
authorization	auth-config	認可設定の CRUD
plugin		プラグイン情報、設定の CRUD
backup		バックアップ設定の CRUD、スケジュール
material		マテリアルの一覧表示、取得、使用状況、更新のトリガー
artifact		アーティファクトストアの CRUD
cluster-profile	cp	Elastic エージェントのクラスタープロファイルの CRUD
elastic-agent-profile	eap	Elastic エージェントプロファイルの CRUD、使用状況
stage		ステージのキャンセル、実行
job		ジョブの実行、コンソールログ（404 時のジョブ名ヒント付き）、アーティファクトの一覧表示／ダウンロード
encrypt		値の暗号化
template	tmpl	パイプラインテンプレートの CRUD
package-repo	pkg-repo	パッケージリポジトリの CRUD
package	pkg	パッケージの CRUD、使用状況
notification-filter	nf	通知フィルターの CRUD
dashboard		ダッシュボードの概要
version		サーバーバージョン情報
access-token	token	アクセストークンの CRUD（ユーザーおよび管理者）
secret-config	secret	シークレット設定の CRUD

コアワークフロー

パイプラインの CRUD

# 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

パイプライングループの管理

# 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

エージェントの管理

# 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

Elastic エージェントインフラストラクチャ

# 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 はパイプラインインスタンスの実際のステージ名／ジョブ名を表示します。例：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

パイプラインテンプレートの管理

# 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

共通パターン

ファイルからリソースを作成／更新する

ほとんどの CRUD コマンドは、YAML または JSON 入力に対して --from-file を受け付けます。

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 ベースの更新

楽観的ロックが必要なリソース（パイプライン、パイプライングループ、環境、設定リポジトリ、ロール、認可設定、プラグイン、クラスタープロファイル、Elastic エージェントプロファイル、アーティファクトストア）では、CLI が ETag の取得を自動的に処理します。更新した設定を指定した --from-file を渡すだけです。

HTTP タイムアウトの調整（大規模なパイプラインの POST）

HTTP クライアントのデフォルトのタイムアウトは 15s です。これは、複雑なパイプラインに対する 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

raw curl へのエスケープ

orbit が送信するリクエストの正確な内容を確認（またはコピー）するには、--curl-equivalent を追加します（トークンは伏せられます）。有効なベアラートークンを含めるには --print-token を追加します。この場合、トークンは完全な状態で出力されるため、使用には注意してください。

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 が透過的に処理します。
• --service フラグが必要なのは、プロファイルに複数の GoCD サービスが設定されている場合のみです。
• サービス設定では 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。