platformctl

platformctl

platformctl is standalone CLI for shared Helm workflow logic across mirrored deployment repos such as platform-deployments and platform-deployments-private.

Scope

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

Command surface

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 the following tools:

• Go
• Helm
• helm-docs for platformctl docs and platformctl check-docs
• goreleaser for release-like local builds and real releases

Install Goreleaser from the official project:

• https://github.com/goreleaser/goreleaser

./scripts/build.sh
./scripts/install-platformctl.sh
make build
make install-platformctl
make release-check
make release-snapshot
just build
just install-platformctl
just release-check
just release-snapshot

Install script behavior:

• builds ./bin/platformctl
• installs binary to ${INSTALL_DIR:-/usr/local/bin}
• uses sudo only when needed, or when USE_SUDO=1
• optionally appends INSTALL_DIR to shell rc when UPDATE_SHELL_RC=1

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

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

make release-snapshot
just release-snapshot
goreleaser release --snapshot --skip=publish --clean

The helper targets resolve goreleaser from PATH, GORELEASER_BIN, ~/.local/bin, ~/.local/go/bin, or ~/go/bin.

release-check validates the release build in a local snapshot mode that does not require a configured git remote.

Release Artifacts

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

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.

Tagged releases are published to Codeberg with Goreleaser. Local and CI release flows both use the same .goreleaser.yaml configuration.

To publish a real release locally, create and push a semver tag, then run:

CODEBERG_TOKEN=your-token make release

CI will use the same release configuration from Forgejo Actions once the workflow is enabled.

Configuration

platformctl is intentionally mirrored-layout-only in v1.

Expected repo roots:

• helm-charts/platform
• helm-charts/apps
• deployments/platform
• deployments/apps

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.

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