Task Linking Patterns

Task linking is at the heart of Tapioca’s Git integrations. By following consistent patterns in your commit messages, branch names, and PR descriptions, you enable automatic evidence collection and workflow automation.

How Task Linking Works

When Tapioca receives Git events (commits, PRs, MRs), it scans the content for task identifiers:

┌─────────────────────────────────────────────────────────┐
│  Git Event (commit, PR, MR)                             │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Extract Text (message, title, description, branch)    │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Pattern Matching (task ID regex)                       │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Task Lookup (verify task exists in project)            │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Create Link + Evidence (store association)             │
└─────────────────────────────────────────────────────────┘

Task ID Format

Default Format

Tapioca uses a standard format for task identifiers:

PREFIX-NUMBER

Where:

• PREFIX is your project key (2-10 uppercase letters)
• NUMBER is the task number (1 or more digits)

Examples:

• TAP-123
• PROJ-1
• MYPROJECT-9999

Case Sensitivity

Task IDs are case-insensitive when matching:

Commit Message Patterns

Recommended Format

We recommend the conventional commits format with task ID:

type(scope): message [TAP-123]

Examples:

git commit -m "feat(auth): add OAuth login [TAP-456]"
git commit -m "fix(api): resolve memory leak TAP-789"
git commit -m "docs: update README TAP-101"

Supported Patterns

Tapioca recognizes task IDs in various positions:

Action Keywords

Certain keywords trigger automatic task status changes:

Closing Keywords (move to “Done” on merge):

• fixes, fixed, fix
• closes, closed, close
• resolves, resolved, resolve

Reference Keywords (link only, no status change):

• refs, references, ref
• relates to, related to
• see, cf.

Examples:

# Links and closes TAP-123 when merged
git commit -m "fixes TAP-123: resolve login timeout"

# Links but doesn't change status
git commit -m "refs TAP-123: add related test coverage"

# Multiple actions
git commit -m "closes TAP-123, refs TAP-456: complete feature"

Multiple Task References

Link a single commit to multiple tasks:

# Comma-separated
git commit -m "TAP-123, TAP-456: shared component update"

# Multiple keywords
git commit -m "fixes TAP-123, refs TAP-456, closes TAP-789"

# In body
git commit -m "Update shared utilities

Fixes TAP-123
Related to TAP-456
See also TAP-789"

Branch Naming Patterns

Branch names are scanned for task IDs when PRs/MRs are created.

Recommended Formats

type/TASK-ID-description
TASK-ID/description
TASK-ID-description

Examples:

# Type prefix (recommended)
git checkout -b feature/TAP-123-add-login
git checkout -b bugfix/TAP-456-fix-memory-leak
git checkout -b hotfix/TAP-789-security-patch

# Task ID first
git checkout -b TAP-123/implement-oauth
git checkout -b TAP-456-update-docs

# Just task ID (minimal)
git checkout -b TAP-123

Branch Type Prefixes

Common prefixes and their meanings:

Branch Naming Rules

Configure custom patterns for automatic branch name generation:

Default Pattern:

{type}/{taskId}-{title}

Variables Available:

Custom Pattern Examples:

# Short format
{taskId}/{title}
→ TAP-123/add-user-login

# With username
{username}/{taskId}-{title}
→ john/TAP-123-add-user-login

# GitFlow style
{type}/{projectKey}-{taskNumber}-{title}
→ feature/TAP-123-add-user-login

Pull Request / Merge Request Patterns

Where Tapioca Looks

For PRs and MRs, Tapioca scans:

1. Title - First line of the PR
2. Description - Full PR body
3. Branch Name - Source branch
4. Commits - All commits in the PR

Title Patterns

[TAP-123] Add user authentication
TAP-123: Add user authentication
feat(TAP-123): Add user authentication

Description Templates

Create PR templates that encourage task linking:

## Related Tasks

Closes TAP-XXX

## Changes

- 

## Testing

- [ ] Unit tests
- [ ] Integration tests

Linking Multiple Tasks

A single PR can link to multiple tasks:

## Related Tasks

Closes TAP-123
Fixes TAP-456
Relates to TAP-789

## Description

This PR addresses multiple related issues...

Link Types

When a link is created, Tapioca records the link type:

Configuring Link Behavior

Customize what happens when PRs are merged:

1. Go to Settings → Integrations → Automation Rules
2. Configure status transitions:

on_pr_merged:
  link_type_fixes:
    move_to: "Done"
  link_type_refs:
    move_to: null  # No change
  link_type_manual:
    move_to: "Review"

Auto-Create Tasks

When enabled, Tapioca can create tasks from PRs that don’t reference existing tasks.

How It Works

1. PR is opened without a task reference
2. Tapioca extracts the PR title
3. New task is created in the mapped project
4. Task is linked to the PR
5. PR description is updated with the task ID

Configuration

Enable in Settings → Integrations → (GitHub/GitLab) → Auto-Create:

Evidence Collection

Every linked commit, PR, or MR creates an evidence record.

What’s Captured

Evidence vs Time Entries

Evidence and time entries are complementary:

Best Practices

For Developers

1. Always include task ID in commit messages or branch names
2. Use consistent format across the team
3. Use closing keywords only when work is complete
4. Reference related tasks with refs for partial work

For Teams

1. Document your conventions in CONTRIBUTING.md
2. Use PR templates to encourage linking
3. Set up branch protection to require task references
4. Configure automation for consistent workflows

Example Team Convention

## Git Conventions

### Branch Naming
- Format: `type/TASK-ID-short-description`
- Example: `feature/TAP-123-add-oauth`
- Types: feature, bugfix, hotfix, refactor, docs

### Commit Messages
- Format: `type: message TAP-XXX`
- Example: `feat: add login page TAP-123`
- Include task ID in every commit

### Pull Requests
- Title: `[TAP-XXX] Description`
- Include "Closes TAP-XXX" for completing tasks
- Include "Refs TAP-XXX" for partial work

Troubleshooting

Task Not Linking

Check task ID format:

• Verify the project key is correct (TAP vs TAP vs TAP)
• Ensure no extra characters (TAP-123. won’t match)
• Check that the task exists

Check project mapping:

• Verify the repository is mapped to the correct project
• Confirm the project key matches your task IDs

Wrong Task Linked

Verify task ID:

• Check for typos in the task ID
• Ensure you’re using the right project key
• Look for accidental matches in commit messages

Multiple matches:

• If multiple task IDs are found, all are linked
• Use specific patterns like fixes TAP-123 to be explicit

Keywords Not Triggering Status Change

Check the merge context:

• Keywords only trigger on PR/MR merge, not direct commits
• The PR must be merged (not closed without merging)

Check automation rules:

• Verify rules are configured in Settings → Automation
• Check that the target status exists

API Reference

Get Links for Task

GET /api/v1/tasks/{task-id}/links

Response:

{
  "links": [
    {
      "id": "uuid",
      "type": "fixes",
      "source": "github",
      "external_id": "123",
      "external_url": "https://github.com/...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Evidence for Task

GET /api/v1/tasks/{task-id}/evidence

See the API Documentation for full details.

Next Steps

• GitHub Integration →
• GitLab Integration →
• Evidence & Audit →