Gocd

GoCD with orbit CLI

Comprehensive GoCD management through the orbit CLI. Covers pipelines, pipeline groups, agents, environments, config repos, server administration, users, roles, authorization, plugins, backups, materials, artifact stores, elastic agent profiles, cluster profiles, stages, jobs, server configuration, templates, packages, package repositories, notification filters, dashboard, access tokens, secret configs, and server version. Works with self-hosted GoCD instances via the REST API, with multi-profile support and 1Password secret resolution.

Prerequisites

1. orbit CLI installed — if which orbit fails, install with:
   • macOS/Linux (Homebrew): brew install jorgemuza/tap/orbit
   • macOS/Linux (script): 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. A profile with a gocd service configured in ~/.config/orbit/config.yaml
3. Valid credentials (API token or basic auth) - can be stored as 1Password (op://) or Infisical (infisical://) references
4. base_url is required (GoCD is always self-hosted)

Quick Reference

All commands follow the pattern: orbit -p <profile> gocd <command> [flags]

Alias: orbit -p <profile> cd <command> [flags]

All commands support -o json and -o yaml for structured output. For full command details and all flags, see references/commands.md.

For self-hosted instances with self-signed certificates, add tls_skip_verify: true to the service config. For proxy access, add proxy: socks5://host:port.

GoCD 25.x compatible. All API versions verified against api.gocd.org/25.1.0. Key compatibility notes:

• Dashboard handles both the v4 format (GoCD 25.x: pipeline names as strings) and older formats (objects nested inside groups) automatically.
• Agent list/get handles free_space as either a number or "unknown" string, and environments as either []string or [{"name":"..."}] objects (v7 format).
• Pipeline instance (pipeline get --counter N) uses a three-strategy fallback: modern path, legacy path, then history extraction — works even on servers that restrict the instance API by permission.
• Job log prints actual stage/job names on 404 so you don't have to look up the correct job name separately.

Command Groups

Core Workflows

Pipeline 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

Pipeline Group Management

# 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 Management

# 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>

Environment Management

# 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

Config Repo Operations

# 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

User Management

# 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

Security: Roles & Authorization

# 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

Plugin Management

# 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

Backup Management

# 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

Material Operations

# 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>

Artifact Store Management

# 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 Agent Infrastructure

# 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

Stage & Job Operations

# 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 name hint: if --job is wrong, the CLI prints actual stage/job names from the pipeline instance, e.g. stage=plan jobs=[terraform-plan] (applies to job log and job artifacts). Use pipeline get <name> --counter N to discover stage/job names first.

Artifacts vs. artifact stores: job artifacts fetches the files a build produced (backed by GoCD's /files/... endpoint). The separate artifact command manages artifact store configuration.

Server Administration

# 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 Template Management

# 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

Package Repository & Package Management

# 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

Notification Filter Management

# 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

Dashboard & Version

# View dashboard overview
orbit -p myprofile gocd dashboard

# Check server version
orbit -p myprofile gocd version

Access Token Management

# 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"

Secret Configuration Management

# 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

Common Patterns

Create/Update Resources from File

Most CRUD commands accept --from-file for YAML or JSON input:

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-Based Updates

For resources that require optimistic locking (pipelines, pipeline groups, environments, config repos, roles, auth configs, plugins, cluster profiles, elastic agent profiles, artifact stores), the CLI handles ETag retrieval automatically — just provide the --from-file with updated config.

Tuning HTTP Timeout (large pipeline POSTs)

The HTTP client defaults to a 15s timeout, which can be shorter than GoCD's admin API latency for non-trivial pipelines. Raise it with the global --timeout flag, or persist it per service/profile via http_timeout in config.yaml. Precedence: --timeout flag > service http_timeout > profile http_timeout > 15s default.

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

Escaping to raw curl

To see (or copy) the exact request orbit sends, add --curl-equivalent (token redacted). Add --print-token to include the live bearer token — it then prints in full, so use it deliberately.

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

Debug a Failing Config Repo

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

Prepare for Maintenance

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

Important Notes

• GoCD API uses versioned Accept headers — handled automatically by the CLI.
• Update operations use ETag-based optimistic locking — the CLI handles this transparently.
• The --service flag is only needed when a profile has multiple GoCD services configured.
• base_url is required in service configuration (GoCD is always self-hosted).
• Destructive operations execute immediately without confirmation prompts, except pipeline delete, which prompts in an interactive terminal (use --yes, or run non-interactively in scripts/CI, to skip the prompt).
• A large pipeline create can outlast the HTTP timeout even when the server accepts it. Use --wait (and/or raise --timeout) so orbit polls the group and reports success regardless of a client-side timeout. Without --wait, a timeout error prints a hint to verify with pipeline-group get.
• The pipeline group on pipeline create is auto-created by GoCD if it doesn't exist — no need to run pipeline-group create first.
• Output formats: table (default), json, yaml.