Skip to content

Latest commit

 

History

History
160 lines (107 loc) · 13 KB

flavours.md

File metadata and controls

160 lines (107 loc) · 13 KB

Understanding flavours

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.

Which flavour do I need?

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.

Flavour reference

app

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.

cluster-app

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.

cli

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.

k8sapi

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

fleet

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.

customer

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.

fork

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.

multi-image

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

generic

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.

plans

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

Flavours and languages

--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

Caveats

  • Only gen makefile and gen circleci validate --language against the list above. gen workflows, gen llm and gen precommit accept any string, so a typo such as -l golang silently produces output with the language-specific parts missing.
  • gen makefile requires both --flavour and --language; gen workflows requires --flavour.
  • gen llm writes the devctl-managed block in AGENTS.md: --language go adds the goimports -local rule and gs-godev plugin, --flavour app adds the gs-appdev plugin, and --flavour fork skips generation.
  • gen renovate --language is not this list. It names an ecosystem for Renovate to watch (go, docker, ...).
  • gen precommit has its own, unrelated --flavors flag (US spelling) with the values bash, md and helmchart. These select extra pre-commit checkers and have nothing to do with repository flavours.