platformctl

platformctl

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

Supporting documentation:

• docs/README.md
• docs/maintainer-guide.md
• docs/release.md
• docs/agent-release-flow.md

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:

• 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

To install a published release instead of building from source:

VERSION=v1.0.0 make install-release-platformctl
VERSION=v1.0.0 just install-release-platformctl
VERSION=v1.0.0 ./scripts/install-release-platformctl.sh

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

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/just 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 release-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.

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.

Next Priorities

After v1.0.0, 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 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