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
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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.