README
¶
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 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@latest
Recommended: Download the latest release from
https://github.com/giantswarm/devctl/releases
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 status shows the identities, never a token. Commands that need a token exit 8 naming devctl auth login when none is usable. See docs/auth.md.
devctl auth login
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
Waiting for a release (devctl release wait)
devctl release wait <owner/repo> (<vX.Y.Z> | --pr <n>) blocks until every image and chart of the tag is pullable 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
Repository set-up (devctl repo)
Giant Swarm repositories are declared in the team files of giantswarm/github; the reconciler creates and keeps them as declared. devctl repo create validates a declaration through the engine, prints the dry run and opens the team-file pull request as you; devctl repo status prints a repository's set-up state. 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 status my-service
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
Set LOG_LEVEL=debug to see detailed output:
devctl --log-level debug repo status my-service
Contributing
Please check our contributing guidelines for details on how to contribute to this project.
License
devctl is licensed under the Apache 2.0 License.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
repo/internal/auth
Package auth resolves the GitHub token the repo commands act with: the person's own, so a pull request they open is theirs.
|
Package auth resolves the GitHub token the repo commands act with: the person's own, so a pull request they open is theirs. |
|
repo/internal/engine
Package engine is what the repo commands share to run the set-up steps of pkg/reposetup/reconcile as the person: the clients from the token environment variables, the repository slug, the log adapter and the result on stdout.
|
Package engine is what the repo commands share to run the set-up steps of pkg/reposetup/reconcile as the person: the clients from the token environment variables, the repository slug, the log adapter and the result on stdout. |
|
e2e
|
|
|
mock/circleci
Package circleci mocks the CircleCI API v2 and CircleCI's OAuth issuer on one server: DEVCTL_CIRCLECI_API_URL is the server's URL plus APIPrefix, the path circleci.com serves the API under, and DEVCTL_CIRCLECI_OAUTH_URL is the server's URL.
|
Package circleci mocks the CircleCI API v2 and CircleCI's OAuth issuer on one server: DEVCTL_CIRCLECI_API_URL is the server's URL plus APIPrefix, the path circleci.com serves the API under, and DEVCTL_CIRCLECI_OAUTH_URL is the server's URL. |
|
mock/github
Package github mocks the GitHub REST API and the device-flow endpoints of github.com on one server: DEVCTL_GITHUB_API_URL and DEVCTL_GITHUB_OAUTH_URL both point at it.
|
Package github mocks the GitHub REST API and the device-flow endpoints of github.com on one server: DEVCTL_GITHUB_API_URL and DEVCTL_GITHUB_OAUTH_URL both point at it. |
|
mock/registry
Package registry mocks an OCI distribution registry the way a release's artifacts are probed: HEAD and GET of /v2/<name>/manifests/<reference> for images and for charts (names under charts/).
|
Package registry mocks an OCI distribution registry the way a release's artifacts are probed: HEAD and GET of /v2/<name>/manifests/<reference> for images and for charts (names under charts/). |
|
mock/sequence
Package sequence scripts a mock's answers.
|
Package sequence scripts a mock's answers. |
|
scenario
Package scenario is the format of e2e/scenarios/<slug>/: scenario.yaml (the command line, the environment, the mocks' response sequences) and expected.json (the exit code and the JSON document, "*" for a value the scenario does not pin).
|
Package scenario is the format of e2e/scenarios/<slug>/: scenario.yaml (the command line, the environment, the mocks' response sequences) and expected.json (the exit code and the JSON document, "*" for a value the scenario does not pin). |
|
internal
|
|
|
validate
Package validate constrains the caller-supplied strings that devctl interpolates into filesystem paths, subprocess arguments and URLs.
|
Package validate constrains the caller-supplied strings that devctl interpolates into filesystem paths, subprocess arguments and URLs. |
|
pkg
|
|
|
agentcli
Package agentcli is what devctl's agent-facing commands share: the JSON envelope every one of them prints as its only stdout output, the exit-code table, the clock that DEVCTL_TIME_SCALE speeds up for tests, the endpoint configuration read from the environment and the --progress writer.
|
Package agentcli is what devctl's agent-facing commands share: the JSON envelope every one of them prints as its only stdout output, the exit-code table, the clock that DEVCTL_TIME_SCALE speeds up for tests, the endpoint configuration read from the environment and the --progress writer. |
|
authstore
Package authstore holds the identities devctl's agent-facing commands act with: a GitHub user access token of the devctl GitHub App, obtained with the device flow and refreshed without a human, and a CircleCI API token obtained with the OAuth 2.0 authorization code flow with PKCE after a one-time dynamic client registration per device.
|
Package authstore holds the identities devctl's agent-facing commands act with: a GitHub user access token of the devctl GitHub App, obtained with the device flow and refreshed without a human, and a CircleCI API token obtained with the OAuth 2.0 authorization code flow with PKCE after a one-time dynamic client registration per device. |
|
circleciclient
Package circleciclient is devctl's client for the CircleCI API: the calls the repository set-up engine makes for a project — follow and unfollow and stop building (v1.1), the token's user, the project, its settings and checkout keys, its pipelines (paged) and their workflows and jobs (v2) — and nothing else.
|
Package circleciclient is devctl's client for the CircleCI API: the calls the repository set-up engine makes for a project — follow and unfollow and stop building (v1.1), the token's user, the project, its settings and checkout keys, its pipelines (paged) and their workflows and jobs (v2) — and nothing else. |
|
prwait
Package prwait is the wait engine behind `devctl pr wait` (and the merge that follows it): one bounded, blocking call that returns when a pull request's head is green, red, or cannot become green as it is.
|
Package prwait is the wait engine behind `devctl pr wait` (and the merge that follows it): one bounded, blocking call that returns when a pull request's head is green, red, or cannot become green as it is. |
|
releasewait
Package releasewait waits until a tag's images and charts are pullable: what `devctl release wait` does.
|
Package releasewait waits until a tag's images and charts are pullable: what `devctl release wait` does. |
|
renovate
Package renovate provides helpers to surgically edit Renovate configuration files (renovate.json and renovate.json5) in place, preserving comments, quoting style and key order of the original file.
|
Package renovate provides helpers to surgically edit Renovate configuration files (renovate.json and renovate.json5) in place, preserving comments, quoting style and key order of the original file. |
|
reposetup
Package reposetup is the front half of the repository set-up engine: it reads a team file of giantswarm/github, validates its entries against the repositories schema — and, for the entries about to create a repository, the creation rules — derives the template each repository is scaffolded from and returns the dry-run value the clients render — the team-file entry as it would be written, the implied template, the verdict of the name check and the guard notices.
|
Package reposetup is the front half of the repository set-up engine: it reads a team file of giantswarm/github, validates its entries against the repositories schema — and, for the entries about to create a repository, the creation rules — derives the template each repository is scaffolded from and returns the dry-run value the clients render — the team-file entry as it would be written, the implied template, the verdict of the name check and the guard notices. |
|
reposetup/manager
Package manager is the client of giantswarm-repo-manager, the MCP server behind muster that keeps the repository inventory.
|
Package manager is the client of giantswarm-repo-manager, the MCP server behind muster that keeps the repository inventory. |
|
reposetup/reconcile
Package reconcile is the back half of the repository set-up engine: every set-up step of a declared repository as a check and a repair, run in order by Runner.Run against GitHub and CircleCI, with the outcome as one structured Result the inventory stores.
|
Package reconcile is the back half of the repository set-up engine: every set-up step of a declared repository as a check and a repair, run in order by Runner.Run against GitHub and CircleCI, with the outcome as one structured Result the inventory stores. |