gitlab-ci

Q: How do I install gitlab-ci?

Run npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill gitlab-ci in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gitlab-ci/ (personal) or .claude/skills/gitlab-ci/ (project).

by bagelholeDevOps & Cloud

Configure GitLab CI/CD pipelines and runners for automated building, testing, and deployment. Create .gitlab-ci.yml configurations, manage runners, and implement DevOps workflows. Use when working with GitLab repositories or self-hosted GitLab instances.

Installs: 354
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill gitlab-ci

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads gitlab-ci automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

GitLab CI/CD

Automate your software delivery pipeline with GitLab's integrated CI/CD system.

When to Use This Skill

Use this skill when:

Setting up CI/CD pipelines in GitLab
Configuring GitLab runners (shared or self-hosted)
Creating multi-stage deployment pipelines
Implementing GitLab Auto DevOps
Managing CI/CD variables and secrets

Prerequisites

GitLab repository (gitlab.com or self-hosted)
Basic understanding of YAML
For self-hosted runners: Linux server or Kubernetes cluster

Pipeline Configuration

Create .gitlab-ci.yml in repository root:

stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "20"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test
  coverage: '/Coverage: \d+\.\d+%/'

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    url: https://example.com
  only:
    - main

Job Configuration

Rules-Based Execution

deploy:
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - when: on_success

Parallel Jobs

test:
  stage: test
  parallel: 3
  script:
    - npm test -- --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

Matrix Builds

test:
  stage: test
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        OS: ["alpine", "slim"]
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

Caching

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push

build:
  cache:
    key: build-cache
    paths:
      - .cache/
    policy: pull

Artifacts

build:
  artifacts:
    paths:
      - dist/
      - coverage/
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml
    expire_in: 1 week
    when: always

Environments and Deployments

deploy_staging:
  stage: deploy
  script:
    - deploy --env staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop_staging

stop_staging:
  stage: deploy
  script:
    - undeploy --env staging
  environment:
    name: staging
    action: stop
  when: manual

Docker Builds

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

GitLab Runners

Install Runner

# Download and install
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt install gitlab-runner

# Register runner
sudo gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token TOKEN \
  --executor docker \
  --docker-image alpine:latest

Runner Configuration

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = true
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]

Runner Tags

build:
  tags:
    - docker
    - linux
  script:
    - make build

CI/CD Variables

Protected Variables

Define in Settings > CI/CD > Variables:

AWS_ACCESS_KEY_ID (protected, masked)
AWS_SECRET_ACCESS_KEY (protected, masked)

Using Variables

deploy:
  script:
    - aws s3 sync dist/ s3://$S3_BUCKET
  variables:
    AWS_DEFAULT_REGION: us-east-1

Include and Extend

Include Templates

include:
  - template: Security/SAST.gitlab-ci.yml
  - project: 'group/shared-ci'
    file: '/templates/deploy.yml'
  - local: '/ci/jobs.yml'

Extend Jobs

.base_job:
  image: node:20
  before_script:
    - npm ci

build:
  extends: .base_job
  script:
    - npm run build

test:
  extends: .base_job
  script:
    - npm test

Multi-Project Pipelines

trigger_downstream:
  stage: deploy
  trigger:
    project: group/downstream-project
    branch: main
    strategy: depend

Common Issues

Issue: Pipeline Stuck

Problem: Jobs stay pending Solution: Check runner availability and tags matching

Issue: Docker-in-Docker Fails

Problem: Cannot connect to Docker daemon Solution: Use docker:dind service with proper TLS configuration

Issue: Cache Not Working

Problem: Cache misses between jobs Solution: Verify cache key and ensure runners share distributed cache

Best Practices

Use rules instead of only/except for complex conditions
Leverage GitLab's built-in security scanning templates
Use job dependencies to optimize pipeline speed
Implement review apps for merge requests
Cache dependencies aggressively
Use artifacts for passing data between stages

Related Skills

github-actions - GitHub CI/CD alternative
argocd-gitops - GitOps deployments
container-registries - Registry management

FAQ

What does the gitlab-ci skill do?

How do I install gitlab-ci?

Run npx skills add https://github.com/bagelhole/devops-security-agent-skills --skill gitlab-ci in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gitlab-ci/ (personal) or .claude/skills/gitlab-ci/ (project).

Which AI agents can use gitlab-ci?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is gitlab-ci safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains gitlab-ci?

It is published by bagelhole in bagelhole/devops-security-agent-skills. It has 354 recorded installs.