Nine repos, one intent, five spellings
Nobody decided this. It's what copy-paste does over two years. Updating means opening nine PRs by hand, so it doesn't happen.
For platform & DevEx teams with many repos
v0.1 · pre-release · not yet on npm
Ship a CI change to 80 repos as one release. Write workflows as TypeScript, publish them as an npm package, and let Renovate deliver every change, breaking ones included, as a migrated, SHA-pinned PR in each repo. Stop using it and the committed YAML keeps working.
@acme/wf-node-ci 2.0.0 fans out into pull requests in acme/api, acme/web, acme/billing, acme/auth and acme/search. Each PR changes the config, the generated ci.yml and the lockfile, and passes cikick check.The problem
Every repo got its workflow by copying the last one. Then each copy lived its own life.
Nobody decided this. It's what copy-paste does over two years. Updating means opening nine PRs by hand, so it doesn't happen.
Distributing the new value is a ticket per repo, tracked in someone's spreadsheet. Seven repos keep running on the key you meant to retire.
This is not hypothetical: in March 2025 the widely usedtj-actions/changed-files action was compromised and its existing version tags were re-pointed at a commit that printed secrets into workflow logs (CVE-2025-30066). Workflows pinned to a full commit SHA kept running the commit they had been reviewed against. The fix is old advice: pin by SHA. cikick does it at every synth and records it in a lockfile; cikick lock --refresh moves the pins forward.
The idea
Like AWS CDK, but for workflows. You describe CI as typed TypeScript objects; cikick synth walks the construct tree and writes plain .github/workflows/*.yml, resolves every action to a commit SHA, and records it incikick.lock.json. The generated YAML runs without cikick; cikick check is an optional CI gate.
cikick.config.tsimport { NodeCi } from '@acme/wf-node-ci';import { applyBaseline } from '@cikick/policies'; export default (app) => { new NodeCi(app, 'node', { nodeVersion: 22, packageManager: 'pnpm', }); applyBaseline(app); // policies};
# Generated by cikick — do not edit. Run `npx cikick synth`.name: CIon: # push to main, pull_requestpermissions: contents: readjobs: build: timeout-minutes: 30 steps: - uses: actions/checkout@11d5960a3267… # v4 - uses: pnpm/action-setup@b906affcce14… # v4 - uses: actions/setup-node@49933ea5288c… # v4 # …
{ "actions": { "actions/checkout@v4": { "sha": "11d5960a3267…", "resolvedAt": "2026-11-22T10:36Z" }, … }, "packages": { "@acme/wf-node-ci": "2.0.0" }}
A cikick.config.ts file that instantiates a NodeCi construct is synthesized (via a construct tree) and rendered to ci.yml where every action is pinned to a commit SHA with a version comment, plus a cikick.lock.json recording each resolved SHA.
In between: synth builds a construct tree (App → NodeCi → Workflow → Jobs, plus managed files like renovate.json). Aspects visit every node to add permissions or timeouts, or rewrite deprecated actions.
@acme/wf-node-ci; repos depend on it like any library.addOverride) and aspects. No fork needed.git ls-remote and recorded in the lockfile. cikick lock --refresh re-resolves them; run it on a schedule (e.g. a weekly workflow) and review the resulting diff.cikick check fails CI if it drifts from the config.The update loop
The platform team releases a new major. Every repo gets a PR that already contains the migration. Humans review a diff; nobody hunts for a Slack thread.
shared package repo
A breaking rename ships with a codemod. One release, written once by the platform team.
every consumer repo
It bumps the dependency like any other, and runs npx cikick update as a post-upgrade task.
in the PR branch
Migrations between the locked and installed versions run in order, editing cikick.config.ts with ts-morph.
$ npx cikick update@acme/wf-node-ci: 1.4.0 -> 2.0.0migrate @acme/wf-node-ci@2.0.0: Rename NodeCi prop `node` to `nodeVersion`…renamed 1 `node` prop(s) to `nodeVersion`deleted legacy .github/workflows/node.ymlwrote .github/workflows/ci.ymlwrote cikick.lock.json
in the PR branch
The config edit and the file changes land in one PR, so a reviewer sees exactly what changed before anything merges.
cikick.config.ts- new NodeCi(app, 'node', { node: 22 })+ new NodeCi(app, 'node', { nodeVersion: 22 }).github/workflows/node.yml- (legacy generated file removed).github/workflows/ci.yml- node-version: 20+ node-version: 22cikick.lock.json- "packages": { "@acme/wf-node-ci": "1.4.0" }+ "packages": { "@acme/wf-node-ci": "2.0.0" }
in CI
Generated files match the config, the lock covers every action, and policy checks pass. Merge.
check passed npx cikick check exits 0
If a migration throws, cikick update stops with the error and exits non-zero. It does not synth or update the lockfile, so cikick check fails and the PR stays red. Edits the earlier migrations made are left in the working tree for you to inspect. Once cikick check is green, Renovate automerge is an option you can enable in your Renovate config.
Without a codemod you can still ship a check with enforceAfter: a warning today, a CI error after a date you choose.
Fleet
cikick-fleet works from a fleet.json allowlist that you select. It never means "everything in the org". Inventory, settings drift, secret age and rotation all run against that list. Anything outside it is refused.
$ cikick-fleet secrets report --group publishersstale acme/api NPM_TOKEN 212d (max 90)stale acme/web NPM_TOKEN 212d (max 90)… 7 more$ cikick-fleet secrets rotate NPM_TOKEN --group publishers \ --value-from-env NEW_NPM_TOKENDry run: nothing written. Re-run with --yes to rotate.$ … --yesupdated acme/api NPM_TOKENupdated acme/web NPM_TOKEN… 7 more
A terminal: a secrets report lists stale NPM_TOKEN secrets, then a dry-run and a confirmed rotate push a new value to each selected repository.
cikick-fleet pushes a value you provide to every selected repo or environment and reports its age. Minting and revoking at the provider (npm, cloud) is still yours.
cikick-fleet select lists repos you administer; you pick. Commands refuse any repo outside fleet.json.settings apply and secrets rotate write nothing without --yes.GITHUB_TOKEN or GH_TOKEN, and admin on each selected repo (select only lists repos where permissions.admin is true).settings apply writes repo settings, but rulesets are only reported as drift, never changed.cikick-fleet inventory and report --html show which repos run which shared-package version, and how many action references are unpinned.cikick-fleet covers per-repo and environment-scoped secrets, repos across several owners, and tells you how old each value is.secretPolicies give each secret a max age; secrets report exits non-zero when something is stale or missing.Why not just…
Most of these are better than cikick at the thing they do. cikick earns its place only when you need shared, versioned, migratable workflows across many repos.
| Capability | cikick | Reusable workflows | Composite actions | Org rulesets / required workflows | Org-level secrets | Renovate / Dependabot | File sync / multi-repo PR tools | projen | github-workflows-kt | zizmor / actionlint |
|---|---|---|---|---|---|---|---|---|---|---|
| Shared across repos | Yes: npm packages | Yes: native | Partial: steps only | Yes: enforced centrally | Yes | No: per-repo copies | Partial: copy files out | Yes: npm packages | Partial: Kotlin scripts/libs | Not applicable: analysis only |
| Per-repo customisation | Yes: props, addOverride, aspects | Partial: inputs, secrets, job-level settings; not steps | Partial: inputs only | No: same workflow everywhere | Partial: select repos; one value | Not applicable | Partial: via templating (unverified) | Yes: escape hatches | Yes: code | Not applicable |
| Breaking-change migrations | Yes: versioned codemods via cikick update | No | No | No | Not applicable | No: bumps strings | Partial: scripted, not versioned | Partial: re-synth; breaks surface as compile errors, no shipped codemods (unverified) | No: (unverified) | No |
| SHA pinning | Yes: at synth (refresh is manual: lock --refresh) | Partial: caller pins @sha by hand | Partial: by hand | Partial: by hand in the one file | Not applicable | Yes: Renovate digest pinning; Dependabot bumps SHAs (pinning on its own: unverified) | No | Unverified: unverified | Unverified: unverified | Partial: flags unpinned uses (zizmor) |
| Lockfile | Yes: cikick.lock.json | No | No | No | Not applicable | No | No | Unverified: unverified | No: (unverified) | No |
| Secret distribution / fleet ops | Partial: age report + push a value to selected repos; no mint/revoke | No | No | No | Partial: one value, many repos; no age policy | No | No | No | No | No |
| Static analysis | Partial: 5 stock checks + custom Checks | No | No | No | Not applicable | No | No | No | Yes: typed action inputs | Yes: deeper than cikick |
| No build step | No: synth step | Yes | Yes | Yes | Yes | Yes | Yes | No: synth step | No: script step | Yes |
| Maturity | No: 0.1, unpublished | Yes: GA | Yes: GA | Yes: plan availability: unverified | Yes | Yes | Partial: varies | Yes: widely used | Partial: active, niche | Yes |
Third-party cells reflect our reading of their docs as of Nov 2026; cells marked ? or "unverified" are ones we have not confirmed. Corrections welcome.
permissions, strategy, concurrency, if, needs) but cannot add or change a step inside the called jobs. Each caller pins its own @ref and needs a bump PR; orgs that use @main skip those PRs, at the cost of unreviewed changes going live in every repo at once. A cikick Job can uses: a reusable workflow and cikick pins its ref.uses:. They cannot define jobs, triggers, permissions or needs, so the workflow skeleton is still copy-pasted. Keep them; cikick generates the skeleton that calls them..github repo help new repos begin from a good default. They are copied once, so later changes do not reach existing repos.helpers:pinGitHubActionDigests). They bump strings and do not know your shared workflow renamed an input. cikick uses Renovate as the delivery truck, then runs cikick update.with: inputs are checked at compile time. A real advantage in a Kotlin shop that cikick lacks. An alternative, not a companion; choose by language.package.json with cikick as a dev dependency.Quickstart
This clones the cikick monorepo, builds every package from source, then runs cikick check onexamples/consumer: a repo that uses a shared package, with its generated ci.yml andcikick.lock.json committed. The check verifies they match the config, offline.
cikick is pre-release (0.1.0) and its packages are not yet published to a registry, so there is no npm install yet. The guide covers wiring it into your own repo.
git clone https://github.com/cikick/cikick && cd cikick # the 2nd install links the built bins pnpm install && pnpm build && pnpm install cd examples/consumer && pnpm exec cikick check