GitLab Integration

CAPA supports adding skills from GitLab repositories, providing the same functionality as GitHub integration for teams using GitLab.

Adding Skills from GitLab

Manual Configuration

Add GitLab skills directly in your capabilities file:

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

Repository Format

GitLab skills use the format: group/project[@skill-name]

  • group: GitLab group or username
  • project: Project name
  • skill-name (optional): Subdirectory containing the skill

Examples



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

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

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

For private repositories, configure GitLab authentication:

Option 1: Personal Access Token

# Create a personal access token with read_repository scope
# Set it as an environment variable
export GITLAB_TOKEN=glpat-yourtoken

# Add private skill
capa add gitlab:mygroup/private-skills

Option 2: SSH Authentication

# Use SSH URL
capa add git@gitlab.com:mygroup/myrepo.git

Option 3: .netrc File

Create a ~/.netrc file:

machine gitlab.com
login your-username
password glpat-yourtoken

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 and Tag Support

Specify branches or tags in the repository reference:

# Specific branch
capa add gitlab:mygroup/myrepo@develop

# Specific tag
capa add gitlab:mygroup/myrepo@v1.0.0

# Specific commit
capa add gitlab:mygroup/myrepo@a1b2c3d

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