GitLab Integration

CAPA pulls skills from GitLab repositories. The flow mirrors the GitHub integration, including nested groups, OAuth, and version pinning.

Adding Skills from GitLab

Using the CLI

Add GitLab skills using the gitlab: prefix. GitLab nested groups are supported (any number of path segments before the project name):

# Recursive search by skill folder name
capa add gitlab:mygroup/myrepo@web-researcher

# Nested groups
capa add gitlab:mygroup/subgroup/skills@data-analyst

# Exact path inside the repo (use "::" when names collide)
capa add gitlab:mygroup/skills::skills/team/web-researcher

# Pin to a tag or commit
capa add gitlab:mygroup/myrepo@web-researcher:v1.2.0
capa add gitlab:mygroup/myrepo@web-researcher#abc1234

# Add from a GitLab skill URL
capa add https://gitlab.com/mygroup/myrepo/-/tree/main/skills/web-researcher

Manual Configuration

Add GitLab skills directly in your capabilities file:

skills:
  - id: custom-skill
    type: gitlab
    def:
      repo: mygroup/subgroup/myrepo@skill-name
      description: Custom skill from GitLab
      requires:
        - '@server1.tool1'
        - '@server2.tool2'

Repository Format

GitLab skills use one of two grammars:

  • group[/subgroup...]/project@<name>: recursive search by directory name.
  • group[/subgroup...]/project::<path>: exact path inside the repo.

Each grammar accepts an optional :<tag-or-branch> or #<sha> suffix for pinning. CAPA records the resolved commit in capabilities.lock.

Examples

# Skill in a monorepo
myorg/agent-skills@web-researcher

# Nested group
myorg/subgroup/skills@data-analyst

# Exact path (no ambiguity if two skill folders share a name)
myorg/skills::skills/team-a/web-researcher

# Pinned to a tag
myorg/skills::skills/team-a/web-researcher:v1.2.0

GitLab Instances

GitLab.com (Default)

By default, CAPA uses gitlab.com:

capa add gitlab:mygroup/myrepo

Self-Hosted GitLab

For self-hosted GitLab instances, specify the full URL:

# Using full URL
capa add https://gitlab.mycompany.com/mygroup/myrepo.git

# In capabilities file
skills:
  - id: custom-skill
    type: remote
    def:
      url: https://gitlab.mycompany.com/mygroup/myrepo/-/raw/main/SKILL.md
      description: Skill from self-hosted GitLab
      requires:
        - tool1

Authentication

Public Repositories

No authentication required for public repositories on GitLab.com.

Private Repositories (Recommended: OAuth via CAPA)

The simplest way to install from a private GitLab project is to connect your account through the CAPA web UI:

  1. Start the server: capa start
  2. Open the web UI and navigate to the Integrations page.
  3. Click Connect GitLab and complete the OAuth flow.
  4. Run capa add gitlab:my-org/private-skills@team-helper. CAPA uses your stored token to clone the project.

If you try to add a private project without a token, CAPA prints a clear error pointing at the integrations URL. Raw GitLab URLs for private group projects silently return SAML login HTML (with HTTP 200), so CAPA always prefers authenticated git clones over raw URL fetches for private content.

Private Repositories (Alternative: Personal Access Token)

# Create a personal access token with read_repository scope, then:
export GITLAB_TOKEN=glpat-yourtoken
capa add gitlab:mygroup/private-skills@my-skill

Repository Structure

GitLab skill repositories follow the same structure as GitHub:

Single Skill

my-skill/
├── SKILL.md
└── README.md (optional)

Monorepo

agent-skills/
├── web-researcher/
│   └── SKILL.md
├── data-analyst/
│   └── SKILL.md
└── code-reviewer/
    └── SKILL.md

Branch, Tag, and Commit Support

Pin a version or commit with the :<tag-or-branch> or #<sha> suffix. The suffix is applied after the @name or ::path target:

# Specific tag or branch (note the colon between skill name and version)
capa add gitlab:mygroup/myrepo@my-skill:v1.0.0
capa add gitlab:mygroup/myrepo@my-skill:develop

# Specific commit (7-40 hex chars)
capa add gitlab:mygroup/myrepo@my-skill#a1b2c3d

# Pinned exact path
capa add gitlab:mygroup/myrepo::skills/data/analyst:v2.0.0

The resolved commit SHA is recorded in capabilities.lock so future installs use the same commit until you intentionally bump the version. To pull the latest commit for unpinned (floating) references, run capa install --no-cache.

CI/CD Integration

GitLab CI Example

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - curl -LsSf https://capa.infragate.ai/install.sh | sh
    - echo "GitLabToken=$CI_JOB_TOKEN" > .env
    - capa install -e
  only:
    - main

Creating Skills for GitLab

Skill Repository Setup

  1. Create a new GitLab project
  2. Add a SKILL.md file with proper frontmatter
  3. Add a descriptive README.md
  4. Tag releases for version tracking
  5. Configure appropriate visibility (public/private)

Example SKILL.md

---
name: my-gitlab-skill
description: Custom skill hosted on GitLab
---

# My GitLab Skill

Description and usage instructions.

## When to Use

- Use case 1
- Use case 2

## Required Tools

- tool_1
- tool_2

Best Practices

  • Use project access tokens: For CI/CD, use project-specific tokens instead of personal tokens
  • Pin versions: Use tags or specific commits for production deployments
  • Set up CI/CD: Automate skill testing and deployment
  • Document dependencies: Clearly list required tools and their versions
  • Mirror critical skills: Consider mirroring important external skills to your GitLab instance

Examples

Complete Configuration

providers:
  - cursor

skills:
  - id: data-analyst
    type: gitlab
    def:
      repo: gitlab:myorg/agent-skills@data-analyst
      requires:
        - pandas_query

tools:
  - id: pandas_query
    type: command
    def:
      init:
        cmd: pip install pandas
      run:
        cmd: python -c "import pandas as pd; df = pd.read_csv('{file}'); print(df.query('{query}'))"
        args:
          - name: file
            type: string
            required: true
          - name: query
            type: string
            required: true

Troubleshooting

Authentication Issues

  • Verify your GitLab token has read_repository scope
  • Check token expiration date
  • Ensure GITLAB_TOKEN environment variable is set
  • For self-hosted, verify network connectivity

Repository Not Found

  • Verify the group/project path is correct
  • Check repository visibility settings
  • Ensure you have access to the repository
  • Try accessing the repository URL in a browser

Skill File Not Found

  • Ensure SKILL.md exists in the repository root or specified subdirectory
  • Check file name capitalization (must be SKILL.md)
  • Verify branch/tag if specified

Related Documentation