GitLab Integration

The GitLab integration connects your projects to Tapioca, enabling automatic time tracking evidence from commits, merge requests, and code reviews. GitLab’s built-in time tracking can also sync bidirectionally with Tapioca.

Overview

When connected, Tapioca receives webhook events from GitLab and:

1. Creates Evidence - Records commits, MRs, and reviews as work evidence
2. Links to Tasks - Automatically connects activity to tasks via ID patterns
3. Updates Status - Optionally moves tasks through workflow states
4. Syncs Time - Optionally syncs GitLab time tracking with Tapioca

Prerequisites

Before setting up the GitLab integration, ensure you have:

• Maintainer or Owner access to your GitLab group/project
• Admin access to your Tapioca organization
• A Tapioca project to link GitLab projects to

Installation

GitLab integration uses OAuth or Personal Access Tokens for authentication.

Method 1: OAuth (Recommended)

OAuth provides the best user experience and security:

OAuth Scopes Required:

Method 2: Personal Access Token

Use a PAT for simpler setup or when OAuth isn’t available:

Method 3: Group Access Token

For organization-wide access without personal credentials:

1. Go to your GitLab Group → Settings → Access Tokens
2. Create a token with api and read_repository scopes
3. Enter the token in Tapioca settings

This is ideal for CI/CD automation or shared team accounts.

Self-Hosted GitLab

Tapioca supports self-hosted GitLab instances (Community Edition and Enterprise Edition).

Configuration

Network Requirements:

• Tapioca must be able to reach your GitLab instance (outbound HTTPS)
• GitLab must be able to reach Tapioca for webhooks (inbound HTTPS)
• If using self-signed certificates, configure trusted CAs in Tapioca

GitLab.com vs Self-Hosted

Webhook Configuration

If using a PAT (non-OAuth), configure webhooks manually:

Adding a Webhook

1. Go to your GitLab project → Settings → Webhooks
2. Configure the webhook:

3. Click “Add webhook”

Testing Webhooks

After adding a webhook:

1. Click “Test” next to the webhook
2. Select an event type (e.g., “Merge request events”)
3. Check the result for success/failure
4. View details for error messages

Project Mapping

Link GitLab projects to Tapioca projects for automatic task association.

Setting Up Mappings

1. Go to Tapioca Settings → Integrations → GitLab → Project Mappings
2. Click “Add Mapping”
3. Select the GitLab project (namespace/project-name)
4. Choose the Tapioca project
5. Configure automation options

Mapping Options

GitLab Groups

You can map at the group level to automatically include all projects within a group:

gitlab.com/mycompany/*  → Tapioca Organization: "My Company"
  ├── gitlab.com/mycompany/frontend → Tapioca Project: "Web App"
  ├── gitlab.com/mycompany/backend  → Tapioca Project: "API"
  └── gitlab.com/mycompany/mobile   → Tapioca Project: "Mobile"

Commit Linking

Tapioca automatically links commits to tasks when task IDs are included in commit messages.

Supported Patterns

GitLab Issue References

Tapioca also recognizes GitLab’s native issue reference patterns:

# Standard GitLab reference (links to GitLab issue AND Tapioca if mapped)
git commit -m "Fixes #123"

# Cross-project reference
git commit -m "Fixes mygroup/myproject#123"

# Tapioca-style reference
git commit -m "Fixes TAP-123"

Merge Request Integration

MR to Task Linking

MRs are linked to tasks using the same patterns as commits. Tapioca checks:

1. MR title
2. MR description
3. Source branch name
4. Commits in the MR

Branch naming conventions:

feature/TAP-123-add-login
bugfix/TAP-456-memory-leak
123-short-description
TAP-789/new-feature

MR Keywords

GitLab’s closing keywords work with Tapioca:

Automatic Status Updates

Configure task status transitions based on MR events:

Configure these in Settings → Integrations → GitLab → Automation Rules.

Draft/WIP MRs

Draft MRs (previously WIP) are tracked but don’t trigger status updates until marked ready. This prevents premature status changes during work-in-progress.

To mark ready:

• Remove “Draft:” prefix from title
• Click “Mark as ready” in GitLab

Code Review Tracking

Tapioca creates evidence for code review activity on GitLab MRs.

Review Evidence

When someone approves an MR or leaves review comments, Tapioca records:

• Reviewer username (linked to Tapioca user if connected)
• Approval status
• Time of review
• MR information

Notes and Threads

Discussion threads on MRs are captured as evidence:

Time Tracking Sync

GitLab has built-in time tracking with /spend and /estimate commands. Tapioca can sync this bidirectionally.

GitLab → Tapioca

When enabled, time logged in GitLab syncs to Tapioca:

/spend 2h working on TAP-123

This creates a time entry in Tapioca:

• Linked to TAP-123
• Duration: 2 hours
• Source: GitLab

Tapioca → GitLab (Optional)

Time logged in Tapioca can sync back to GitLab issues:

1. Enable “Sync time to GitLab” in integration settings
2. Link Tapioca tasks to GitLab issues
3. Time entries automatically update GitLab’s time spent

Time Tracking Commands

Evidence Events

Every GitLab interaction creates an evidence event in Tapioca:

Evidence Types

Viewing Evidence

Evidence from GitLab appears in:

• Task “Evidence” tab
• User timesheets
• Activity reports
• Audit logs

User Mapping

Link GitLab users to Tapioca users for proper attribution.

Automatic Mapping

Tapioca attempts to match users by:

1. Email address (GitLab email ↔ Tapioca email)
2. Previously linked accounts

Manual Mapping

For users that can’t be auto-matched:

1. Go to Settings → Integrations → GitLab → User Mappings
2. Click “Add Mapping”
3. Enter the GitLab username
4. Select the Tapioca user
5. Save

Multiple GitLab Accounts

A single Tapioca user can be linked to multiple GitLab accounts:

• Personal GitLab.com account
• Work self-hosted GitLab account
• Multiple organizations

CI/CD Pipeline Integration

Tapioca can track CI/CD pipeline status for tasks:

Pipeline Evidence

When pipelines run, Tapioca records:

• Pipeline status (success, failed, running)
• Duration
• Triggered by (commit/MR)
• Linked task

Pipeline Status in Tasks

View pipeline status directly on tasks:

• ✅ Green = All pipelines passing
• ❌ Red = Pipeline failed
• 🟡 Yellow = Pipeline running
• ⚪ Gray = No pipeline data

Troubleshooting

Commits Not Linking

Check task ID format:

• Ensure task ID matches your project prefix (e.g., TAP-123)
• Task IDs are case-insensitive in most configurations
• Check that the project mapping exists

Verify webhook delivery:

• Check GitLab webhook logs for delivery status
• Ensure the webhook URL is correct
• Verify the secret token matches

MR Status Updates Not Working

Verify automation rules:

• Check Settings → Integrations → GitLab → Automation Rules
• Ensure the status transition is configured
• Verify the target status exists in your workflow

Check task state:

• Automation only triggers from the expected source state
• Tasks in unexpected states won’t transition

Webhooks Not Received

Check webhook configuration:

1. Verify the payload URL matches your Tapioca instance
2. Check the secret token is correct
3. Review GitLab webhook recent events

Network issues:

• Ensure GitLab can reach your Tapioca instance
• Check firewall rules for webhook traffic
• For self-hosted, verify DNS resolution

Time Sync Not Working

Check sync settings:

• Ensure “Sync time tracking” is enabled
• Verify the GitLab project is mapped to a Tapioca project
• Check that the GitLab user is mapped to a Tapioca user

Check permissions:

• The integration needs api scope for time tracking
• Verify the token has correct permissions

Self-Hosted Connection Issues

Certificate errors:

• For self-signed certs, add the CA to Tapioca’s trust store
• Check certificate expiration
• Verify the certificate matches the hostname

Network connectivity:

• Test connectivity: can Tapioca reach GitLab’s API?
• Check proxy settings if using a corporate proxy
• Verify firewall rules allow outbound HTTPS

Advanced Configuration

Environment Variables

For self-hosted Tapioca instances:

integrations:
  gitlab:
    webhook_secret: "your-secure-secret"
    default_base_url: "https://gitlab.com"  # or your self-hosted URL

Rate Limiting

Tapioca respects GitLab’s API rate limits:

• Implements exponential backoff on 429 responses
• Caches responses where appropriate
• Uses conditional requests (ETags) to reduce load

If you hit rate limits on self-hosted instances:

• Increase rate limits in GitLab configuration
• Reduce polling frequency in Tapioca settings
• Use webhooks instead of polling

Custom Fields Mapping

Map GitLab labels and milestones to Tapioca fields:

Configure in Settings → Integrations → GitLab → Field Mappings.

API Reference

Webhook Endpoint

POST /api/v1/webhooks/gitlab/{org-id}
Headers:
  X-Gitlab-Event: Merge Request Hook
  X-Gitlab-Token: {secret}

Integration Settings API

GET /api/v1/organizations/{org-id}/integrations/gitlab
PUT /api/v1/organizations/{org-id}/integrations/gitlab

See the API Documentation for full details.

Next Steps

• GitHub Integration →
• Task Linking Patterns →
• Evidence & Audit →