platformctl

Overview

platformctl centralizes shared Helm workflow logic for mirrored deployment repos such as platform-deployments and platform-deployments-private. It discovers chart and values pairs, verifies them, renders manifests, packages bundles, and regenerates chart README files from one strict platformctl.yaml.

Release automation is executed through the installed release-tools CLI and the repo-local .release-tools.env config.

Scope

• mirrored repo layout only
• Go binary distribution
• command surface parity with current root workflow commands
• config-driven behavior through platformctl.yaml

Documentation

• docs/README.md
• docs/maintainer-guide.md
• docs/release.md
• https://codeberg.org/rch/release-tools/src/branch/main/docs/usage.md
• https://codeberg.org/rch/release-tools/src/branch/main/docs/agent-release-flow.md

Commands

platformctl docs
platformctl check-docs
platformctl verify
platformctl verify-charts
platformctl verify-values
platformctl render --chart platform/example --overlay platform/example/values-test.yaml
platformctl render-all
platformctl bundle --chart platform/example
platformctl bundle-all

Build And Install

Development requires:

• Podman

The dev container provides Go 1.26.4, Helm 4.2.1, helm-docs, Goreleaser, and release-tools. Source code stays on the host and is mounted at /workspace. Release configuration lives in .release-tools.env.

Open an interactive container shell:

make shell

Common one-shot commands:

make build
make test
make verify
make install-platformctl

To install a published release instead of building from source:

VERSION=vX.Y.Z make install-release-platformctl
VERSION=vX.Y.Z ./scripts/install-release-platformctl.sh

For fast iteration inside make shell, ./scripts/build.sh keeps the current single-binary workflow.

For release-like local artifacts, use Goreleaser snapshot mode:

make verify
./scripts/in-container release-tools snapshot

For install script behavior, helper resolution details, and maintainer commands, see docs/maintainer-guide.md.

Release Artifacts

Consumer CI is expected to download versioned release artifacts from Codeberg rather than build from source.

Consumer repos can use scripts/install-release-platformctl.sh or the matching make target to pin a specific release version.

The release installer expects a published Codeberg release with uploaded assets, not just a git tag.

Release tag URL shape:

https://codeberg.org/rch/platformctl/releases/download/<tag>/

Expected assets per tag:

• platformctl_linux_amd64.tar.gz
• platformctl_linux_arm64.tar.gz
• platformctl_darwin_amd64.tar.gz
• platformctl_darwin_arm64.tar.gz
• platformctl_checksums.txt

Each archive should contain a single root-level platformctl binary.

Release commands, token handling, local publish-tag, and Forgejo CI release flow are documented in docs/release.md.

Release descriptions on Codeberg are generated from the matching NEWS.md entry for the released tag.

Local maintainer auth should come from:

RELEASE_TOKEN_FILE=~/.config/codeberg/token ./scripts/in-container release-tools publish-tag vX.Y.Z

CI should provide RELEASE_TOKEN through Forgejo repository secrets.

Local exact-tag publishing runs release-tools through the dev container:

./scripts/in-container release-tools publish-tag vX.Y.Z

The release command publishes from a clean temporary clone of the requested tag, so local uncommitted changes cannot leak into the release.

If you need to publish from the current checkout instead, use:

./scripts/in-container release-tools publish

Configuration

platformctl is intentionally mirrored-layout-only. The mirrored group names and roots are configurable in platformctl.yaml, but the model still expects mirrored chart/values pairs.

Supported config files use apiVersion: platformctl/v1beta1. platformctl/v1alpha1 configs are no longer accepted as of platformctl v2.0.0.

By default, chart and values roots are resolved under the repository containing platformctl.yaml. To control charts and values from separate checkouts, set repositories.charts.root and repositories.values.root. Relative repository roots are resolved from the control repository root. When chart roots point to an external checkout, check-docs verifies generated chart README diffs in that chart repository.

Supported layout config uses layout.mirroredGroups. Each group defines:

• name
• chartRoot: chart subtree inside repositories.charts.root
• valuesRoot: values subtree inside repositories.values.root
• structure

The CLI reads platformctl.yaml from the repository root by default.

Useful global flags:

platformctl --repo-root /path/to/repo verify
platformctl --repo-root /path/to/repo --config /path/to/repo/platformctl.yaml verify

Use platformctl.example.yaml as the starting point for new mirrored repositories.

Example layout config:

apiVersion:platformctl/v1beta1kind:Configrepositories:charts:root:.values:root:.layout:mirroredGroups:- name:platformchartRoot:helm-charts/platformvaluesRoot:deployments/platformstructure:service- name:appschartRoot:helm-charts/appsvaluesRoot:deployments/appsstructure:domain-service

service means <group>/<service>. domain-service means <group>/<domain>/<service>.

Legacy layout.chartRoots / layout.valuesRoots config is no longer supported.

Example with separate control, chart, and values repositories:

repositories:charts:root:../platform-chartsvalues:root:../platform-values

Next Priorities

The most useful next implementation work is:

• validate the Forgejo tag-release workflow end to end in normal use
• migrate consumer repos fully to release-based installation
• add integration tests around release install and release publishing helpers
• improve CLI error messages further for failing external tools and bad repo layout

For the reusable reasoning behind this release setup, see https://codeberg.org/rch/release-tools/src/branch/main/docs/agent-release-flow.md.

Consumer Model

Consumer repos such as platform-deployments should treat platformctl as the source of truth for shared chart and values workflows.

Consumer repos own:

• helm-charts/
• deployments/
• platformctl.yaml
• root command wrappers in Makefile, justfile, and ci/

platformctl owns:

• docs generation checks
• chart verification
• values verification
• rendering
• bundling