Add Step Registry

Add Step Registry Step

Create a new atomic step under ci-operator/step-registry/.

Before you start

• Run step-finder (or python3 .claude/scripts/step_finder.py "<query>") — reuse existing steps when possible.
• Read a similar step in the same area for from, env vars, credentials, and script patterns.
• Confirm the step belongs in step-registry (single task), not a one-off inline in one repo's config.

Scaffold files

Dry-run (prints target paths to stderr; add --preview to show generated bodies):

python3 .claude/scripts/scaffold_step_registry.py \
  --name <step-name> \
  --subdir <path-under-step-registry> \
  --from cli \
  --documentation "What this step does"

ImageStream-based step (uses from_image block instead of from alias):

python3 .claude/scripts/scaffold_step_registry.py \
  --name <step-name> \
  --subdir <path-under-step-registry> \
  --from-image-namespace <ns> \
  --from-image-name <name> \
  --from-image-tag <tag> \
  --write

Create files:

python3 .claude/scripts/scaffold_step_registry.py \
  --name <step-name> \
  --subdir <path-under-step-registry> \
  --from cli \
  --documentation "What this step does" \
  --write

Naming:

| Item | Rule |

|------|------|

| --name | lowercase, hyphens; becomes ref.as and ref: <name>; must not end with -step |

| files | <name>-ref.yaml, <name>-commands.sh |

| --subdir | e.g. myorg/install → ci-operator/step-registry/myorg/install/ |

Common from alias values: cli, tests, or another image alias from the consuming repo's ci-operator config. Use --from-image-* when the step needs an explicit ImageStream reference.

Implement the step

• Edit *-commands.sh:
• Start with set -euo pipefail (avoid -x unless debugging).
• Disable tracing around secrets/passwords (see root CLAUDE.md).
• Use ${SHARED_DIR} to pass data between steps; do not echo credentials.
• Edit *-ref.yaml:
• Add env entries with default + documentation for tunables.
• Set timeout, grace_period, resources if non-default.
• Add dependencies / credentials only when required (copy from similar steps).
• Add OWNERS under new top-level directories if no parent OWNERS covers the path.

Validate and regenerate

make registry-metadata

Registry load check (optional; make validate-step-registry may fail if the local configresolver image no longer accepts --prow-config):

podman run --rm \
  -v "$(pwd)/ci-operator/config:/config:z" \
  -v "$(pwd)/ci-operator/step-registry:/step-registry:z" \
  quay.io/openshift/ci-public:ci_ci-operator-configresolver_latest \
  --config /config --registry /step-registry --validate-only

If wiring into a ci-operator config in the same PR, also:

make update
make checkconfig

Wire into a test (same or follow-up PR)

In ci-operator/config/<org>/<repo>/<branch>.yaml:

tests:
- as: my-test
  steps:
    pre:
    - ref: <step-name>
    test:
    - ref: openshift-e2e-test

Or reference the step from a -chain.yaml / -workflow.yaml instead of directly in config.

Chains and workflows

This skill scaffolds steps only. For chains/workflows:

• Chain: new *-chain.yaml listing - ref: / - chain: steps; no commands script.
• Workflow: new *-workflow.yaml with pre / test / post phases.

Copy structure from an existing chain/workflow in the same platform area; run make validate-step-registry.

Checklist

• [ ] step-finder searched; no duplicate
• [ ] -ref.yaml + -commands.sh created and named consistently
• [ ] documentation field describes behavior
• [ ] secrets handled safely in shell
• [ ] make registry-metadata pass (and optional configresolver --validate-only above)
• [ ] referenced from config/chain/workflow if intended for use