Quickstart
You will turn a repository’s GitHub Actions workflows into TypeScript that cikick synthesizes into pinned .github/workflows/*.yml plus a cikick.lock.json. By the end you will have committed generated workflows, a CI-ready cikick check, the @cikick/policies baseline and a shared workflow package in use.
Prerequisites
Section titled “Prerequisites”- Node.js and a
package.jsonin the repository root. cikick discovers shared packages from thedependenciesanddevDependenciesof thatpackage.json. giton the PATH and network access togithub.comfor the firstsynth. Action refs such asactions/checkout@v4are resolved to commit SHAs withgit ls-remote; no token is needed. If that fails, cikick falls back to the GitHub commits API and usesGITHUB_TOKENwhen it is set.
1. Install
Section titled “1. Install”npm install --save-dev @cikick/cli @cikick/core @cikick/policies@cikick/cli provides the cikick binary. @cikick/core is what your config imports (App, Workflow, secret, …). @cikick/policies is optional and used in step 5.
2. Initialize
Section titled “2. Initialize”npx cikick initinit writes a starter cikick.config.ts in the current directory (or in --dir <repo>). If one already exists it leaves it untouched. Output:
wrote cikick.config.ts
Add to package.json: "scripts": { "cikick:synth": "cikick synth", "cikick:check": "cikick check" }
Sample renovate.json:{ "extends": ["config:recommended"], "packageRules": [ { "matchPackageNames": ["@cikick/**", "@your-org/wf-**"], "postUpgradeTasks": { "commands": ["npx cikick update"], "fileFilters": [".github/**", "cikick.lock.json", "cikick.config.ts"], "executionMode": "branch" } } ]}init only prints the scripts and Renovate snippets. It does not edit package.json or renovate.json. See Renovate for what the snippet does.
The starter config:
import { App, Workflow } from '@cikick/core';
export default (app: App) => { const ci = new Workflow(app, 'ci', { name: 'CI', on: { push: { branches: ['main'] }, pull_request: {} }, permissions: { contents: 'read' }, }); const job = ci.addJob('test', { runsOn: 'ubuntu-latest', timeoutMinutes: 15 }); job.addStep({ uses: 'actions/checkout@v4' }); job.addStep({ run: 'echo hello from cikick' });};The config file is cikick.config.ts (also accepted: .mts, .js, .mjs). Its default export is either a function (app) => void | Promise<void> or an App instance. The workflow id ('ci') becomes the file name: .github/workflows/ci.yml. See Constructs and synth.
3. Synthesize
Section titled “3. Synthesize”npx cikick synthwrote .github/workflows/ci.ymlwrote cikick.lock.jsonsynth writes every generated file, then cikick.lock.json, and prints any check findings after the wrote lines. Files in seeded mode that already exist are not overwritten; they print as kept <path> (seeded). See Managed files.
The generated workflow:
# Generated by cikick — do not edit. Run `npx cikick synth`.name: CIon: push: branches: - main pull_request: {}permissions: contents: readjobs: test: runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - run: echo hello from cikickThe SHA shown is what the lockfile recorded at the time of writing; yours will be whatever v4 points to when you run synth. The lockfile records each resolved action:
{ "actions": { "actions/checkout@v4": { "resolvedAt": "2026-11-22T10:36:56.498Z", "sha": "11d5960a326750d5838078e36cf38b85af677262" } }, "packages": {}, "version": 1}Commit both the generated workflows and the lockfile:
git add .github/workflows cikick.lock.json cikick.config.ts package.jsongit commit -m "Adopt cikick"See Lockfile and pinning for how the lock is used and refreshed.
4. Check
Section titled “4. Check”npx cikick checkcheck recomputes everything in frozen mode (no network, lock entries required), compares it with what is on disk and runs all checks. If nothing is wrong it prints nothing and exits 0. Otherwise it lists drift and findings and exits 1:
drift: .github/workflows/ci.ymlWARN [@acme/wf-node-ci:nvmrc-min-node] .nvmrc: Node 18 is end-of-life; set nodeVersion >= 20 in NodeCiGenerated files are out of date. Run `npx cikick synth` and commit.(The WARN line is a finding from the check shipped by the example shared package from step 6; it is shown to illustrate the format and would not appear in the starter setup.)
Drift lines are drift: <path>. Findings are SEVERITY [check-id] path: message, where severity is ERROR, WARN or INFO (padded to five characters). Warnings alone do not fail the command. Run it in CI so drift cannot be merged.
5. Add the policy baseline
Section titled “5. Add the policy baseline”@cikick/policies adds least-privilege defaults and a set of stock checks. Add one call at the end of your config:
import { App, Workflow } from '@cikick/core';import { applyBaseline } from '@cikick/policies';
export default (app: App) => { // ... your workflows ... applyBaseline(app);};applyBaseline(app) registers:
- aspects:
ExplicitPermissions(sets workflow-levelpermissions: { contents: read }where none is declared) andDefaultTimeout(setstimeout-minutes: 30on jobs that have none); - checks:
require-pinned-actions,require-explicit-permissions,no-pull-request-target-checkout,no-script-injection(warn) andrequire-timeout(warn).
Both accept options: applyBaseline(app, { timeoutMinutes: 20, permissions: { default: { contents: 'read', pullRequests: 'write' } } }). Run npx cikick synth again and commit. See Checks and the policies reference.
6. Use a shared workflow package
Section titled “6. Use a shared workflow package”Shared packages are ordinary npm packages whose package.json has a cikick field. cikick finds them among your direct dependencies. This is how the example consumer in the repository uses @acme/wf-node-ci (an example package; substitute your organisation’s package):
npm install --save-dev @acme/wf-node-ciimport { Workflow, secret, type App } from '@cikick/core';import { applyBaseline } from '@cikick/policies';import { NodeCi } from '@acme/wf-node-ci';
export default (app: App) => { const ci = new NodeCi(app, 'node', { nodeVersion: 22, packageManager: 'pnpm', test: 'pnpm test -- --coverage', release: {}, extraSteps: [ { name: 'Upload coverage', uses: 'actions/upload-artifact@v4', with: { name: 'coverage', path: 'coverage' } }, ], });
// Escape hatches into the shared construct ci.testJob.addOverride('runs-on', 'ubuntu-24.04'); ci.testJob.addOverride('env.CI', 'true'); ci.buildJob.props.runsOn = ['self-hosted', 'linux']; ci.workflow.addOverride('concurrency.cancel-in-progress', false);
// Custom workflow with an environment-scoped secret const deploy = new Workflow(app, 'deploy', { name: 'Deploy', on: { workflowDispatch: {} } }); const job = deploy.addJob('deploy', { runsOn: 'ubuntu-latest', environment: 'production' }); job.addStep({ uses: 'actions/checkout@v4' }); job.addStep({ name: 'Deploy', run: './scripts/deploy.sh', env: { DEPLOY_KEY: secret(app, 'DEPLOY_KEY', { scope: 'env', environment: 'production', maxAgeDays: 30 }) }, });
applyBaseline(app);};NodeCi (id node) creates the workflow ci (so the file is ci.yml, not node.yml), a managed .nvmrc and a merged renovate.json. npx cikick synth then writes:
wrote .github/workflows/ci.ymlwrote .github/workflows/deploy.ymlwrote .nvmrcwrote renovate.jsonwrote cikick.lock.jsonExcerpt of the generated ci.yml (middle sections elided with # ...). Notice the overrides (runs-on, CI: "true", cancel-in-progress: false) and the baseline’s permissions and timeout-minutes:
# Generated by cikick — do not edit. Run `npx cikick synth`.name: CIon: push: branches: - main tags: - v* pull_request: {}permissions: contents: readconcurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: falsejobs: build: runs-on: - self-hosted - linux timeout-minutes: 30 steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4 - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: 22 cache: pnpm - name: Install run: pnpm install --frozen-lockfile # ... Lint, Build test: needs: build runs-on: ubuntu-24.04 timeout-minutes: 30 steps: # ... checkout, pnpm, setup-node, Install - name: Test run: pnpm test -- --coverage - name: Upload coverage uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: name: coverage path: coverage env: CI: 'true' release: # ... tag-triggered publish job, uses ${{ secrets.NPM_TOKEN }}The lockfile now also records the package version, which cikick update uses to decide which migrations to run:
{ "actions": { "...": "..." }, "packages": { "@acme/wf-node-ci": "2.0.0" }, "version": 1}See what secrets your workflows reference:
npx cikick secretsNAME SCOPE ENVIRONMENT MAX AGE (d) PROVIDERDEPLOY_KEY env production 30 -NPM_TOKEN repo - 90 npm(--json prints the manifest as JSON.) Secrets explains how cikick-fleet uses this.
Next steps
Section titled “Next steps”- Run
cikick checkin CI. - Set up Renovate so package bumps regenerate workflows and run migrations.
- Fleet setup to operate on many repositories.
- Author your own shared package.
- Command details: cikick CLI reference.
Troubleshooting
Section titled “Troubleshooting”“No cikick.config.ts (or .js/.mjs) found in
cd or pass --dir <repo> (every command accepts it).
“default export must be an App or a function (app) => void”. The config must export default a function or an App; a named export is not picked up.
Synth fails with Failed to resolve owner/repo@ref: ref not found. The ref is not a tag or branch on github.com/owner/repo, or the network is unavailable. Tags win over branches when both exist.
A shared package is ignored. It is only discovered when it is listed in your package.json dependencies or devDependencies, is installed in node_modules, and its installed package.json has a string cikick field.
After upgrading a shared package by hand, run npx cikick update, not synth. synth records the installed package versions in cikick.lock.json; if you only synth, the version is overwritten and the package’s migrations will never run. See Migrations.