Evidence & Audit Trail

Evidence is the foundation of Tapioca’s verification and compliance capabilities. Every commit, pull request, code review, and other Git activity is captured as an evidence event, creating a comprehensive audit trail of work.

What is Evidence?

Evidence events are immutable records of work activity captured from external systems:

• Commits pushed to repositories
• Pull requests opened, merged, or closed
• Code reviews submitted
• Comments on PRs and issues
• CI/CD pipelines executed

Unlike time entries (which are user-reported), evidence is automatically collected and provides objective proof of work.

Why Evidence Matters

For Individuals

• Forgotten time - Evidence shows work you forgot to log
• Verification - Prove what you worked on and when
• Time reconstruction - Rebuild timesheets from Git history

For Teams

• Accountability - Verify work was done as claimed
• Transparency - Clear record of who did what
• Estimation - Compare estimates with actual work evidence

For Organizations

• Compliance - Meet regulatory requirements for work documentation
• Audit trail - Immutable record for financial audits
• Billing verification - Support invoices with evidence

Evidence Sources

GitHub Events

GitLab Events

Calendar Events

Evidence Event Structure

Each evidence event contains:

{
  "id": "uuid",
  "organizationId": "uuid",
  "userId": "uuid",
  "source": "github_pr",
  "externalId": "123",
  "externalUrl": "https://github.com/org/repo/pull/123",
  "eventTime": "2024-01-15T10:30:00Z",
  "title": "Add user authentication",
  "description": "Implements OAuth login flow",
  "detectedTaskKey": "TAP-456",
  "linkedTaskId": "uuid",
  "linkedProjectId": "uuid",
  "linkConfidence": 0.95,
  "manuallyLinked": false,
  "rawPayload": { /* original webhook data */ },
  "createdAt": "2024-01-15T10:30:05Z"
}

Key Fields

Automatic Task Linking

Evidence is automatically linked to tasks when:

1. Task ID detected - Found in commit message, PR title, branch name
2. Task exists - The detected task ID is valid
3. Project mapped - The repository is linked to the correct project

Link Confidence

Tapioca assigns a confidence score to automatic links:

Manual Linking

Link evidence to tasks manually when automatic linking fails:

1. Go to the Evidence view (Timeline → Evidence)
2. Find the unlinked evidence event
3. Click “Link to Task”
4. Search for and select the correct task
5. Click “Link”

Or from a task:

1. Open the task
2. Go to the Evidence tab
3. Click “Add Evidence”
4. Search for unlinked evidence events
5. Select and link

Viewing Evidence

Task Evidence Tab

Every task has an Evidence tab showing all linked evidence:

┌─────────────────────────────────────────────────────────────┐
│  Evidence for TAP-123: Implement OAuth Login               │
├─────────────────────────────────────────────────────────────┤
│  🔀 PR #456 opened                     Jan 15, 10:30 AM    │
│     "Add OAuth login flow"                                  │
│     → github.com/org/repo/pull/456                         │
│                                                             │
│  📝 Commit abc123                      Jan 15, 9:45 AM     │
│     "WIP: Start OAuth implementation"                       │
│     → github.com/org/repo/commit/abc123                    │
│                                                             │
│  ✅ PR #456 approved by @reviewer      Jan 15, 2:15 PM     │
│     "LGTM, good use of the OAuth library"                  │
│                                                             │
│  🔀 PR #456 merged                     Jan 15, 3:00 PM     │
│     → Closed TAP-123                                        │
└─────────────────────────────────────────────────────────────┘

User Timeline

View all evidence for a user over time:

1. Go to Timeline (or press G then T)
2. Select the time range
3. Toggle “Show Evidence” on

Evidence appears alongside time entries:

January 15, 2024

09:00 ─────────────────────────────────────────────
       │ 📝 Commit: "Start OAuth implementation"
       │ ⏱️  Time Entry: 2h on TAP-123
10:30 ─────────────────────────────────────────────
       │ 🔀 PR #456 opened
11:00 ─────────────────────────────────────────────
       │ ⏱️  Time Entry: 1.5h on TAP-123
       │ 💬 Comment on PR #456
14:00 ─────────────────────────────────────────────
       │ ✅ PR #456 approved
15:00 ─────────────────────────────────────────────
       │ 🔀 PR #456 merged

Organization Evidence Report

Administrators can view organization-wide evidence:

1. Go to Reports → Evidence Report
2. Filter by date range, user, project
3. Export as CSV/PDF for audits

Evidence vs Time Entries

Evidence and time entries serve complementary purposes:

Using Evidence to Verify Time

Compare evidence with time entries to:

1. Find gaps - Evidence without corresponding time entries
2. Verify claims - Time entries backed by evidence
3. Reconstruct - Build timesheets from evidence when entries were forgotten

Evidence-Based Time Suggestions

Tapioca can suggest time entries based on evidence:

How Suggestions Work

1. Tapioca analyzes your evidence events
2. Clusters related events (same task, close in time)
3. Suggests time entries for periods with evidence but no logged time

Enabling Suggestions

1. Go to Settings → Time Tracking
2. Enable “Evidence-based suggestions”
3. Configure suggestion sensitivity

Reviewing Suggestions

Suggestions appear in your Daily Review:

┌─────────────────────────────────────────────────────────────┐
│  📊 Suggested Time Entries                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Based on your Git activity on January 15:                 │
│                                                             │
│  TAP-123: Implement OAuth Login                            │
│  Commits: 3 | PR opened and merged | Reviews: 2            │
│  Suggested: 4-5 hours                                       │
│                                                             │
│  [Accept 4h]  [Adjust]  [Dismiss]                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Audit Trail

Evidence creates an immutable audit trail for compliance:

What’s Logged

• Evidence event creation
• Manual link changes
• Link confirmations/rejections
• Evidence exports/views

Audit Log Access

1. Go to Settings → Security → Audit Log
2. Filter by event type: “evidence”
3. View who accessed/modified evidence records

Compliance Features

Privacy & Data

What Data is Stored

Evidence includes data from the source system:

• Commit messages and SHAs
• PR/MR titles and descriptions
• Usernames and email addresses
• Code comments
• File paths (in commit data)

What Data is NOT Stored

• File contents
• Actual code changes
• Secrets or credentials
• Private repository URLs (for public evidence)

Data Retention

Configure how long evidence is retained:

1. Go to Settings → Privacy → Data Retention
2. Set retention period for evidence (default: forever)
3. Configure automatic anonymization

User Data Access

Users can export or delete their evidence:

1. Go to Settings → Privacy → My Data
2. Click “Export Evidence” for a JSON export
3. Click “Delete My Data” for GDPR deletion

Integration with Reports

Evidence in Time Reports

Include evidence summary in time reports:

Time Report: January 2024
─────────────────────────────────────────────
Total Hours: 160
Verified by Evidence: 142h (89%)
  - Commits: 127
  - PRs/MRs: 23
  - Reviews: 45

Evidence Metrics

Track evidence-based metrics:

API Reference

List Evidence

GET /api/v1/organizations/{org-id}/evidence
Query Parameters:
  - userId: Filter by user
  - taskId: Filter by task
  - source: Filter by source (github_pr, gitlab_mr, etc.)
  - from: Start date (ISO 8601)
  - to: End date (ISO 8601)

Get Evidence Event

GET /api/v1/organizations/{org-id}/evidence/{evidence-id}

Link Evidence to Task

POST /api/v1/organizations/{org-id}/evidence/{evidence-id}/link
Body:
{
  "taskId": "uuid"
}

Unlink Evidence

DELETE /api/v1/organizations/{org-id}/evidence/{evidence-id}/link

See the API Documentation for full details.

Best Practices

For Developers

1. Consistent linking - Always include task IDs in commits/PRs
2. Review weekly - Check for unlinked evidence
3. Use keywords - fixes, refs improve auto-linking

For Managers

1. Review coverage - Ensure team has good evidence coverage
2. Set expectations - Document linking requirements
3. Use reports - Leverage evidence in reviews and billing

For Compliance

1. Enable retention - Set appropriate retention periods
2. Regular exports - Archive evidence for audits
3. Access controls - Limit who can view evidence reports

Troubleshooting

Evidence Not Appearing

Check webhook delivery:

• Verify webhooks are configured correctly
• Check GitHub/GitLab webhook logs for errors
• Ensure Tapioca can receive webhooks (firewall, etc.)

Check user mapping:

• Git user must be mapped to Tapioca user
• Verify email addresses match
• Check Settings → Integrations → User Mappings

Evidence Not Linking

Check task ID format:

• Verify task ID is correct
• Ensure project is mapped
• Check for typos in commit/PR

Check project mapping:

• Repository must be mapped to a project
• Task must exist in that project

Old Evidence Missing

Check retention policy:

• Evidence may have been deleted per retention policy
• Check Settings → Privacy → Data Retention

Check sync history:

• Integration may not have been connected
• Historical sync is limited

Next Steps

• GitHub Integration →
• GitLab Integration →
• Task Linking Patterns →