GitLab Skill

Comprehensive assistance with GitLab development, operations, and DevOps workflows based on official documentation.

When to Use This Skill

This skill should be triggered when you need help with:

GitLab Runners: Registering runners, configuring executors (Docker, Kubernetes, Shell), troubleshooting runner issues
CI/CD Pipelines: Creating .gitlab-ci.yml files, defining jobs and stages, setting up workflows, validating configuration
OAuth & Authentication: Implementing OAuth 2.0 flows (PKCE, Authorization Code, Device Authorization), managing access tokens
Deploy Tokens: Creating and managing deploy tokens for automated deployments, container registry access, package registry operations
API Integration: Using GitLab GraphQL API, REST API authentication, managing projects and repositories programmatically
Container Registry: Pushing/pulling Docker images, managing registry permissions, using the dependency proxy
Package Registry: Publishing and consuming packages (npm, Maven, NuGet, PyPI), managing package permissions
Migration Tasks: Migrating from Jenkins or CircleCI to GitLab CI/CD
GitLab Administration: Monitoring GitLab instances, reference architectures, scaling strategies

Quick Reference

Common Patterns

1. Register a GitLab Runner (Docker)

# Linux/macOS
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

# Docker container
docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

2. Basic GitLab CI/CD Pipeline

Simple pipeline with build, test, and deploy stages:

# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building the application..."
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/

test_job:
  stage: test
  script:
    - echo "Running tests..."
    - npm test

deploy_job:
  stage: deploy
  script:
    - echo "Deploying to production..."
    - ./deploy.sh
  only:
    - main

3. OAuth 2.0 Access Token Request (PKCE)

Secure OAuth flow for public clients (SPAs, mobile apps):

# Request access token with PKCE
parameters = 'client_id=APP_ID&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER'
RestClient.post 'https://gitlab.example.com/oauth/token', parameters

Response:

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
  "created_at": 1607635748
}

4. Use Deploy Token with Docker Registry

Authenticate and pull/push images using deploy tokens:

# Login to GitLab Container Registry
echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com

# Pull image
docker pull registry.example.com/myproject/myimage:latest

# Push image
docker tag myimage:latest registry.example.com/myproject/myimage:latest
docker push registry.example.com/myproject/myimage:latest

5. GitLab CI with Docker Services

Run tests with database services:

# .gitlab-ci.yml
test:
  image: ruby:3.1
  services:
    - mysql:latest
    - redis:latest
  variables:
    MYSQL_ROOT_PASSWORD: secret
  script:
    - bundle install
    - bundle exec rspec

6. Clone Repository with Deploy Token

# Clone using deploy token
git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git

7. GraphQL API Authentication

# Header-based authentication
curl "https://gitlab.example.com/api/graphql" \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{"query": "query { currentUser { name } }"}'

# Parameter-based authentication
curl "https://gitlab.example.com/api/graphql?access_token=<token>" \
  --header "Content-Type: application/json" \
  --data '{"query": "query { currentUser { name } }"}'

8. Parallel Jobs in GitLab CI

# Jobs run in parallel by default
python_tests:
  image: python:3.9
  script:
    - pytest tests/

java_tests:
  image: openjdk:11
  script:
    - mvn test
  only:
    - staging

9. Kubernetes Resource Limits for AI Gateway

resources:
  requests:
    memory: "16Gi"
    cpu: "4"
  limits:
    memory: "32Gi"
    cpu: "8"

10. Scheduled Pipeline with Rules

nightly_build:
  script:
    - ./run_tests.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

Key Concepts

GitLab Runners

Runners are agents that execute CI/CD jobs. They can be:

Instance runners: Available to all projects in a GitLab instance
Group runners: Available to all projects in a group
Project runners: Dedicated to specific projects

Executor types:

Docker: Runs jobs in Docker containers (most common)
Kubernetes: Runs jobs in Kubernetes pods
Shell: Runs jobs directly on the runner machine
Docker-windows: For Windows containers

OAuth 2.0 Flows

GitLab supports multiple OAuth flows:

Authorization Code with PKCE: Most secure, recommended for SPAs and mobile apps
Authorization Code: Traditional flow for server-side apps
Device Authorization Grant: For input-constrained devices (headless servers, CLI tools)
Resource Owner Password Credentials: Legacy flow (use personal access tokens instead)

Deploy Tokens

Deploy tokens provide automated access without personal credentials:

Scopes: read_repository, write_repository, read_registry, write_registry, read_package_registry, write_package_registry
Special token: gitlab-deploy-token auto-exposes as CI_DEPLOY_USER and CI_DEPLOY_PASSWORD variables
Expiration: Optional, occurs at midnight UTC on specified date

CI/CD Stages

Jobs are organized into stages that run sequentially:

Jobs in the same stage run in parallel
Next stage waits for previous stage to complete
Pipeline fails if any job fails (unless configured otherwise)

Authentication Methods

Personal Access Tokens: For individual users
Project Access Tokens: For automation within a project
Deploy Tokens: For deployment automation
OAuth Tokens: For third-party applications
Session Cookies: For web UI access

Reference Files

This skill includes comprehensive documentation in references/:

administration.md - GitLab instance administration, monitoring, reference architectures, scaling strategies, and infrastructure requirements
api.md - OAuth 2.0 flows (PKCE, Authorization Code, Device Grant), GraphQL API basics, authentication methods, and token management
ci_cd.md - Runner registration, CI/CD pipeline syntax, job configuration, migration guides (Jenkins, CircleCI), and workflow patterns
getting_started.md - Initial setup, basic concepts, and beginner-friendly tutorials
security.md - Security best practices, token security, runner security, and DevSecOps workflows
user_guide.md - Day-to-day GitLab usage, merge requests, issue tracking, and collaboration features
other.md - Additional topics not covered in other categories

Use these files to find detailed documentation and advanced examples.

Working with This Skill

For Beginners

Start with these topics:

Read getting_started.md for foundational concepts
Learn about GitLab CI/CD basics in ci_cd.md
Understand authentication with api.md

First tasks:

Create a simple .gitlab-ci.yml pipeline
Register your first runner
Set up a deploy token for automated deployments

For CI/CD Engineers

Focus areas:

ci_cd.md - Advanced pipeline patterns, caching, artifacts, workflows
administration.md - Runner management, scaling strategies
Migration guides for Jenkins/CircleCI in ci_cd.md

Common tasks:

Configure parallel and sequential job execution
Set up scheduled pipelines
Optimize pipeline performance with caching
Migrate existing CI/CD workflows to GitLab

For DevOps/Platform Engineers

Key documentation:

administration.md - Reference architectures, monitoring, high availability
security.md - Security scanning, vulnerability management
api.md - Automation via GraphQL and REST APIs

Advanced tasks:

Design GitLab infrastructure at scale
Implement GitLab Geo for disaster recovery
Configure Kubernetes-based runners
Set up self-hosted AI Gateway

For Application Developers

Relevant sections:

Basic CI/CD in ci_cd.md
OAuth integration in api.md
Package/container registry in user_guide.md

Daily workflows:

Push code and trigger pipelines
Create and manage merge requests
Publish packages to GitLab registries
Integrate GitLab OAuth into applications

Navigation Tips

Need to find specific information?

Runners: See ci_cd.md → "Registering runners"
OAuth flows: See api.md → "OAuth 2.0 identity provider API"
Deploy tokens: See ci_cd.md or search in reference files
Pipeline syntax: See ci_cd.md → "Validate GitLab CI/CD configuration"
Migration: See ci_cd.md → "Migrate from Jenkins" or "Migrate from CircleCI"
Scaling: See administration.md → "Reference architectures"

Code examples:

Quick Reference section above has the most common patterns
Each reference file includes code examples from official documentation
Examples include proper language annotations for syntax highlighting

Resources

references/

Organized documentation extracted from official GitLab sources:

Detailed explanations of features and concepts
Real-world code examples with language detection
Links to original official documentation
Table of contents for quick navigation within each file

scripts/

Add helper scripts for common GitLab automation tasks:

Runner setup scripts
Deployment automation
API integration helpers

assets/

Add templates and boilerplate:

.gitlab-ci.yml templates for different tech stacks
OAuth integration examples
Kubernetes runner configurations

Best Practices

CI/CD Pipelines

Use rules: instead of deprecated only:/except:
Cache dependencies to speed up jobs
Use artifacts to pass data between stages
Set appropriate timeout values
Use variables for configuration

Security

Never commit tokens or secrets to repositories
Use CI/CD variables for sensitive data
Enable protected branches and protected tags
Use deploy tokens instead of personal credentials
Regularly rotate tokens and secrets

Runners

Use Docker executor for isolation
Don't run runners in privileged mode unless necessary
Use tags to target specific runners
Monitor runner performance and capacity
Keep runners updated

OAuth Integration

Always use PKCE for public clients
Use HTTPS for redirect URIs in production
Implement proper state validation for CSRF protection
Request minimal required scopes
Handle token refresh properly

Notes

This skill was automatically generated from official GitLab documentation
Reference files preserve structure and examples from source docs
Code examples include language detection for syntax highlighting
Quick reference patterns are extracted from common usage examples in the docs

Updating

To refresh this skill with updated documentation:

Re-run the scraper with the same configuration
The skill will be rebuilt with the latest information from GitLab docs