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)

Register a runner using authentication token (recommended approach):

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=&#x3C;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