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:

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:

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.

Sync schema

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

pnpm run generate-types

Schema sources

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