GitHub Integration

The GitHub integration connects your repositories to Tapioca, enabling automatic time tracking evidence from commits, pull requests, and code reviews.

Overview

When connected, Tapioca receives webhook events from GitHub and:

1. Creates Evidence - Records commits, PRs, 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. Tracks Reviews - Records code review activity for reviewers

Prerequisites

Before setting up the GitHub integration, ensure you have:

• Admin access to your GitHub organization (or personal account)
• Admin access to your Tapioca organization
• A Tapioca project to link repositories to

Installation Methods

Tapioca supports two methods for GitHub integration:

Method 1: GitHub App (Recommended)

The GitHub App is the recommended approach as it provides:

• Fine-grained permissions
• Automatic webhook configuration
• Better security with short-lived tokens
• Easy installation across multiple repositories

Required Permissions:

Method 2: Personal Access Token (PAT)

Use a PAT if you cannot install apps or need simpler setup for personal repositories.

Webhook Configuration

If using a PAT, you must manually configure webhooks for each repository.

Adding a Webhook

1. Go to your GitHub repository → Settings → Webhooks
2. Click “Add webhook”
3. Configure the webhook:

4. Select events to trigger the webhook:

   • Pull requests
   • Pull request reviews
   • Pull request review comments
   • Issue comments
   • Pushes

5. Click “Add webhook”

Verifying Webhook Delivery

After adding a webhook:

1. Go to the webhook settings in GitHub
2. Click “Recent Deliveries”
3. Look for successful (green) deliveries
4. Check for any errors in failed deliveries

Repository Mapping

Link GitHub repositories to Tapioca projects for automatic task association.

Setting Up Mappings

1. Go to Tapioca Settings → Integrations → GitHub → Repository Mappings
2. Click “Add Mapping”
3. Select the GitHub repository
4. Choose the Tapioca project
5. Configure automation options:

Multiple Mappings

You can map multiple repositories to a single project, or use different projects for different repositories within the same organization.

github.com/mycompany/frontend → Tapioca Project: "Web App"
github.com/mycompany/backend  → Tapioca Project: "API"
github.com/mycompany/infra    → Tapioca Project: "Infrastructure"

Commit Linking

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

Supported Patterns

Keywords for Actions

Certain keywords trigger automatic task status changes:

Examples:

# Links to task, no status change
git commit -m "refs TAP-123: Add unit tests"

# Links to task and moves to Done on merge
git commit -m "fixes TAP-123: Resolve memory leak"

Pull Request Integration

PR to Task Linking

PRs are linked to tasks using the same patterns as commits, but Tapioca also checks:

1. PR title
2. PR description
3. Branch name
4. Commits in the PR

Branch naming conventions:

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

Automatic Status Updates

Configure task status transitions based on PR events:

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

Draft PRs

Draft PRs are tracked but don’t trigger “PR Opened” status changes until marked ready for review. This prevents premature status updates while work is still in progress.

Code Review Tracking

Tapioca creates evidence for code review activity:

Review Evidence

When someone submits a PR review, Tapioca records:

• Reviewer username (linked to Tapioca user if connected)
• Review type (approved, changes requested, commented)
• Time of review
• PR information

This allows tracking time spent on code reviews even when reviewers aren’t explicitly logging time.

Review Comments

PR comments and review comments are also captured as evidence, enabling:

• Tracking discussion/collaboration time
• Linking code review feedback to tasks
• Auditing code review activity

Evidence Events

Every GitHub interaction creates an evidence event in Tapioca:

Evidence Types

Viewing Evidence

1. Go to any task in Tapioca
2. Click the “Evidence” tab
3. View all linked GitHub activity with timestamps

Evidence can also be viewed:

• On user timesheets (shows evidence alongside time entries)
• In reports (filter by evidence source)
• Via API (for custom integrations)

User Mapping

Link GitHub users to Tapioca users for proper attribution:

Automatic Mapping

Tapioca attempts to match users by:

1. Email address (if GitHub email matches Tapioca email)
2. Previously linked accounts

Manual Mapping

For users that can’t be auto-matched:

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

Troubleshooting

Commits Not Linking

Check task ID format:

• Ensure task ID matches your project prefix (e.g., TAP-123)
• Task ID must be uppercase
• Include separator (e.g., TAP-123: not TAP123)

Check repository mapping:

• Verify the repository is mapped to the correct project
• Confirm auto-linking is enabled

Webhooks Not Received

Verify webhook configuration:

1. Check the payload URL matches your Tapioca instance
2. Verify the secret token is correct
3. Check GitHub webhook delivery history for errors

Check Tapioca logs:

• Look for webhook errors in Settings → System → Logs
• Common issues: signature mismatch, invalid JSON, missing org

PR Status Updates Not Working

Verify automation rules:

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

Check task state:

• Automation only works if the task is in the expected source state
• Tasks in unexpected states won’t transition

GitHub App Installation Failed

Common causes:

• Insufficient permissions on GitHub organization
• Browser blocking popup windows
• OAuth flow interrupted

Solutions:

• Ensure you’re an admin of the GitHub organization
• Disable popup blockers temporarily
• Try a different browser
• Check browser developer console for errors

Advanced Configuration

Environment Variables

For self-hosted Tapioca instances:

integrations:
  github:
    webhook_secret: "your-secure-secret"
    app_id: "12345"
    app_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
    default_base_url: "https://api.github.com"  # or GitHub Enterprise URL

GitHub Enterprise

For GitHub Enterprise Server:

1. Use the same installation methods above
2. Configure the base URL in Tapioca settings
3. Ensure network connectivity between Tapioca and your GHE instance
4. For self-signed certificates, configure trusted CAs

Rate Limiting

Tapioca respects GitHub’s API rate limits:

• Uses authenticated requests (5,000/hour)
• Implements exponential backoff
• Caches responses where appropriate

If you hit rate limits, consider:

• Using GitHub App auth (higher limits)
• Reducing polling frequency
• Enabling only needed webhook events

API Reference

Webhook Endpoint

POST /api/v1/webhooks/github/{org-id}
Headers:
  X-GitHub-Event: pull_request
  X-Hub-Signature-256: sha256=...
  X-GitHub-Delivery: {uuid}

Integration Settings API

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

See the API Documentation for full details.

Next Steps

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