Skip to content

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.

  • Node.js and a package.json in the repository root. cikick discovers shared packages from the dependencies and devDependencies of that package.json.
  • git on the PATH and network access to github.com for the first synth. Action refs such as actions/checkout@v4 are resolved to commit SHAs with git ls-remote; no token is needed. If that fails, cikick falls back to the GitHub commits API and uses GITHUB_TOKEN when it is set.
Terminal window
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.

Terminal window
npx cikick init

init 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:

cikick.config.ts
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.

Terminal window
npx cikick synth
wrote .github/workflows/ci.yml
wrote cikick.lock.json

synth 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:

.github/workflows/ci.yml
# Generated by cikick — do not edit. Run `npx cikick synth`.
name: CI
on:
push:
branches:
- main
pull_request: {}
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- run: echo hello from cikick

The 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:

cikick.lock.json
{
"actions": {
"actions/checkout@v4": {
"resolvedAt": "2026-11-22T10:36:56.498Z",
"sha": "11d5960a326750d5838078e36cf38b85af677262"
}
},
"packages": {},
"version": 1
}

Commit both the generated workflows and the lockfile:

Terminal window
git add .github/workflows cikick.lock.json cikick.config.ts package.json
git commit -m "Adopt cikick"

See Lockfile and pinning for how the lock is used and refreshed.

Terminal window
npx cikick check

check 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.yml
WARN [@acme/wf-node-ci:nvmrc-min-node] .nvmrc: Node 18 is end-of-life; set nodeVersion >= 20 in NodeCi
Generated 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.

@cikick/policies adds least-privilege defaults and a set of stock checks. Add one call at the end of your config:

cikick.config.ts
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-level permissions: { contents: read } where none is declared) and DefaultTimeout (sets timeout-minutes: 30 on jobs that have none);
  • checks: require-pinned-actions, require-explicit-permissions, no-pull-request-target-checkout, no-script-injection (warn) and require-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.

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):

Terminal window
npm install --save-dev @acme/wf-node-ci
cikick.config.ts
import { 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.yml
wrote .github/workflows/deploy.yml
wrote .nvmrc
wrote renovate.json
wrote cikick.lock.json

Excerpt 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:

.github/workflows/ci.yml
# Generated by cikick — do not edit. Run `npx cikick synth`.
name: CI
on:
push:
branches:
- main
tags:
- v*
pull_request: {}
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
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:

cikick.lock.json
{
"actions": { "...": "..." },
"packages": {
"@acme/wf-node-ci": "2.0.0"
},
"version": 1
}

See what secrets your workflows reference:

Terminal window
npx cikick secrets
NAME SCOPE ENVIRONMENT MAX AGE (d) PROVIDER
DEPLOY_KEY env production 30 -
NPM_TOKEN repo - 90 npm

(--json prints the manifest as JSON.) Secrets explains how cikick-fleet uses this.

“No cikick.config.ts (or .js/.mjs) found in

. Run npx cikick init.” You are not in the repository root. Use 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.