The gen command family is designed to create common files in repositories, adapted specifically for the repository flavour and/or programming language used.
Files are written to the current directory. The assumption is that the current working directory is the root directory of a cloned repository.
Usually these commands are executed via automation in the giantswarm/github repository, but this can also be done manually/locally.
Note: the added files are not meant for later editing, as changes would be overwritten by a subsequent devctl execution.
Creates common GitHub actions workflows (for CI/CD) in the .github/workflows directory.
Example:
devctl gen workflows --flavour cli
Repositories can stage exact-commit merge-group validation and then opt into full CI once per protected merge batch. See the batch CI policy and transition for the repository-owned configuration, required queue proof and rollback sequence. Ordinary PR CI remains unchanged until explicitly transitioned.
--release-workflow selects which release flow to generate. Two values:
| Value | What's emitted | When to use |
|---|---|---|
legacy (default) |
.github/workflows/zz_generated.create_release.yaml, zz_generated.create_release_pr.yaml, zz_generated.validate_changelog.yaml. Releases driven by manually-pushed main#release#patch-style branches that open a release PR for human approval. |
The historical flow; in use by most giantswarm repos today. |
auto-release |
.github/workflows/zz_generated.auto_release.yaml and cliff.toml (at repo root). Releases driven by conventional commits on main -- the workflow runs git-cliff --unreleased --bump on every push, computes the next semver, and creates the next release candidate tag + GitHub pre-release atomically. A stable release is a manual promotion of the latest candidate. feat bumps the minor version, a breaking change the major, every other type the patch; ci, chore, docs, style and test commits are skipped and release nothing, except that test: can advance an existing candidate. |
Repos that want push-button releases from conventional commits. Requires semantic_pull_request enforcement on PR titles. |
Switching between values is bidirectional and self-cleaning: the chosen branch generates its own files and emits deletion inputs for the files of the other branch, so a flipped --release-workflow value over two consecutive gen runs leaves the repo with exactly one set of release files.
A repository's release workflow is its declaration in giantswarm/github (gen.ci.releaseWorkflow in its team-file entry), which align-files passes as --release-workflow. Auto Release files added to a repository whose declaration says legacy are deleted again by the next run, so both places name the declaration as the place to change instead: a legacy run that deletes zz_generated.auto_release.yaml or cliff.toml warns on stderr, and the generated zz_generated.validate_changelog.yaml fails a pull request whose head carries either file (job "Release workflow matches the declaration").
A fork line (--flavour fork) gets nothing generated on legacy. On auto-release it gets the release flow alone: the workflow, cliff.toml and the PR title check. --release-branch names the branch the line is consumed from (the declaration's defaultBranch, e.g. giantswarm), and pushes to that branch alone cut releases. A re-pin rebases that branch onto a new upstream commit, which leaves the line's earlier tags unreachable, while the upstream tags the mirror copies stay reachable. So the line counts from its highest stable tag rather than the nearest reachable one, and git-cliff counts only the tags of that tag's major. After a re-pin, the workflow moves that tag onto the commit the branch still shares with it, in its own checkout only, and the next candidate carries what changed since. --maintenance-branches (team file gen.ci.maintenanceBranches: true) adds the line's maintenance branches release-X.Y: each releases patches of its own X.Y series, counted from that series' highest stable tag, so a backported feature is a patch and the next minor stays the consumed branch's. A maintenance branch carries the same rendering as the consumed branch.
devctl gen workflows --flavour app --language go --release-workflow=auto-release
With --language go, the generated Nested Go modules workflow discovers tracked
nested go.mod files, excluding test fixtures, vendored dependencies and hidden
directories. Each module runs independently with GOWORK=off, verifies that
go mod tidy leaves its dependencies unchanged, and runs race tests and vet.
The repository's existing root-module checks remain responsible for the root.
After the module changes land, dispatch zz_generated.nested_go_modules.yaml
on the configured release branch with module=k8s and version=v0.1.0 to publish
k8s/v0.1.0. Publication waits for all nested modules to pass and checks that the
selected directory declares the expected repository module path and major version.
An existing tag is accepted only when it points to that same commit. Module
releases use directory-prefixed tags and never become the repository's latest
release. These are source releases: GITHUB_TOKEN does not trigger a subsequent
tag pipeline, so image or chart publication needs its existing release workflow.
Every releasable push releases the version git-cliff computes from the conventional commits since the last stable release. A minor or major version is cut as the next release candidate, vX.Y.0-rc.N; a patch of the last stable release (for example, only fixes since it) is the fast path and is tagged vX.Y.Z stable on its push, so there is never a patch candidate:
Merge (after v1.2.9) |
Tag | Why |
|---|---|---|
fix: x |
v1.2.10 |
a patch of the last stable release, tagged stable on its push |
feat: add x |
v1.3.0-rc.1 |
a feat puts the cycle on the next minor |
fix: y |
v1.3.0-rc.2 |
a fix during a cycle rides its next candidate |
chore(deps): bump y |
none | chore is skipped |
ci(tools): bump y |
none | ci is skipped |
test: fix a failing test |
v1.3.0-rc.3 |
a test fix can replace an existing candidate |
docs: fix a typo |
none | docs is skipped, so there is nothing new to put in a candidate |
refactor!: drop y |
v2.0.0-rc.1 |
a breaking change moves the target, and the series restarts at rc.1 |
The first release of a repository with no stable tag is a candidate. On a maintenance branch (release-v3.x, a fork line's release-X.Y) every release is a patch of its series, so it is tagged stable on its push. A patch candidate cut before this rule is released by the next releasable push as its stable version.
--patch-candidates (team file gen.ci.patchCandidates: true) drops the fast path: a patch is cut as a candidate too, v1.2.10-rc.1 for fix: x above and v1.2.10-rc.2 for the next fix, on the default branch and on a maintenance branch alike, so no push tags a stable release. It is for a repository whose consumers follow a semver range that takes its next patch on their own (>=1.17.0 <1.18.0): every stable release is then a promotion of a candidate proven first. A maintenance branch's candidate is promoted on that branch, devctl release promote <owner/repo> --branch release-X.Y --version vX.Y.Z-rc.N.
A push whose commits git-cliff all skips (ci, chore, docs, style, test) or drops as non-conventional tags nothing, except that a conventional test: commit after an existing candidate for the computed version cuts the next candidate. This lets a test fix replace a red candidate without depending on its pipeline status; it also applies when that candidate is green. Tests remain excluded from the version bump and release notes, and a test-only push with no pending candidate cuts nothing. Docs, style, ci and chore still cannot spend an rc number and a publish pipeline. A candidate is flagged as a GitHub pre-release, so it does not surface as the repo's "Latest release", and the /^v.*/ CircleCI tag filter publishes it like any other tag.
Use fix or feat for a dependency or build change that needs its own release. A ci, chore or docs change waits for the next releasable commit, including on fork lines.
The single-version Auto-release workflow creates its tags and GitHub releases with a short-lived installation token of the giantswarm-release GitHub App, so a repository's GitHub Actions workflows listening on push.tags (for example v*) or release can run for candidates and stable releases. The App must be installed on the consuming repository with Contents: write and Workflows: write, and RELEASE_BOT_CLIENT_ID and RELEASE_BOT_PRIVATE_KEY must be available as Actions secrets. The token is scoped to that repository and minted only when a tag was selected, after the release guards pass. A stable promotion's token also asks for Workflows write: it tags the candidate's commit, and GitHub refuses the App that tag when .github/workflows changed on the branch since. Candidates and auto releases tag the branch head with Contents write alone. Missing or unusable App credentials fail the job before a tag or release is created; there is no fallback to GITHUB_TOKEN, whose tag pushes and release events do not start workflows. Checkout, release-note lookups and CircleCI verification keep using the workflow's own read-only token. Existing repositories need the regenerated workflow; a tag already created with GITHUB_TOKEN gains no run retroactively. The separate multi-image workflow still uses GITHUB_TOKEN and relies on CircleCI for tag builds.
A job of the repository's own that must not see a candidate, in a hand-written pipeline or in .circleci/custom.yml, filters on stable tags before the repository moves to auto-release. The krew index update of a CLI is one: krew-release-bot refuses a GitHub pre-release, so a /^v.*/ filter turns the first candidate's pipeline red.
Before moving a hand-written CircleCI pipeline to RC promotion, review the architect orb < 10 inventory and bump queue, including the build-context and branch-publishing checks.
workflows:
release:
jobs:
- update-krew-index:
filters:
branches:
ignore: /.*/
tags:
only: /^v\d+\.\d+\.\d+$/A stable minor or major release is cut only by running the workflow by hand with release-type: stable. It promotes the latest candidate since the last stable release, or the one its version input names (vX.Y.Z-rc.N, one of those candidates: one built while a later one still builds, or the one proven; any other tag fails the run): the workflow checks that candidate out, so the version, the release notes and the tag's commit are all the candidate's, and whatever merged after it waits for the next candidate. The run fails when there is no candidate to promote, when the candidate has no GitHub pre-release (the run that cut it did not finish), or when a commit status of its commit failed or is still pending (the pipelines that build and publish it report there). A failed ci/circleci: sync-china-registry, the in-China mirror the release does not require, is a warning on the run, not a refusal, as in devctl release wait and devctl release promote. Only commit statuses count, which CircleCI writes; a GitHub Actions workflow of the repository's own that publishes on a tag reports check runs, and the promotion does not wait for it. A repository's own rules for a stable release go in .github/release-gate.custom.sh: when the released commit carries it (the promoted candidate, or a patch push's head), the run executes it with bash on that checkout, with the version about to be tagged as its argument, after the version is decided and before the tag and the GitHub release are created; a non-zero exit fails the run and cuts neither. A repository without the script has no gate. A check in the tag's own pipeline runs after the release exists, so a refusal there leaves a release that looks published with nothing built. One commit releases one version: every run that is about to tag, a candidate or a stable, first reads the remote's tags, and when the commit already carries the release tag (vX.Y.Z, vX.Y.Z-rc.N) of another version the run fails naming both and cuts no tag and no release. A stable on its own candidate's commit is the same version and passes; a tag outside that pattern (an upstream pre-release) counts for nothing. release-type: auto applies the same rule as a push. A stable run queued behind a push run waits in the branch's concurrency group, where GitHub keeps one waiting run: a further push replaces it, and the promotion has to be started again.
Existing repositories need regenerated files to stop ci and chore commits from
releasing. The template fix ships in devctl v8.166.0.
Upgrading the generator alone does not update a repository's checked-in cliff.toml.
Use that version or newer through the repository's Align files automation, or rerun
devctl gen workflows --release-workflow=auto-release with its existing flavour,
language and release options. Preserve the fork's --release-branch,
--maintenance-branches and --patch-candidates settings where enabled.
Merge the generated cliff.toml and workflow changes through a pull request.
In the generated cliff.toml, these entries in [git].commit_parsers must have
skip = true:
{ message = "^docs", skip = true },
{ message = "^chore", skip = true },
{ message = "^ci", skip = true },These are entries from the array, not a replacement for the whole configuration.
Assigning a commit to Changed or another changelog group still counts it toward
a release. Plain and scoped subjects, such as ci: update tooling and
ci(deps): update tooling, are both skipped.
To verify adoption, inspect the Auto-release run for a subsequent ci, chore or
docs merge when no releasable commits are waiting. Its Decide whether to tag
step should report No releasable commits since <version>; skipping tag., naming
the last stable release or the existing candidate. Create release (and the tag,
atomically) should be skipped. A green run alone does not prove that nothing
released. A push that also includes pending fix or feat commits can still
release those changes; the skipped commits ship with them without affecting the
version or release notes.
On auto-release the GitHub Releases are the changelog. Each release's notes are git-cliff's grouping of the pull request titles merged since the previous release (the squash commit subjects), so the pull request title is the entry and nothing writes CHANGELOG.md: no changelog commit or PR after a release, no changelog check, and no conflict between parallel pull requests on the file.
gen workflows on auto-release freezes an existing CHANGELOG.md as a pointer at https://github.com/giantswarm/<repo>/releases; its earlier entries stay in the git history and in the file at every earlier tag. It also drops a checklist item asking for a changelog edit from the repository's .github/pull_request_template.md, with its heading when the item was all the section held, keeping the rest of the template. A repository without either file gets none. A multi-image repository and a fork line keep their CHANGELOG.md as it is: the first releases each image on its own tag, the second carries upstream's file.
devctl release create reads a component's changes from its CHANGELOG.md at the tag, and from its GitHub Releases when that file has no section for the version or the tag has no CHANGELOG.md: the notes of every release after the previous version up to the new one, its pre-releases left out, since the stable release carries their notes; a component new in the release gets the notes of its own release. Any other failure to read the file fails the command, as before. A note's [**breaking**] bullet is listed under the breaking changes.
cliff.toml's [remote.github].repo is read from the consuming repo's origin git remote URL, its giantswarm/<repo> path. A checkout with no origin remote, or one outside giantswarm, needs --repo-name <repo> instead; without either the command fails rather than silently writing repo = "".
After a successful promotion, the workflow fetches the release branch again. If it has commits after the promoted
candidate, it dispatches release-type: auto on that branch, in the same concurrency group, before verifying the
stable tag's CircleCI build. The queued run uses the new stable as its baseline: features open the next minor
candidate, fixes take the normal patch path (a candidate with --patch-candidates), and skipped commits tag nothing.
No additional user push is needed. A failed stable gate queues nothing. If the branch head already carries an RC
of the just-promoted version, catch-up opens a release-preparation PR instead of dispatching onto that conflicting
commit. The PR updates .github/release-catch-up with the stable tag and the head it resumes, and arms squash
auto-merge. Its docs(release): title is skipped by git-cliff, so preparation alone spends no version.
Its merge supplies a new commit and triggers auto-release; the one-version-per-commit guard stays in
force. Other branch heads use the direct dispatch path. Retries reuse the preparation branch and PR; a closed,
unmerged preparation PR fails with its URL rather than silently dropping catch-up.
The preparation path uses the existing giantswarm-release App (RELEASE_BOT_CLIENT_ID and
RELEASE_BOT_PRIVATE_KEY, Contents and Pull requests write). Repository auto-merge and the release App's
review-rule bypass must be enabled by repository reconciliation (--release-app-id); required checks still gate
the PR. Missing App credentials, a refused push/PR/auto-merge, or failing PR checks must be fixed in the automation:
catch-up never pushes directly to a protected branch or bypasses required checks.
devctl release promote --version refusing an RC older than the last stable lists commits on the branch after that
stable in stranded[] and gives the auto-release dispatch command; a comparison it cannot read is reported as such.
--helm-docs-regen (app flavour only, off by default) adds .github/workflows/zz_generated.helm-docs-regen.yaml. On pull requests from renovate/** and dependabot/** branches that touch helm/** or .pre-commit-config.yaml, the workflow regenerates the files the generated pre-commit hooks derive from a chart's values.yaml -- the helm-docs README and values.schema.json -- and pushes the result back onto the PR branch. Without it, every dependency bump that changes an image tag or a values key fails the pre-commit check on files only the hooks can rewrite ("files were modified by this hook"), and the PR waits for a human to run the hooks and push. The Mend-hosted Renovate app cannot run postUpgradeTasks, so the regeneration has to happen in the consuming repo.
How it works:
- A
preflightjob reads the repo's own.pre-commit-config.yaml: everyhelm-schema-<chart>hook plus the hooks of thenorwoodj/helm-docsentry, whoserevnames the helm-docs release to install. Nothing in the workflow is repo-specific, so it needs no regeneration when a chart is added or a tool is bumped. No hooks (or noRELEASE_BOT_CLIENT_ID/RELEASE_BOT_PRIVATE_KEYsecrets, as on fork and Dependabot-triggered runs, which only see Dependabot secrets) skips the second job with a warning. - A
regenjob mints a short-lived token of thegiantswarm-releaseGitHub App (secrets.RELEASE_BOT_CLIENT_ID,secrets.RELEASE_BOT_PRIVATE_KEY), checks out the head branch with it, installs that helm-docs release (the schema hook installs and pins its own generator throughadditional_dependencies), and runs each hook twice through pre-commit: the first pass may rewrite files, the second pass has to be clean. A hook that still rewrites, or errors out, fails the job and nothing is pushed. - A changed tree is committed as
giantswarm-release[bot]and pushed. The push uses the App token because aGITHUB_TOKENpush does not re-trigger the required checks on the new commit. A clean tree is a no-op, so the run the push triggers on the new head exits without pushing again. Runs are serialised per head ref withcancel-in-progress. devctl gen renovatelists the regen commit's author342014845+giantswarm-release[bot]@users.noreply.github.com(and taylorbot'sdev@giantswarm.iofor repositories not regenerated yet) ingitIgnoredAuthors, so Renovate treats the regen commit as its own and keeps rebasing and autoclosing the PR. A repo whoserenovate-custom.json5sets its owngitIgnoredAuthorsmust repeat the addresses: Renovate replaces the array instead of merging it. If the App token cannot be minted (the App is not installed on the repository, or its key is stale), the regen job fails loudly instead of skipping: that is a broken set-up to fix, not a missing secret.
In giantswarm/github the flag is gen.helmDocsRegen: true on the repository entry.
devctl gen workflows --flavour app --language generic --helm-docs-regen
--reservation-support (app flavour only, off by default) adds .github/workflows/zz_generated.reservation_command.yaml, a self-contained workflow with one job. A pull request comment that starts a line with /deploy, /undeploy or /extend, and a closed pull request, are sent to giantswarm/mc-reservations as a repository_dispatch, which reserves a management cluster for the branch's dev build (see devctl reservation). The workflow is a pure trigger: it sends only the repository, the pull request number and the comment ID, and mc-reservations re-reads and checks the rest. A job filter skips other comments, bot comments and the close of a fork's pull request, so they start no run. The repository needs the MC_RESERVATIONS_DISPATCH_CLIENT_ID and MC_RESERVATIONS_DISPATCH_APP_KEY org secrets, and the mc-reservations-github App installed, or a command gets no answer.
In giantswarm/github the flag is gen.reservationSupport: true on the repository entry.
The app flavour generates .github/workflows/zz_generated.chart_tests.yaml, which runs the chart unit tests (make helm-test) on pull requests. A repository whose pipeline runs them elsewhere can leave it out.
--chart-tests=false (app flavour only, on by default) keeps the workflow out of a repository. In giantswarm/github that is gen.chartTests: false on the repository entry; without it align-files puts the workflow back on every run.
devctl gen workflows --flavour app --language generic --chart-tests=false
The app flavour generates .github/workflows/zz_generated.check_readme_links.yaml, which calls the check-readme-links reusable workflow of giantswarm/github-workflows. A pull request that touches README.md fails on a dead URL, a relative path that does not exist in the repository or a reversed link (text)[url]. A weekly run catches links whose target moved without the README changing, which no pull request trigger sees, and files its findings as one issue, Broken links in README, updated on later runs and closed with a comment once the links are fixed. The issue is filed, updated and closed from the default branch only: a workflow_dispatch on another branch keeps its report in the job summary and the run's artifact. The ignore list and the checker versions live in giantswarm/github-workflows under link-check/ and are taken from main whatever ref the generated workflow pins, so a fix there reaches every repository without a regeneration.
--check-readme-links=false (app flavour only, on by default) keeps the workflow out of a repository. In giantswarm/github that is gen.checkReadmeLinks: false on the repository entry; without it align-files puts the workflow back on every run.
devctl gen workflows --flavour app --language generic --check-readme-links=false
Creates common Makefile and includes in the root directory.
The Go Makefile copies built binaries to a unique temporary file beside the destination, then renames it into place. Rebuilding while the previous binary is running succeeds, and the destination only exposes a complete binary. Copy or rename failures keep the previous binary and remove the temporary file. Versioned artifacts, executable permissions and timestamps are preserved. Consumers receive the updated Makefile through align after adopting a devctl release containing this template.
For Go repositories, make install sets CGO_ENABLED=0, like the release build targets,
and writes the binary to $(go env GOPATH)/bin. On Linux this keeps the statically linked
binary from calling glibc's hostname resolver through cgo. Regenerate existing repositories'
Makefiles to pick up this fix.
Example:
devctl gen makefile --flavour cli --language go
Put repository-specific targets in Makefile.custom.mk. The generated root Makefile includes
Makefile.*.mk in lexical order, so Makefile.gen.go.mk is read after Makefile.custom.mk.
A same-named recipe in Makefile.custom.mk is ignored when a generated include supplies that
target's recipe.
For Go repositories, add extra lint checks by defining lint-custom in Makefile.custom.mk:
# Makefile.custom.mk
lint-custom:
./hack/lint-extra.shThe generated lint target depends on this phony hook, which has no generated recipe. Custom
checks run before the Go lint recipe, including with make -j lint, and a failing custom check
fails make lint. Repositories without custom checks keep the existing lint behavior. Move
extra commands from a custom lint recipe into lint-custom, then regenerate the Makefiles
with the repository's usual devctl gen makefile options to get the hook.
Creates a .pre-commit-config.yaml file in the repo root with hooks appropriate for the repository's language and content.
The --language flag sets the primary language (go, python, generic). The --flavors flag enables additional hook groups:
bash— shell script linting viapre-commit-shellmd— Markdown linting viamarkdownlint-clihelmchart— Helm chart schema and docs hooks (auto-detects charts underhelm/)
With --flavors helmchart, generation also writes helm/<chart>/values.schema.json.
The schema hook prints a regeneration command containing the original language, repository,
flavors, Kubernetes schema version and --go-generate setting. Run that complete command
from the repository root: a bare devctl gen precommit uses empty language and flavor
defaults, which removes the language and Helm hooks and skips schema generation. For
example, a Go repository with a chart can regenerate with
devctl gen precommit --language go --flavors helmchart; keep any other original options.
A Go repository's config also refuses a require line in any go.mod (single or in a block) whose trailing comment has more than one word (go-mod-require-comment): Renovate's gomod manager reads only a one-word comment such as // indirect and skips the whole line otherwise, so that dependency is never updated and nothing says so. The explanation goes on a comment line above the require.
A Go repository's golangci-lint hook, like make lint of devctl gen makefile --language go, passes no linter flags: the linters live in the repository's golangci-lint configuration, so a bare golangci-lint run lints with the same set. Both commands write .golangci.yaml (gosec and goconst on top of the standard set) when the repository has no configuration. A repository's own .golangci.yml or .golangci.yaml is kept as it is, except that gosec and goconst are added to linters.enable when it neither enables nor disables them (and govet too when linters.default replaces the standard set); a TOML or JSON configuration, or one whose linters.enable is a flow sequence, fails generation naming the linters to enable.
New configurations set linters.settings.goconst.ignore-tests: true: repeated test-fixture strings do not count toward goconst violations, while repeated production strings are still checked. This avoids the test-fixture noise introduced by the goconst update in golangci-lint 2.12. Existing configurations, including ones created by an earlier Align files run, keep their settings. To apply the same tuning there, merge this setting into the repository's existing .golangci.yml or .golangci.yaml:
linters:
settings:
goconst:
ignore-tests: trueRepositories can set ignore-tests: false to check test literals too, or tune min-occurrences and min-len under the same goconst mapping. To opt out, remove goconst from linters.enable if present and add it to linters.disable. Generation preserves these choices. A repository with production goconst debt still needs to address it or choose one of these overrides.
Before pushing a Go change, run make lint. It uses goimports from PATH, or installs golang.org/x/tools/cmd/goimports@v0.50.0 into go env GOBIN (defaulting to $(go env GOPATH)/bin) when missing. The installed binary does not need to be on PATH. Installation failures fail the target. It first runs goimports -local "$(MODULE)" -l ., with MODULE read from go list -m, to check the import formatting required by CI. Listed files or a goimports error fail the target without changing source files. Run make imports to apply the formatting, then retry make lint.
No hook reads protobuf-generated code: the config's top-level exclude skips *_pb.* (protoc-gen-es, grpc-tools), *_pb2.py, *_pb2.pyi, *_pb2_grpc.py and *.pb.go with its _grpc, .gw, .validate and _vtproto variants. Their generator is the source of truth, so a hook that rewrote them (end-of-file-fixer on buf's TypeScript output, go-imports -local, ruff --fix) would be undone by the next generation. Hand-written files next to them, a gen/ directory's README.md or buf.gen.yaml included, are still checked. The fixer hooks also skip testdata/, .yarn/ and the vendored subcharts under helm/<chart>/charts/.
Examples:
devctl gen precommit --language go --repo-name devctl
devctl gen precommit --language go --repo-name my-app --flavors bash,helmchart
devctl gen precommit --language generic --repo-name my-service --flavors md,bash
With --flavors helmchart, the helm-docs hook builds the pinned revision in pre-commit's Go environment and uses file order for the values table. A globally installed helm-docs cannot change that hook's output. The schema generator and normalizer are likewise pinned to devctl's own dependencies. devctl gen precommit writes the schema and scaffolds README.md.gotmpl; run pre-commit run helm-docs --all-files to update the README. Hook environments need their pinned sources on first installation; cached environments run offline. Schema annotations that reference remote documents still require those documents to be reachable.
A devctl build without generated template provenance files keeps an existing generated YAML file untouched when only its fallback module tree link differs. Changes to the rendered body still regenerate the file, and builds with a known template commit continue to update that provenance.
Generates a renovate.json5 file in the repo root to configure renovate, which automatically updates dependencies in the configured repository.
devctl gen renovate --language LANGUAGE
Note: The LANGUAGE value is not validated currently. go, python and node add the matching language preset; every other value (e.g. generic) renders the base preset alone.
The command also initializes an empty, repo-owned renovate-custom.json5 when it is absent and extends it last. Commit both files in the same pull request. Existing custom files are preserved on every run; add repository-specific rules there, and they apply from that merge without another align-files run. Rules shared by a class of repositories belong in giantswarm/renovate-presets.
The preset reference needs the repository's name even before it has custom rules. The command reads the giantswarm/<name> path of the origin remote, or accepts --repo-name <name> for a checkout without that remote. The checkout directory's name is never used.
For a repository with an older generated config, run this command with the repository's existing generation options and commit both files before adding custom rules. If the pull request introduces renovate-custom.json5, regenerate the root config in that same pull request: adding the custom file alone to an older config still leaves its rules inactive until alignment. Once initialized, keep the custom file (use {} for no overrides), because Renovate cannot resolve a preset that has been deleted.
The giantswarm/github align-files workflow runs this generator for repositories on devctl-generated CI (with --circleci-generated, which disables Renovate's architect-orb updates and extends the ATS preset because gen circleci bakes those in) and for the customer flavour (without it: customer repositories have no CircleCI). Every other repository keeps its hand-maintained renovate.json5.
A GitHub fork takes --flavour fork. Renovate skips a fork ("Repository is a fork and not manually configured - skipping") unless its default config file, renovate.json and never renovate.json5, sets forkProcessing to "enabled" itself; a preset cannot set it. The fork flavour therefore writes the same config as JSONC (comments kept, otherwise strict JSON, which is how Renovate parses renovate.json) into renovate.json with that key, and removes renovate.json5; it leaves .github/dependabot.yml, which on a fork line is upstream's, where the other flavours remove it. The fork line's own rules (enabledManagers, customManagers, dependencyDashboard) go into renovate-custom.json5 as on any other repository. A fork line whose config turns Renovate off (enabled: false) keeps it: the command refuses to replace the opt-out, and Renovate skips the fork anyway. align-files generates nothing for a fork line, so the command runs by hand.
devctl gen renovate --language go --flavour fork
devctl gen makefile --flavour app --language go emits Makefile.gen.app.mk with helm-test
for chart unit tests and ats-test for app-test-suite cluster tests. make test
includes the unit tests; run the cluster tests explicitly:
make ats-test ATS_CHART_FILE=build/my-app-1.2.3.tgz
Build the chart first, as CI's separate build-chart job does. Without
ATS_CHART_FILE, the target selects the single *.tgz below build/; missing or
ambiguous archives fail before creating a cluster. ATS_CHART_ARCHIVE_PREFIX
restricts this discovery, like the orb's chart_archive_prefix parameter.
The target requires Docker with host networking and a compatible kind on PATH
(the pinned architect orb installs kind v0.33.0). It creates a temporary kind
cluster with the same default node image as generated CI, applies
.ats/kind-config.yaml when present, and runs the pinned ATS 1.x image with the
checkout mounted at /ats/workdir, the calling user's UID/GID, and explicit
chart, kubeconfig, cluster type and Kubernetes version arguments. ATS reads the
repository's .ats/main.yaml (also .yml) and tests from the checkout. Each run
uses its own kubeconfig and cluster name and removes them on success or failure;
the caller's current context is never used. Repositories with no Python
(test_*.py or *_test.py) or Go (*_test.go) tests under tests/ats/ and no
ATS config print a message and exit successfully before checking tools or
artifacts. Generated dependency files alone do not count as a suite.
The ATS and kind node image versions carry Renovate annotations. A repository
with explicit CI pins must match them using ATS_VERSION and
ATS_KIND_NODE_IMAGE_VERSION in Makefile.custom.mk; ATS_KIND_NODE_IMAGE
overrides the whole node image reference. ATS_KIND_CONFIG overrides the kind
config path (set it empty to disable it), and ATS_FLAGS passes additional ATS
arguments, like the orb's additional_app-test-suite_flags parameter. The target
requires an ATS 1.x suite; legacy 0.x suites must migrate before using it.
CI continues to use architect/run-tests-with-ats. Its registry context and
image publication steps are separate prerequisites: local tests need pullable
application images, and this target does not copy CI credentials into kind for
private image pulls. It also leaves the chart build and release steps separate.
A real-repository validation records the generated target, built chart, image pins, command and live ATS outcome.
Writes the set-up every team plans repository shares. Nothing is generated without the plans flavour.
devctl gen plans --flavour plans
.claude/settings.json enables the gs-plans plugin, the plan-workflow skills, from the giantswarm marketplace (giantswarm/claude-code), with autoUpdate on so Claude Code refreshes the marketplace and its plugins after startup. devctl owns two entries, extraKnownMarketplaces.giantswarm and enabledPlugins["gs-plans@giantswarm"], and keeps every other key of an existing file, so a team adds its own settings in the same file. The JSON is rewritten with sorted keys and two-space indentation; strings and numbers stay as written. The skills live in the plugin, not in the repository; the repository's own rules, such as which plan stages are required, stay in its AGENTS.md.
Writes Giant Swarm's shared instructions for coding agents into the repository's root AGENTS.md, which Claude Code, Codex, Cursor and other agents read.
devctl gen llm --flavour app --language go
The instructions sit in a block at the top of AGENTS.md:
<!-- BEGIN devctl-managed: edits in this block are overwritten -->
<!-- markdownlint-disable-file MD041 -->
## Giant Swarm conventions
…
<!-- END devctl-managed -->
## This repositorydevctl owns the block and replaces it on every run. Everything outside it belongs to the repository and is kept byte for byte: put the repository's own instructions below the block, where they take precedence over it. A new AGENTS.md gets an empty ## This repository section for them. The block passes markdownlint and prettier with their default settings, which many repositories run in pre-commit; prettier's proseWrap: always rewraps it. The one exception is markdownlint's rule that a file starts with a top-level heading: the begin marker comes first, so the block turns that rule off for the whole file, including text outside the block. The block holds only short rules for every change; Go repositories get one more, for goimports. It also asks the agent to point Giant Swarm staff once to the plugins of the giantswarm/claude-code marketplace when their skills are missing: gs-base and gs-dev, plus gs-godev for Go and gs-appdev for the app flavour. Longer guidance comes from the style guides in giantswarm/fmt and the plugins in giantswarm/claude-code, not from generated skills.
On every run, gen llm also:
- adds an import of
AGENTS.mdto aCLAUDE.mdor.claude/CLAUDE.mdthat has content of its own and no import yet (@AGENTS.md, or@../AGENTS.mdfrom.claude/), so that Claude Code reads both; - links
.claude/skillsto../.agents/skillswhen the repository has skills in.agents/skills, so that Claude Code finds the same skills as other agents; - deletes
.cursor/rules/zz_generated.base-llm-rules.mdcand.cursor/rules/zz_generated.go-llm-rules.mdc, which earlier versions generated, and the.cursordirectories they leave empty.
Nothing is generated for the fork flavour.
AGENTS.md and .agents/skills cover instructions and skills only. Hooks, permissions and MCP servers stay in each agent's own configuration, such as .claude/settings.json or .mcp.json; gen llm neither generates nor moves them. Tooling shared across repositories ships as a plugin in giantswarm/claude-code.
A repository whose AGENTS.md, CLAUDE.md or .claude/CLAUDE.md has instructions outside a devctl-managed block, or whose skills are in a .claude/skills directory, needs a migration first. Until then, gen llm leaves the repository unchanged and prints a warning that says so; the command still succeeds, so the rest of an alignment run is not affected. Migrate it with:
devctl gen llm --flavour app --language go --migrate-instructions
The migration:
- moves the content of
CLAUDE.md, or else.claude/CLAUDE.md, below the block in a newAGENTS.md, unlessAGENTS.mdalready has instructions. A movedCLAUDE.mdis left as@AGENTS.md; a moved.claude/CLAUDE.mdis deleted, and its relative imports and links are rewritten to work from the root. - keeps a Claude file that has instructions next to an existing
AGENTS.md, and adds the import to it. - moves the skill directories in
.claude/skillsto.agents/skills, drops links in it that point to those skills, and replaces.claude/skillswith a link to../.agents/skills.
Moved content is copied as it is. Review the result before committing it: text that names Claude, starts with # CLAUDE.md, or repeats a rule from the block reads better adjusted.
Both modes check the repository before they change anything. Each problem is printed with its path and its fix, and the repository stays as it is:
- malformed devctl-managed markers, for example an end marker without a begin marker;
- an
AGENTS.mdthat is a link, which would put the block into another file; - a Claude file that links anywhere other than
AGENTS.md; .claude,.agentsor.agents/skillsas links or files, and.claude/skillsas a file or a link to anywhere other than../.agents/skills;- names that differ only in case, such as
agents.md; - outputs that Git would ignore, such as an
AGENTS.mdor.claude/entry in.gitignore: a commit withgit add -Awould leave them out; - entries in
.claude/skillsthat cannot move: loose files, links elsewhere, and skills with the same name in.agents/skills.
In default mode the command still succeeds, so that an alignment run goes on with the other generators. With --migrate-instructions it fails after printing the findings, because the migration that was asked for did not happen.
Add --dry-run to see the changes, or the findings, without changing anything. A repository that is up to date gets gen llm would make no changes.
By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it (see Claude Code: AGENTS.md). A CLAUDE.md in a directory that contains your checkouts, or your own ignored CLAUDE.local.md, therefore hides AGENTS.md from your Claude Code. ~/.claude/CLAUDE.md does not count. Either move such instructions to ~/.claude/CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config, so that Claude Code reads both.
Generates the dynamic-config pipeline of a repository on devctl-generated CI: .circleci/config.yml (the static setup workflow, which merges the optional repo-owned .circleci/custom.yml in at pipeline runtime) and .circleci/workflows.yml (the pipeline), plus the canonical tests/ats dependency file of a chart repository.
When chart-test jobs are emitted and neither .ats/main.yaml nor .ats/main.yml exists, generation also creates a starter .ats/main.yaml with skip-steps: [smoke, functional, upgrade]. A repository without ATS scenarios can then run the job without failing on missing test configuration. The legacy ATS 0.x starter also sets the smoke and upgrade cluster types to kind; ATS 1.x receives its cluster from the orb and does not accept those old options. Existing configuration, including an empty file, is kept byte for byte, and an existing main.yml is never shadowed by a new main.yaml. Non-app, fork, template and --skip-ats repositories get no starter.
The configuration and Python tests are the repository's own after creation. Add tests and remove their scenario names from skip-steps to enable them; app-test-suite picks the pytest executor from the generated dependency file and requires test files for enabled scenarios. devctl repo create continues to write a first smoke test and its smoke-enabled configuration into a new repository's scaffold, preserving any configuration supplied by the template.
devctl gen circleci --repo-name REPOSITORY --language LANGUAGE --flavour FLAVOUR[,FLAVOUR]
The pipeline is derived from the repository's signals — the language, the flavours, the presence of a Dockerfile, a .ats/kind-config.yaml, a lockfile or .nvmrc — rather than configured: go and node select a build/test job, a Dockerfile the image jobs, the app flavour the chart jobs (build, chart tests, push on the release tag). The knobs the giantswarm/github team file exposes under gen.ci are the flags of this command; devctl gen circleci --help documents each, and the architect-orb version is baked into devctl next to the template.
A chart whose tests need an image pushed by a custom job can add that job's workflow name to
.circleci/config.custom.yml:
chart_tests:
requires:
- push-buzz-minio-to-registriesgen circleci reads this repository-owned file on every regeneration and adds the names to
execute-chart-tests.requires, keeping build-chart and the generated branch image push when present.
Duplicate names are emitted once. The file is generator input; .circleci/custom.yml still defines
the jobs and their invocations in the build workflow, and is merged at pipeline runtime. Neither
custom file is generated or overwritten. Malformed configuration, unknown keys, and empty or
self-referencing job names fail before generated files are written. Nonempty dependencies require the app flavour with chart tests
enabled, and are refused for template and multi-image repositories.
The custom jobs must run on the same branches as execute-chart-tests: a job filtered to release
tags cannot gate branch tests. For a custom image, publish the branch's computed version before
chart tests and let the chart's test values select that version instead of pinning a released tag.
The generated chart and image builds use the same version for the same commit. A custom image job
should set persist-build-version: false, leaving build-chart to persist its version file into the
shared workspace. This setting affects branch chart tests only; execute-chart-tests-release keeps
its existing dependencies when --ats-on-release is enabled.
A repository other repositories are created from (componentType: template in the team file, e.g. giantswarm/template-app) carries a chart at helm/{APP-NAME} with the placeholders the set-up engine fills in — {APP-NAME}, {TEAM-NAME} (the chart's io.giantswarm.application.team label) and {APP HELM REPOSITORY} — so app-build-suite cannot build it as it is. With --component-type template --team TEAM the chart job renders the checkout first and builds the rendered chart:
devctl gen circleci --repo-name template-app --language generic --flavour app --component-type template --team team-honeybadger
The app name (sample-app) and the Helm repository (https://charts.example.com) are fixtures; the team is the owning team from the team file (team-honeybadger and honeybadger both name it), because the team label is what the first chart build of a created repository is validated on. Green means a repository created from the template passes that first build. Nothing is released from a template, so the pipeline has no chart-test job, no push jobs and no release leg, the build runs on every branch including main, and no tests/ats files are written. A template without a chart (no app flavour) is unchanged by the flag; every other --component-type value is inert.
A repository of the multi-image flavour holds several images, one per toolchains/<name>/ directory with a Dockerfile, each released as its own <name>/vX.Y.Z line:
devctl gen circleci --repo-name agent-toolchains --language generic --flavour multi-image
devctl gen workflows --flavour multi-image --language generic --release-workflow auto-release
Every image is giantswarm/<repo>/<name> (--image-name sets the prefix), built with toolchains/ as its context, so the images share the build files kept there beside them (toolchains/lib/).
.circleci/config.ymlis a setup workflow that reads the image directories at pipeline runtime, so a pull request that adds an image builds it without a regeneration, and continues the pipeline with one copy of the per-image workflow of.circleci/workflows.ymlfor each image to build (__IMAGE__in it stands for the name). The optional.circleci/custom.ymlis merged in last, as everywhere.- A branch pushes an amd64 dev image of each image whose directory changed against
main; a change undertoolchains/outside every image directory builds every image.mainitself builds nothing: its merges are released by their tags. - A tag
<name>/vX.Y.Zpublishes that image multi-arch (--image-platforms,linux/amd64,linux/arm64by default) to gsoci.azurecr.io under its version andlatest;--force-publicfor a private repository whose images are public,--image-private-onlyfor gsociprivate alone. A tag that names no image fails the pipeline. - The repository's own check of an image is the job
check-imagein.circleci/custom.yml, with a string parameterimage, the image's name: when it is defined, each release runs it first and the push requires it. Without it a release publishes straight away.
# .circleci/custom.yml
jobs:
check-image:
parameters:
image:
type: string
machine:
image: ubuntu-2404:current
steps:
- checkout
- run: scripts/check-toolchains.sh << parameters.image >>.github/workflows/zz_generated.auto_release.yaml tags, on every push to the release branch, each image whose directory, or a shared file under toolchains/, changed since its latest <name>/vX.Y.Z with its next version, from the pushed commit's subject (the squash subject): a breaking change (type!: or a BREAKING CHANGE footer) the major, a feat the minor, anything else the patch, v0.1.0 for a new image. There are no release candidates: each tag is stable and gets its GitHub release. .github/release-gate.custom.sh, when present, runs with each tag about to be cut; a refusal skips that tag and fails the run. The last step makes sure CircleCI built every tag, triggering a lost one through CIRCLECI_API_TOKEN. The flavour takes auto-release alone, and cliff.toml is removed.
A repository's gen options are its entry in repositories/<team>.yaml of giantswarm/github. The align-files action (.github/action/index.js there) turns them into devctl gen flags: installUpdateChart is --install-update-chart, helmDocsRegen --helm-docs-regen, ci.releaseWorkflow --release-workflow. An entry without ci.releaseWorkflow gets auto-release when ci.generate is true and legacy otherwise, and pre-commit is generated when ci.generate is true or preCommit is a list ([] for the base hooks alone): a repository on GitHub Actions alone that wants Auto Release sets both keys explicitly.
A new option therefore lands in three steps:
- In devctl: the flag, the template and its golden test. Each generator under
pkg/gen/input/<name>/compares its output with goldens undertestdata/, rewritten bygo test ./pkg/gen/input/<name>/ -update; the workflow tests swap the provenance header for a fixed string (withFixedHeader), so a template that is not committed yet renders the same. The provenance files (*.template.sha) are gitignored and written bygo generate ./..., whichmake testruns first. - In giantswarm/github, once the release is out: the devctl pin at that release or later, and the option on the repository's entry. A merged change to an entry aligns that repository;
gh workflow run align-files.yaml --repo giantswarm/github -f repository=<name>aligns it again, and the run's log names the pull request it opened fromteams-alignment-branch. - In the repository: review and merge that pull request, then prove the generated workflow with a pull request that exercises it.