@change.codes/ci

Type-safe CI jobs for change.codes, executed with Bun in isolated sandboxes.

Install the authoring library as a development dependency:

bun add --dev @change.codes/ci

Every *.ci.ts or *.ci.js file below .change/ is one job. Its path is its stable id:

.change/test.ci.ts       → test
.change/web/build.ci.ts  → web/build

// .change/test.ci.ts
import { job, run } from '@change.codes/ci';

export default job({
	name: 'Tests',
	steps: [run('Install', 'bun install --frozen-lockfile'), run('Test', 'bun test')]
});

Use parallel() when independent commands should share the job sandbox and run together. The next stage starts after every command in the group finishes; if any command fails, later stages do not run.

import { job, parallel, run } from '@change.codes/ci';

export default job({
	steps: [
		run('Install', 'bun install --frozen-lockfile'),
		parallel(
			run('Lint', 'bun run lint'),
			run('Typecheck', 'bun run check'),
			run('Test', 'bun test')
		),
		run('Build', 'bun run build')
	]
});

Parallel commands use the same working directory and environment, so avoid commands that write the same files concurrently. A group can contain up to eight run() steps and cannot be nested.

Dependencies use the imported job value, so renames and invalid references are caught by TypeScript:

// .change/web/build.ci.ts
import { job, run, secret } from '@change.codes/ci';
import tests from '../test.ci';

export default job({
	name: 'Build web',
	needs: [tests],
	environment: {
		NODE_ENV: 'production',
		PUBLISH_TOKEN: secret('PUBLISH_TOKEN')
	},
	steps: [run('Build', 'bun run build')]
});

Ordinary files below .change/ can be imported as helpers. Files outside .change/ are not available while the job graph is being planned; the complete repository is available when a job runs.

Runtime metadata

The runtime helper validates the metadata injected into a running job:

import { context } from '@change.codes/ci';

const ci = context();
console.log(ci.sha, ci.ref, ci.repository.fullName, ci.runId, ci.jobId, ci.attempt);

Shell scripts and other languages can read the underlying CHANGE_CODES_* environment variables directly.