gitlab-ci-ts

Write your GitLab CI/CD pipelines in TypeScript. Types are automatically generated from the official GitLab CI schema.

Installation

You can install the package via npm or yarn:

``bash
npm install @sleeyax/gitlab-ci-ts


or


pnpm add @sleeyax/gitlab-ci-ts
`

Usage

Here's an example of how to use the library to create a GitLab CI/CD pipeline:

`typescript
import { Cache, GitLabCI, transformToFile } from "@sleeyax/gitlab-ci-ts";

// Reusable caches
const nodeCache: Cache = {
key: { files: ["package-lock.json"] },
paths: [".npm/"],
};

const distCache: Cache = {
key: "$CI_COMMIT_REF_SLUG-dist",
paths: ["dist/"],
};

// General-purpose pipeline
export const pipeline: GitLabCI = {
default: {
image: "node:20",
cache: [nodeCache],
},

variables: {
GIT_DEPTH: 0,
},

stages: ["verify", "test", "build", "deploy"],

jobs: {
// Hidden job to share install steps
".install": {
stage: "verify",
before_script: ["npm ci --prefer-offline --no-audit --if-present"],
interruptible: true,
cache: [nodeCache],
},

lint: {
extends: ".install",
stage: "verify",
script: ["npm run lint --if-present"],
rules: [{ if: "$CI" }],
},

test: {
extends: ".install",
stage: "test",
script: ["npm test --if-present"],
artifacts: { reports: { junit: "reports/junit.xml" } },
},

build: {
extends: ".install",
stage: "build",
script: ["npm run build --if-present"],
cache: [distCache, nodeCache],
artifacts: { paths: ["dist/"] },
},

// Optional: containerize and push (works with GitLab Container Registry)
docker_push: {
image: "docker:28",
services: ["docker:28-dind"],
stage: "deploy",
before_script: [
'echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin',
],
script: [
"docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .",
"docker push $CI_REGISTRY_IMAGE --all-tags",
],
rules: [{ if: "$CI" }],
},
},
};

// Write .gitlab-ci.yml
await transformToFile(pipeline, ".gitlab-ci.yml");
`

The above code defines a GitLab CI/CD pipeline with stages for verification, testing, building, and deployment. It includes reusable cache configurations and a hidden job for installation steps. The final step writes the generated pipeline configuration to a .gitlab-ci.yml file, which can be used directly by GitLab CI/CD.

Developers

Information for developers who (want to) contribute to the project.

$3

You can regenerate the types from the latest GitLab CI schema with:

`bash
pnpm run generate-types
``

#### Schema sources

- https://gitlab.com/gitlab-org/gitlab-foss/-/blob/53b1d7b11d91266febc9fcfcdba80f98ab28ab29/app/assets/javascripts/editor/schema/ci.json