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.
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 installwill 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@latestRecommended: Download the latest release from
https://github.com/giantswarm/devctl/releases
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 statusdevctl 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 --progressdevctl 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
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 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. Both 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 rerun giantswarm/devctl f1290c29-9a4b-4e0e-8c6a-0b7d3e5f2a11 --from-failed
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 --progressdevctl release promote (<owner/repo>... | --team <team>) [--dry-run] promotes the latest release candidate of auto-release repositories to a stable 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. It does not wait for the run; devctl release wait <owner/repo> vX.Y.Z does. One JSON document with a repositories[] entry per repository (repository, stable, candidate, statusState, state, message), exit 0 when each was dispatched (would_dispatch with --dry-run) or has nothing to promote, 1 when any is not_built, not_auto_release, outdated_workflow 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 --progressdevctl 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
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; 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 a strict base (exit 3; --update-branch updates it and waits for the new head), 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 --progressGiant 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-runmake testThe 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.
Pass --log-level debug to see detailed output and the stack trace of an error:
devctl --log-level debug repo status my-servicedevctl is licensed under the Apache 2.0 License.