platformctl

README

platformctl

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

Release automation is executed through a version-pinned release-tools toolkit. platformctl bootstraps a cloned toolkit checkout from .release-tools-version and then uses that toolkit's shared Make frontend.

Supporting documentation:

• docs/README.md
• docs/maintainer-guide.md
• docs/release.md
• ../release-tools/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

Release commands fetch the pinned release-tools tag automatically, so a submodule checkout is not required for normal release execution.

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

To install a published release instead of building from source:

VERSION=v1.0.0 make 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
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 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.

Local maintainer auth should come from:

export CODEBERG_TOKEN="$(cat ~/.config/codeberg/token)"

CI should provide CODEBERG_TOKEN through Forgejo repository secrets.

platformctl pins the shared toolkit version in .release-tools-version:

v1.2.0

If an older tag does not contain that file, set an explicit override when releasing it:

RELEASE_TOOLS_VERSION=v1.2.0 VERSION=v1.1.0 make release-tag

Older tags can be released by overriding the shared toolkit version used for the runtime bootstrap. platformctl only bootstraps and invokes the shared toolkit.

Configuration

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

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

• name
• chartRoot
• valuesRoot
• 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:

layout:
  mirroredGroups:
    - name: platform
      chartRoot: helm-charts/platform
      valuesRoot: deployments/platform
      structure: service
    - name: apps
      chartRoot: helm-charts/apps
      valuesRoot: deployments/apps
      structure: domain-service

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

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

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