hydra ci¶

CI/CD configuration, secrets, and pipeline commands for Helm chart management. Pipeline stages live under hydra ci run .... By default, pipeline commands run in full CI mode (commit, push, merge request, OCI upload, webhooks as configured). Use the persistent flags below for dry runs or local-only commits.

Parent command reference in Hydra: Run CI/CD pipeline steps for the Helm chart repository

CLI help recording¶

Synopsis¶

hydra ci run <subcommand> <config-path> [flags]
hydra ci run auto <config-path> [flags]
hydra ci config <path> [--no-color]
hydra ci secrets <subcommand> <config-path> [flags]

config-path is the path to .hydra-ci.yaml, or a directory that contains it (for example the charts repository root). If you pass a directory, Hydra appends .hydra-ci.yaml automatically.

Description¶

All pipeline stages read configuration from .hydra-ci.yaml in the repository. Use hydra ci config to create or edit that file interactively, with defaults and filesystem-based detection of app groups and root apps.

Subcommand	What it does
`run download`	Build-tag change detection, then `helm dependency update` per changed chart even when dependencies already exist locally
`run auto`	Run pipeline stages in order (default or `ci.autoSteps`); fail-fast; logs current git branch
`run test`	Build-tag change detection, verify local dependencies are present, then `helm lint` and `helm template` per changed chart
`run release`	Change detection, wrapper + root version bumps; `--local` commits and tags, `--dry-run` logs only; default CI mode is not fully wired yet
`run promote`	Compare env directories, create `hydra/promote/...` branches, copy, rewrite version suffixes, open merge requests
`run publish`	Resolve charts from release tags at `HEAD`, then `helm package` (and `helm push` in CI mode) to `ci.registry`
`run verify`	Resolve charts like `publish`, then download OCI chart artifacts and verify Helm and Cosign signatures
`run sprint`	At a sprint boundary, bump major versions of all root apps across dev/stage/prod
`run upgrade`	From an external service deployment pipeline, update a service version in dev (optional MR if unit test data changes)
`run sync`	Copy cluster config from external cluster repos and trigger the update path
`run update`	Render all clusters, refresh unit test data, one-auto-commit rule
`config`	Interactive `.hydra-ci.yaml` editor (stdout color follows TTY unless `--no-color`)
`secrets`	Manage encrypted `.hydra-ci-secrets.sops.yaml` files

Persistent Flags¶

These flags apply to hydra ci run ... subcommands, and are also accepted on hydra ci so they can flow into run. --dry-run and --local are mutually exclusive:

Flag	Description
`--dry-run`	Run without changing files, pushing, or notifying (full simulation)
`--local`	Commit in-repo only; no push, MR, OCI push, or webhooks
`--target-branch`	Commit on this existing branch (no autogenerated branch)
`--promote-to`	Limit `promote` / `auto` to `--promote-to` env; skip other pairs

Workflow: Release and promote¶

Typical flow in the charts repository (where .hydra-ci.yaml lives):

Edit charts under apps/<group>/<child>/<env>/ (for example bump an upstream dependency in Chart.yaml or adjust values.yaml).
Release in dev (or the environment you changed): run hydra ci run release --dry-run .hydra-ci.yaml to inspect planned wrapper and root versions, then hydra ci run release --local .hydra-ci.yaml (or your CI job once CI mode is implemented) so wrapper version, root values.yaml, root Chart.yaml, one commit, and Git tags (including build-<UTC time>) are created.
Promote across environments: use hydra ci run promote .hydra-ci.yaml so each chart that differs is copied dev → stage and later stage → prod on dedicated branches (hydra/promote/to-stage/..., hydra/promote/to-prod/...). Chart version strings get their environment suffix rewritten. When the source chart used a Hydra extra counter (after multiple dev releases on the same dependency base), promote does not copy that counter: for example 1.0.0-2-dev becomes 1.0.0-stage unless the target chart already occupies the base line 1.0.0-stage, in which case the promoted version is 1.0.0-1-stage (and analogously stage → prod). A source without an extra counter still maps to the base target line (for example 1.2.3-dev → 1.2.3-stage) even when that version already exists on the target (no-op / content-only promote). Simple cases remain 1.2.3-dev → 1.2.3-stage → 1.2.3. Merge requests then carry the change into the target environment directory.

Version examples (child wrapper)¶

Re-release same dependency, values-only change: the canonical wrapper is already x.y.z-dev for dependency x.y.z. The next release inserts an extra counter before the suffix, for example x.y.z-dev → x.y.z-1-dev → x.y.z-2-dev.
Dependency version bump (new upstream): you set dependencies[].version (for example from a.b.c to a.b.d in Chart.yaml). The next release derives the wrapper from the new dependency and updates the root app pin under apps.<child>.version and bumps the middle number of the root app chart version.
Re-release same wrapper base, values-only (extra counter): as in the first bullet, the child becomes x.y.z-1-dev (or -2, …). The root app chart version then bumps the third number only (for example 200.22.0-dev → 200.22.1-dev); a dependency/base change in any child in that release still uses a middle-number bump for the root app.
No upstream dependency block: some charts have an empty dependencies list (standalone values-only layout). The release step then uses the chart's current version field as the semver base (strip env suffix and extra counter), recomputes the wrapper for the directory's environment (for example 0.1.0-dev → 0.1.0-1-dev when files changed but the base is unchanged), and updates the root pin the same way.

See Pipeline: release (developer doc) for the exact algorithms.

Default `auto` pipeline order¶

When ci.autoSteps is omitted from .hydra-ci.yaml, hydra ci run auto runs:

download → test → release → publish → promote → sync → update → sprint → upgrade

Override with ci.autoSteps (non-empty list of those names only). If autoSteps is present but empty, configuration is invalid.

Stages that are not implemented yet fail immediately. hydra ci run auto remains fail-fast and stops at the first stage error.

Subcommands¶

hydra ci run auto¶

Runs multiple CI stages sequentially using the same flags as the individual commands. Reads .hydra-ci.yaml from config-path (file or directory). Logs the current branch of the charts Git repository (derived from ci.rootAppsPath). Fail-fast: stops at the first error and does not continue.

hydra ci run auto <config-path> [flags]

Optional in .hydra-ci.yaml:

ci:
  autoSteps:
    - release
    - promote

hydra ci run download¶

Download dependencies for changed charts.

hydra ci run download <config-path>

hydra ci run test¶

Detect changed charts, require dependencies to be present locally, and run helm lint and helm template on each.

hydra ci run test <config-path>

hydra ci run release¶

Detect changed child chart directories (build-tag based), bump each child wrapper version from Chart.yaml dependencies when present (otherwise from the chart's own version semver base so -dev / -stage stay consistent), then update the matching apps/<group>/root/<env>/ chart, then create a single commit and lightweight tags (<group>-<app>-<version>, <group>-root-<version>, build-<UTC time>) when using --local. --dry-run prints the plan without writing files. Default CI mode (no --dry-run / --local) is not yet connected to remote operations.

hydra ci run release <config-path>

hydra ci run promote¶

Compare chart trees between environments, create branches under hydra/promote/to-<env>/..., copy files, rewrite version suffixes, and open merge requests (dev→stage, stage→prod, unless narrowed by --promote-to).

hydra ci run promote <config-path>

hydra ci run publish¶

Runs after a local or CI release that created lightweight tags on one commit: at least one build-<UTCYYYYMMDDHHmm> tag plus documentation tags (<group>-<app>-<version>, <group>-root-<version>) on the same commit as HEAD. Hydra maps those tags to chart directories under ci.rootAppsPath, then for each chart:

helm dependency update (via the same logic as hydra ci run download; skips work when there are no dependencies).
helm package into a temporary directory.
Sign the chart and write provenance metadata unless --skip-signing is set.
helm push only in default CI mode (requires a non-empty ci.registry, typically oci://…).

Modes¶

--dry-run: Log which charts would be packaged and the push target; no helm calls and no writes under the chart trees beyond what logging implies.
--local: Package charts locally; no helm push (same no-OCI-upload rule as other hydra ci run --local stages).
Default (CI): Package and helm push each .tgz to ci.registry. The job must already be logged in (helm registry login or runner credentials).
--skip-signing: Package and optionally push charts without provenance signatures. Hydra logs this as a warning.

Selecting charts explicitly¶

Use --chart <group>/<app>/<env> (repeatable) to publish only selected charts.
You can also pass a repo-relative chart path such as apps/demo/service-ui/dev.
When --chart is omitted, publish still requires the release tags and build-* tag to point to HEAD.
When --chart is used, Hydra resolves the expected release tag from each selected chart's Chart.yaml version and checks whether HEAD matches that publish commit.
If HEAD does not match, Hydra logs an error and aborts unless --force-run is set.
In CI mode, Hydra skips uploads when the same chart version already exists remotely unless --force-publish-upload is set.

App groups¶

Tag parsing uses ci.appGroups[].name (longest match first). If appGroups is empty, group names are inferred from existing chart directories under ci.rootAppsPath.

Orchestration¶

A green hydra ci run test on the same ref is expected to be enforced by your CI system before publish; the CLI does not query pipeline status.

hydra ci run publish <config-path>

hydra ci run verify¶

Validates the provenance signatures of charts that are already published in the OCI registry. See verify.md for the full reference.

hydra ci run verify <config-path>

hydra ci run validate remains as a hidden deprecated alias for verify.

hydra ci run sprint¶

If a sprint boundary is crossed, bump the major version of all root apps for dev, stage, and prod.

hydra ci run sprint <config-path>

hydra ci run upgrade¶

Take service name and version from an external service deployment pipeline, update the Chart.yaml dependency in dev, validate, then push or open an MR if unit test data also changed.

hydra ci run upgrade <config-path>

hydra ci run sync¶

Synchronize cluster configuration from external cluster repositories into the current repository and run the update pipeline.

hydra ci run sync <config-path>

hydra ci run update¶

Render all charts for all cluster definitions, commit any changed unit test data, and enforce the one-auto-commit governance rule.

hydra ci run update <config-path>

hydra ci secrets¶

Manage the SOPS-encrypted CI secret file configured by ci.secretsPath (or the default sibling .hydra-ci-secrets.sops.yaml). Public signing metadata is written into ci.sign in .hydra-ci.yaml and must stay identical to the private signing key in the secrets file.

hydra ci secrets create¶

Generate a new encrypted CI secrets file containing signing keys for Helm provenance and/or Cosign OCI signatures.

hydra ci secrets create <config-path> --name "<User ID>" [--force] [--signers both|helm|cosign]

Flag	Description
`--name`	Required. User ID to embed into the generated signing key (e.g. `"Hydra CI <ci@example.com>"`)
`--force`	Overwrite the existing secrets file if it already exists
`--signers`	Which signing material to generate: `both` (default), `helm`, or `cosign`

hydra ci secrets show¶

Decrypt and print the CI secrets file to stdout.

hydra ci secrets show <config-path>

hydra ci config¶

Interactively create or edit .hydra-ci.yaml (all fields, guided defaults).

hydra ci config <path> [--no-color]

Examples¶

# Download dependencies, then validate changed charts before merging
hydra ci run download .hydra-ci.yaml
hydra ci run test .hydra-ci.yaml

# Dry-run a release to see what would happen
hydra ci run release .hydra-ci.yaml --dry-run

# Release and publish in CI
hydra ci run release .hydra-ci.yaml && hydra ci run publish .hydra-ci.yaml

# Promote changes to staging only
hydra ci run promote .hydra-ci.yaml --promote-to staging

# Local release for testing (no push, no MRs)
hydra ci run release .hydra-ci.yaml --local

# Create/edit CI config interactively
hydra ci config .hydra-ci.yaml

# Run the default pipeline sequence (stops at first error)
hydra ci run auto .hydra-ci.yaml --dry-run