devctl understands different types of GitHub repositories, to make the right modifications for each type. App repos have different needs than Go libraries, for example.
A flavour describes what kind of project the repository is. It is passed with --flavour (-f) and decides which files the gen commands write:
devctl gen workflows --flavour app,customer
devctl gen makefile --flavour cli --language go
Flavours are not mutually exclusive. Some repos must be configured with multiple flavours -- pass them comma-separated, or repeat the flag. For example, an operator may carry the flavours app and k8sapi. Note: this configuration is usually persisted in our repository configuration.
The flavour is one of two independent axes. The other one is the programming language (--language), described in Flavours and languages below. Roughly: the flavour decides the release and packaging plumbing, the language decides the build and test plumbing.
| Flavour | Pick it when the repo... |
|---|---|
app |
contains a Helm chart that is published to an app catalog |
cluster-app |
is a cluster app (cluster-aws, cluster-azure, ...) |
cli |
ships downloadable binaries on its GitHub Release |
k8sapi |
defines a Kubernetes API (CRDs) |
fleet |
holds GitOps definitions for management clusters |
customer |
tracks issues on a shared customer board |
fork |
carries an upstream release plus patches on an organisation branch |
multi-image |
builds and releases multiple images, one per toolchains/<name>/ directory |
plans |
holds a team's PRDs, companion websites and plan-workflow skills |
generic |
is none of the above and just needs to be released |
generic is the neutral choice, not a fallback for "I am not sure": it adds nothing beyond the base files. If a more specific flavour applies, use it -- and add generic only when nothing else does.
An app, by the definition of the Giant Swarm app platform. Each app repository contains at least one Helm chart.
| Command | Result |
|---|---|
gen makefile |
Makefile.gen.app.mk -- the lint-chart, update-chart, update-deps, helm-docs and helm-test targets |
gen workflows |
.github/workflows/zz_generated.check_values_schema.yaml, plus zz_generated.chart_tests.yaml (unless --chart-tests=false) and zz_generated.check_readme_links.yaml (unless --check-readme-links=false) |
gen workflows --install-update-chart |
additionally zz_generated.update_chart.yaml, plus zz_generated.sync_from_upstream.yaml with --upstream-sync-automation and zz_generated.dispatch_update_chart_events.yaml with --dispatch-update-chart-events-repo |
gen circleci |
the chart pipeline: build-chart / push-to-app-catalog jobs and the ATS chart tests |
gen llm |
includes the gs-appdev plugin in the AGENTS.md managed block |
With --language kyverno-policy this flavour also generates zz_generated.test-kyverno-policies-with-chainsaw.yaml.
A specific type of app repository which provides a values schema that aims to fulfill the requirements of the RFC #55.
| Command | Result |
|---|---|
gen makefile |
Makefile.gen.cluster_app.mk |
gen workflows |
.github/workflows/zz_generated.documentation_validation.yaml, zz_generated.json_schema_validation.yaml, zz_generated.diff_helm_render_templates.yaml |
cluster-app only adds the schema and documentation validation on top of a chart repo -- it does not generate the chart build and publish pipeline itself. Combine it with app (-f app,cluster-app) to get both.
A command line interface (CLI) component which is typically executed on-demand either by a user or within an automation system. CLIs are typically released with downloadable and executable binaries.
| Command | Result |
|---|---|
gen makefile |
Makefile.gen.go.mk gains the packaging targets (package-darwin-amd64, package-linux-arm64, ... writing to ./bin-dist), plus .github/zz_generated.windows-code-signing.sh |
gen circleci |
the go-build job builds the full six-architecture matrix (linux, darwin, windows on amd64/arm64) and an upload-release-assets job attaches the binaries to the GitHub Release on tag builds |
Requires --language go -- gen makefile rejects any other combination, and the CircleCI binary jobs are only emitted for Go.
The gen circleci flag --build-concurrency applies to this flavour only, and --resource-class sizes the cli go-build job as well as the Node job. Lower the first and/or raise the second if the cold cross-compile gets OOM-killed.
A repository that provides a Kubernetes API (usually one or several custom resource definitions).
| Command | Result |
|---|---|
gen makefile |
Makefile.gen.k8sapi.mk (controller-gen based deepcopy/CRD generation), hack/boilerplate.go.txt and hack/.gitignore; removes the obsolete Makefile.custom.mk and hack/tools/bin/controller-gen |
A repository to be used with GitOps containing kubernetes clusters.
| Command | Result |
|---|---|
gen workflows |
.github/workflows/zz_generated.cluster_app_values_validation_schema.yaml -- validates the management-clusters/**/cluster-app-manifests.yaml committed in the repo against the corresponding cluster app schema, zz_generated.validate_organization_kustomizations.yaml, plus zz_generated.mctl_*.yaml |
zz_generated.validate_organization_kustomizations.yaml runs on every pull request. Its job, Organization kustomizations stay in their directory, runs the composite action giantswarm/management-cluster-bases/.github/actions/organization-kustomizations@main: it fails when a kustomization file under management-clusters/*/extras/agent-platform-organizations (the Agent Platform organization paths that agent-manager writes in commit mode) has a field other than apiVersion, kind, metadata and resources, or a resources entry with .., an absolute path, a git or HTTP URL, or a symbolic link. A repository without organizations passes it, so the job can be a required check (requiredChecks in giantswarm/github).
devctl gen workflows generates the mctl workflows of a <customer>-management-clusters repository (zz_generated.mctl_*.yaml: cluster init PR, /init, /config, /create-mc, the mctl/ready-to-merge gate and the merge and close cascades), running the mctl image tag devctl pins (vars.MCTL_IMAGE overrides it). They never run in giantswarm/template-management-clusters. The unprefixed copies and op.env that mctl create cmc-repo wrote are deleted.
A repository used to track mostly issues and provide project boards, shared with a customer.
| Command | Result |
|---|---|
gen workflows |
.github/workflows/zz_generated.add_customer_board_automation.yaml -- adds new issues to the general customer board |
This flavour is purely about issue tracking. It says nothing about how the repo is built or released, so it is almost always combined with another flavour.
Its generated setup is the GitHub workflows (gen workflows, including the customer board automation) plus renovate.json5 (gen renovate --language generic: the giantswarm base preset, nothing language- or CI-specific). There is no CircleCI for customer repositories, so align-files runs gen renovate for this flavour without --circleci-generated, and a newly registered customer repository has its Renovate config before Renovate's first run instead of receiving the onboarding PR.
A fork line: a repository that carries an upstream release plus the carried patches on a branch named after the organisation, which its entry declares as defaultBranch. The tree is upstream's, so nothing is generated for it: align-files leaves it as it is, and only devctl gen renovate --flavour fork, run by hand, writes the renovate.json Renovate needs to scan a GitHub fork (details); and the repository set-up reconciler skips the scaffold and CODEOWNERS steps on it and runs every other step as declared, branch protection on the declared branch included. Its pull requests land by rebase merge, so that each carried patch stays one upstream-ready commit, and a re-pin merges upstream's history: the reconciler's settings step keeps rebase merges on and leaves merge commits as the repository has them, while the rest of the settings baseline (squash merges named after the pull request's title, branch updates and auto-merge on, the head branch deleted on merge, issues on, wiki and projects off) applies as everywhere. Declared alone, with the repository's language.
A repository of images alone, several of them, each with its own release line: one image per toolchains/<name>/ directory holding a Dockerfile, named giantswarm/<repo>/<name> and released as <name>/vX.Y.Z (giantswarm/agent-toolchains). Declared on its own with language: generic, on generated CI with gen.ci.releaseWorkflow: auto-release (the default there; legacy is refused). devctl gen circleci renders its per-image pipeline and devctl gen workflows its per-image Auto Release (details).
| Command | Result |
|---|---|
gen circleci |
per-image build and publish pipeline for each toolchains/<name>/Dockerfile |
gen workflows --release-workflow auto-release |
.github/workflows/zz_generated.auto_release.yaml tagging each changed image directory <name>/vX.Y.Z |
A repository that does not fit any of the more specific flavours above.
No flavour-specific files. The repo still gets everything that is not flavour-gated: the base Makefile, the release workflows, and whatever the --language selects.
A team plans repository: versioned PRDs, their companion websites and the plan-workflow agent skills (one <team>-plans repository per team). Declared on its own (flavours: [plans]) with language: generic and gen.ci.generate: false -- there is no CircleCI for it, the same as customer. It derives the template giantswarm/template-plans; any other language is refused, the same way language node is until its template ships. devctl gen plans writes the repository's shared set-up, the .claude/settings.json that enables the gs-plans plugin (gen.md).
| Command | Result |
|---|---|
gen plans |
.claude/settings.json enabling the gs-plans plugin |
--language (-l) takes exactly one value and selects the toolchain:
| Language | Result |
|---|---|
go |
gen makefile: Makefile.gen.go.mk. gen circleci: the go-build job. gen workflows: zz_generated.fix_vulnerabilities.yaml. gen llm: goimports -local rule and gs-godev plugin in the AGENTS.md managed block. gen precommit: .golangci.yml and Go hooks, with repo name auto-detected from go.mod |
node |
gen circleci: a node-build / node-test job on a cimg/node executor, tuned with --package-manager and the --node-* flags. gen precommit: a ci:lint pre-push hook |
kyverno-policy |
gen makefile: Makefile.gen.chainsaw.mk and the chainsaw test scaffolding. gen workflows (with flavour app): zz_generated.test-kyverno-policies-with-chainsaw.yaml |
python |
accepted as a valid value, but no generator currently emits Python-specific files |
generic |
no language-specific files |
The two axes combine freely, apart from one rule: cli requires go. Some common pairings:
| Repo | Flags |
|---|---|
| Go operator with a chart | -f app,k8sapi -l go |
| Cluster app | -f app,cluster-app -l generic |
| Go CLI tool | -f cli -l go |
| Kyverno policy chart | -f app -l kyverno-policy |
| Management cluster fleet repo | -f fleet -l generic |
- Only
gen makefileandgen circlecivalidate--languageagainst the list above.gen workflows,gen llmandgen precommitaccept any string, so a typo such as-l golangsilently produces output with the language-specific parts missing. gen makefilerequires both--flavourand--language;gen workflowsrequires--flavour.gen llmwrites the devctl-managed block inAGENTS.md:--language goadds thegoimports -localrule andgs-godevplugin,--flavour appadds thegs-appdevplugin, and--flavour forkskips generation.gen renovate --languageis not this list. It names an ecosystem for Renovate to watch (go,docker, ...).gen precommithas its own, unrelated--flavorsflag (US spelling) with the valuesbash,mdandhelmchart. These select extra pre-commit checkers and have nothing to do with repository flavours.