devctl

devctl

devctl is a command-line tool designed to streamline development workflows at Giant Swarm. It provides various commands to help manage repositories and generate files.

Installation

Important: We recommend downloading the latest release from our releases page rather than using go install. This ensures you get a properly built binary with:

• Correct version information
• Git commit information for traceability
• Build timestamps
• All necessary build flags
• Generated code and mocks for testing

While go install will work, it won't include this important metadata and may miss generated code that helps with debugging and version tracking.

# Not recommended
go install github.com/giantswarm/devctl/v7@latest

Recommended: Download the latest release from

https://github.com/giantswarm/devctl/releases

Verifying a release

Every release binary is signed in CircleCI with cosign (keyless) and published next to its Sigstore bundle, <asset>.bundle. There is no checksums file: the bundle is what a download verifies against. With cosign v2.4 or later:

VERSION=v8.128.1        # the release to verify
ASSET=devctl-linux-amd64 # devctl-{linux,darwin}-{amd64,arm64}, devctl-windows-{amd64,arm64}.exe

curl -fsSLO "https://github.com/giantswarm/devctl/releases/download/${VERSION}/${ASSET}"
curl -fsSLO "https://github.com/giantswarm/devctl/releases/download/${VERSION}/${ASSET}.bundle"

cosign verify-blob "${ASSET}" \
  --bundle "${ASSET}.bundle" \
  --certificate-identity "https://circleci.com/api/v2/projects/8a2733c3-f425-4856-91cd-ca36104ab8eb/pipeline-definitions/e50b2edc-4a9e-5142-9c1b-c5dcda3e15d6" \
  --certificate-oidc-issuer "https://oidc.circleci.com"

Verified OK means the binary was signed by the release pipeline of the giantswarm/devctl CircleCI project:

• OIDC issuer: https://oidc.circleci.com, CircleCI's OpenID Connect issuer.
• Certificate identity: the CircleCI project and pipeline definition of giantswarm/devctl, https://circleci.com/api/v2/projects/8a2733c3-f425-4856-91cd-ca36104ab8eb/pipeline-definitions/e50b2edc-4a9e-5142-9c1b-c5dcda3e15d6. The certificate also records the source repository (github.com/giantswarm/devctl) and the release tag (refs/tags/<version>).

devctl version update does this verification itself: it downloads the bundle published next to this platform's binary and installs the new binary only when the bundle verifies for a CircleCI build of github.com/giantswarm/devctl (CircleCI issuer, a CircleCI pipeline-definition identity, and the certificate's source repository pinned to giantswarm/devctl). A release without a bundle, or a binary that does not match its signature, is refused and the installed binary stays as it is.

Features

Authentication for the agent-facing commands (devctl auth)

devctl auth login logs in to GitHub (the device flow of the devctl GitHub App, refreshed without a human) and CircleCI (OAuth 2.0 with PKCE and dynamic client registration, a 90-day token) and keeps both tokens in the OS keychain; devctl auth login --muster-only signs in to muster the same way, for the repo commands that call giantswarm-repo-manager through it, and completes the sign-in to the manager; devctl auth status shows the identities, never a token; devctl auth exec -- gh … (or a gh link to devctl first on an agent's PATH) runs gh with the App's short-lived token, never your long-lived gh login. Commands that need a token exit 8 naming devctl auth login when none is usable. See docs/auth.md.

devctl auth login
devctl auth login --muster-only
devctl auth status

Waiting for a pull request's CI (devctl pr wait)

devctl pr wait <owner/repo> <number> blocks until the pull request's head is green as the merge box sees it (the latest run per check, every CircleCI workflow of the head revision, no GitHub Actions run still open or awaiting approval, every required context reported), red, or in a state no CI can turn green (draft, closed, conflicting, behind a strict base), then prints one JSON document and exits 0, 1, 2 (timeout), 3, 4 (a required context never reported), 7 or 8. See docs/pr-wait.md.

devctl pr wait giantswarm/devctl 2277 --timeout 45m --progress

Rerunning failed CircleCI workflows (devctl pr rerun, devctl release rerun)

devctl pr rerun <owner/repo> <number> reruns every failed CircleCI workflow of the pull request head's pipeline from failed, devctl release rerun <owner/repo> <tag> those of a tag's pipeline: the fix for a job that failed on a transient cause, without an empty commit or a new tag. A workflow still running is not rerun (exit 5), a pipeline without a failed job is exit 3. The rerun is started, not waited for (pr wait, release wait wait for it), and takes the devctl auth login CircleCI login granted Write access. See docs/pr-rerun.md.

devctl pr rerun giantswarm/devctl 2277
devctl release rerun giantswarm/devctl v8.123.0

CircleCI pipelines at the job level (devctl ci jobs, devctl ci job, devctl ci rerun)

devctl ci jobs <owner/repo> <pipeline number|id> reads a pipeline at the job level: every workflow run with its jobs, their start and stop times, and for a running job the step it is in and how long ago that step last wrote output, which tells a slow job from a stuck one while the workflow reads running. devctl ci job <owner/repo> <job number> reads one job: its steps with their status and the end of its failed steps' output, why it failed, without the CircleCI UI. devctl ci rerun <owner/repo> <workflow id> [--from-failed] [--cancel] reruns one workflow, once an hour: a second rerun of the workflow's name in the same pipeline within an hour is refused (exit 5), as is a workflow still running unless --cancel cancels it first, the recovery of a stuck one. All take the devctl auth login CircleCI login (Write access for the rerun) and read nothing on GitHub. See docs/ci.md.

devctl ci jobs giantswarm/devctl 3885
devctl ci job giantswarm/devctl 7781
devctl ci rerun giantswarm/devctl f1290c29-9a4b-4e0e-8c6a-0b7d3e5f2a11 --from-failed

Waiting for a release (devctl release wait)

devctl release wait <owner/repo> (<vX.Y.Z> | --pr <n>), the wait pr merge runs after its merge, blocks until every image and chart of the tag is pullable and the tag pipeline is green (a repository's own tag jobs included), and prints one JSON document with the digests. The artifact names come from the sources that define them (the team-file entry for generated CI, the tag pipeline's push jobs for hand-written CI), never from the repository name; the public registry is probed anonymously, the private one with the docker keychain; a failed tag pipeline ends the wait as exit 1 with the failed jobs, a timeout as exit 2 naming what is missing. See docs/release-wait.md for the model, the JSON and the exit codes.

devctl release wait giantswarm/devctl v8.9.0
devctl release wait giantswarm/devctl --pr 2289 --progress

Promoting release candidates (devctl release promote)

devctl release promote (<owner/repo>... | --team <team>) [--dry-run] promotes the latest release candidate of auto-release repositories to a stable release (--version vX.Y.Z-rc.N with one repository promotes that candidate instead: a published pre-release newer than the latest stable release and reachable from the default branch, else failed, on a workflow that takes its version input, else outdated_workflow; the stable tag lands on that candidate's commit, and the candidates cut after it are named in later as not in the release): for each repository (named, or every entry of repositories/<team>.yaml in giantswarm/github whose release model is auto-release) it requires the auto-release workflow of devctl v8.102.0 or later on the default branch, picks the highest vX.Y.Z-rc.N GitHub release newer than the latest stable release, both reachable from the default branch (failed when that candidate is a full release, not a pre-release, as the workflow refuses it), checks that the combined commit status of the candidate's commit is success (or that no status reported), and dispatches zz_generated.auto_release.yaml on the default branch with release-type: stable; the workflow does the promotion, the repository's stable gate (.github/release-gate.custom.sh) among its checks. It then follows each dispatched run until it concludes, at most --follow-timeout (20m; --no-follow returns right after the dispatch): a run that concludes other than success cut no release and is refused, its message naming the run's URL and the errors its failed jobs annotated (the gate's "Stable gate refused"), failedJobs[] the end of each failed job's log, where the gate's own output is; a run still going at the timeout stays dispatched with a warning. The release built from the tag is devctl release wait <owner/repo> vX.Y.Z's. One JSON document with a repositories[] entry per repository (repository, stable, candidate, newestBuilt, later, statusState, state, message, run, failedJobs; newestBuilt, for not_built, is the highest other candidate that is built, to promote with --version instead of waiting), exit 0 when each was dispatched and its run passed or still runs (would_dispatch with --dry-run) or has nothing to promote, 1 when any is not_built, not_auto_release, outdated_workflow, refused or failed, 7 usage, 8 not signed in. Dispatching needs Actions write, which the devctl GitHub App carries: the devctl auth login identity dispatches wherever you may run the workflow yourself, and identity in the document names the token's source and, for the login, its account. A 403 on a dispatch says the token needs Actions write on that repository.

devctl release promote --team team-bumblebee --dry-run
devctl release promote giantswarm/devctl giantswarm/klaus --progress
devctl release promote giantswarm/devctl --version v1.2.3-rc.14

Waiting for a rollout (devctl rollout wait)

devctl rollout wait <installation> <owner/repo> (<vX.Y.Z> | --pr <n>) runs the release wait, then blocks until every Flux HelmRelease and App CR on the installation's management cluster that deploys one of the release's charts runs the version, is ready and has its Deployments, StatefulSets and DaemonSets rolled out. It reads the cluster through the kube context tsh kube login writes, as you; --reconcile asks Flux to look now. A deployment pinned elsewhere is reported and warned about; a failed install or upgrade of the version is exit 1, a timeout exit 2 naming what is missing. See docs/rollout-wait.md.

devctl rollout wait myinstallation giantswarm/app-operator v7.5.4 --progress

Merging a pull request (devctl pr merge)

devctl pr merge <owner/repo> <number> is the one call an agent makes to land its own pull request: it runs the wait of pr wait, squash-merges the pull request (--rebase for a rebase merge, the default on a fork line, whose team-file entry lists the fork flavour, where --squash squashes; a merge commit where the repository allows only that) through the merge API with the judged head as the expected head, deletes the branch through the refs API, and then runs the wait of release wait --pr on the merge commit until the release is pullable (--release-timeout, 30 minutes by default; --no-release-wait ends at the merge). A base with a merge queue is enqueued and waited for instead of merged. A merge that no release follows (a repository that does not tag merge commits, an auto-release run that tagged nothing) is exit 0. Refused before any wait: a draft, closed or conflicting pull request and one behind its base, strict or not, whose checks ran against an older base (exit 3; --update-branch updates it and waits for the new head); a base that moved during the wait is compared again before the merge, with the same rule, another human's pull request and a repository whose team-file entry says agentMerge: false (exit 5). A reviewer's COMMENTED or CHANGES_REQUESTED review or comment newer than the head that the author has not answered refuses it too (exit 5), read before the wait and again right before the merge. No protection setting is read to be changed or written: the merge is made as you, through the bypass the repository's ruleset grants its owning team and its admins. One JSON document (pr wait's fields plus mergeCommitSha, mergedBy, method, branchDeleted, enqueued, unansweredReviews and release), exit 0, 1, 2, 3, 4, 5, 7 or 8, and after a merge 6 (the release failed) or 9 (the release not confirmed). --detach starts the same merge in a process of its own and returns within seconds with a handle; devctl pr merge status <handle> reads its outcome later, with the merge's exit code, and --on-done <command> runs a command when it ended. See docs/pr-merge.md.

devctl pr merge giantswarm/devctl 2278 --timeout 45m --progress

The agent-facing commands as MCP tools (devctl serve)

devctl serve serves the agent-facing commands as MCP tools over streamable HTTP at /mcp: pr_wait, pr_merge, pr_merge_status and release_wait (and release_promote with --release-promote), the read-only ones with the MCP read-only annotation. A tool answers the command's JSON document as structured content, exit code included; the call is an MCP error only for auth_required. A wait is one call kept alive by notifications/progress on the caller's progressToken, which a gateway such as muster takes to restart its timeout; a wait without one answers within --no-progress-timeout (20s) with the verdict it reached, timeout while still pending, for the caller to call again. The server acts on GitHub as the person who calls it, with the token handed to it for them, and has no version gate, keychain, on-disk state, SIGHUP handling or DEVCTL_TIME_SCALE. See docs/serve.md.

Repository set-up (devctl repo)

Giant Swarm repositories are declared in the team files of giantswarm/github; the reconciler keeps them as declared. devctl repo create creates a repository as you, pushes its scaffold and opens the team-file pull request; the other verbs are giantswarm-repo-manager's tools called through muster as you (devctl auth login --muster-only first): list, get, refresh, status, sweep, watch, adopt, update, transfer, set-lifecycle, approve, align, each with --dry-run where it writes and -o json for the manager's answer. See docs/repo.md.

devctl repo create --team bumblebee --name my-service --component-type service --flavour app --language go --description "What it does"
devctl repo watch my-service --pull-request 4711
devctl repo list --scope unassigned --inactive-days 365
devctl repo set-lifecycle old-tool archived --reason "replaced by new-tool" --dry-run

Reserving an MC for a branch (devctl reservation)

devctl reservation deploys the dev builds of your branch of an app to one management cluster for a limited time, then puts the normal release back. It only commits to the GitOps repo and lets Flux apply it, so it works the same from a laptop and from CI. See docs/reservation.md.

devctl reservation reserve --cluster graveler --app hello-world --branch fix/crash --pull-request giantswarm/hello-world#123 --user alice
devctl reservation list --cluster graveler
devctl reservation release --pull-request giantswarm/hello-world#123 --user alice

Running Tests

make test

The suite includes the end-to-end scenarios under e2e/: the built binary against in-process mocks of GitHub, CircleCI and the registry, one directory per known incident. See e2e/README.md for the format and how to add one.

Debug Mode

Pass --log-level debug to see detailed output and the stack trace of an error:

devctl --log-level debug repo status my-service

License

devctl is licensed under the Apache 2.0 License.