GitLab CI pipelines in TypeScript
npm install @okeeffed/gitlab-ci-kitA TypeScript library for generating GitLab CI pipelines with type safety and auto-generated schema types.
GitLab CI Kit provides a programmatic way to define GitLab CI/CD pipelines using TypeScript instead of manually writing YAML. The library automatically generates TypeScript types from GitLab's official JSON schema, ensuring your pipelines are always compatible with the latest GitLab CI features.
Define your jobs and pipeline configuration in TypeScript, then synthesize them to valid GitLab CI YAML with automatic snake_case conversion.
- 🎯 Type-Safe Pipeline Definitions - Full TypeScript support with auto-generated types from GitLab's official schema
- 🔄 Auto-Generated Types - Types are generated directly from GitLab's CI JSON schema
- 🐍 Automatic snake_case Conversion - Write in camelCase, output in snake_case
- ✅ Built-in Validation - Catch configuration errors before committing
- 🎨 Clean YAML Output - Synthesizes to readable GitLab CI YAML
- 🧩 Composable Jobs - Build reusable job configurations with type safety
``bash`
npm install @okeeffed/gitlab-ci-kit
`typescript
import { Job, Rule, Default, synth } from '@okeeffed/gitlab-ci-kit';
// Define jobs with camelCase properties
const jobs = {
build: new Job({
stage: 'build',
image: 'node:20',
script: ['npm ci', 'npm run build'],
cache: {
key: '${CI_COMMIT_REF_SLUG}',
paths: ['node_modules/'],
},
artifacts: {
paths: ['dist/'],
expireIn: '1 week', // camelCase!
},
}),
test: new Job({
stage: 'test',
image: 'node:20',
script: ['npm test'],
beforeScript: ['npm ci'], // camelCase!
allowFailure: true, // camelCase!
}),
deploy: new Job({
stage: 'deploy',
image: 'node:20',
script: ['npm run deploy'],
rules: [
new Rule({ if: '$CI_COMMIT_BRANCH == "main"' }),
new Rule({
if: '$CI_PIPELINE_SOURCE == "merge_request_event"',
when: 'manual',
}),
],
environment: {
name: 'production',
url: 'https://example.com',
},
}),
};
// Pipeline configuration with camelCase
const config = {
variables: {
NODE_VERSION: '20',
},
stages: ['build', 'test', 'deploy'],
default: new Default({
idTokens: { // camelCase!
GITLAB_OIDC_TOKEN: {
aud: 'https://gitlab.com',
},
},
tags: ['docker'],
}),
};
// Generate YAML (automatically converts to snake_case)
const yaml = synth(jobs, config);
console.log(yaml);
`
Individual tasks that execute scripts, build artifacts, run tests, or deploy applications. Jobs are defined using the Job class with type-safe properties.
Workflow rules that determine when jobs run. Create rules using the Rule class.
Global default settings applied to all jobs. Define using the Default class.
The synthesizer function that converts your TypeScript job definitions and configuration into valid GitLab CI YAML, automatically converting camelCase properties to snake_case.
The library includes a script that fetches the latest GitLab CI JSON schema and generates TypeScript types:
`bash`
npm run generate:types
This ensures your pipeline definitions stay in sync with GitLab's latest features and validates your configuration against the official schema.
Schema Source: GitLab CI JSON Schema
`bashInstall dependencies
npm install
Examples
examples/` directory for complete pipeline examples.- Node.js >= 18.0.0
MIT