Team Collaboration

This feature is completely opt-in. If you prefer managing git yourself, these commands won't get in your way. But if you want a guided experience with built-in review processes, read on. See the workflow documentation for complete details.

What happens at each step

Tessera provides a flexible role system. You define what roles exist and which entity types they can approve. This is entirely customizable to fit your organization's needs.

Team members can have multiple roles. The approval matrix in your team file determines which roles can approve which entity types. You define these rules—Tessera just enforces them.

version: 1
members:
  - name: "Jane Smith"
    email: "jane@example.com"
    username: "jsmith"
    roles: [engineering, quality]
    active: true

  - name: "Bob Wilson"
    email: "bob@example.com"
    username: "bwilson"
    roles: [quality, management]
    active: true

# Define your own approval rules here
approval_matrix:
  REQ: [engineering, quality]    # Your choice
  RISK: [quality, management]    # Your choice
  TEST: [quality]                # Your choice
  _release: [management]         # Your choice

For regulated environments or critical systems, you can require multiple approvals before an entity transitions to "approved" status. Configure this in your .tdt/config.yaml:

workflow:
  enabled: true
  provider: github
  approvals:
    default:
      min_approvals: 1
    RISK:
      min_approvals: 2
      required_roles: [engineering, quality]
    REQ:
      min_approvals: 2

When multi-approval is configured, the tdt approve command records the approval but only transitions the status to "approved" once all requirements are met. Use tdt review pending-approvals to see which entities need more approvals:

$ tdt review pending-approvals
ID          Title                    Current  Required  Next Role Needed
REQ@1       Pump flow rate           1        2         quality
RISK@2      Motor overheating        0        2         engineering,quality

Team members can find PRs that need their role's approval, even if they weren't explicitly requested as reviewers:

# Find PRs targeting main that need your role
$ tdt review list --target main --needs-role

PRs Needing Your Role's Approval

PR     ENTITY       TYPE   TITLE              APPROVALS  MISSING
#45    RISK-02CD... RISK   Motor failure      1/2        quality

1 entities across 1 PRs (1 need more approvals).
Run `tdt approve  --pr ` to approve.

Tessera automatically creates git tags for workflow events, providing an immutable audit trail that's easy to query and filter. This supports regulatory compliance requirements like 21 CFR Part 11 and ISO 13485.

Tag Format

Querying the Audit Trail

# List all approval tags
git tag -l "approve/*"

# List approvals for a specific entity
git tag -l "approve/REQ-01ABC*"

# List all approvals by a specific user
git tag -l "approve/*/jsmith/*"

# Show tag details (includes message)
git show approve/REQ-01ABC/jsmith/2024-01-15

# Use tdt log for a formatted view
tdt log --approver jsmith

Setting Up GitHub

First, install and authenticate the GitHub CLI:

# Install GitHub CLI (macOS)
brew install gh

# Login to GitHub
gh auth login

Then configure Tessera to use GitHub:

workflow:
  enabled: true
  provider: github
  base_branch: main

Setting Up GitLab

For GitLab, use the GitLab CLI:

# Install GitLab CLI
brew install glab

# Login to GitLab
glab auth login

No Provider (Manual Mode)

If you're using a different git host, set provider to none. Tessera will create branches and commits, but you'll create pull requests yourself.

Do I have to use these workflow commands?

No! The workflow is completely opt-in. If workflow.enabled is false (the default), you can manage git manually.

What if I don't have a team roster?

Without a team roster, there are no permission checks. Anyone can approve anything. This is fine for solo projects or small teams without formal processes.

Can I still use git directly?

Absolutely. These commands are convenient wrappers. You can always use git, gh, or glab directly.

How do I see the git commands Tessera runs?

Use --verbose on any command to see each git command as it runs, or use --dry-run to preview without executing.

How do I request specific reviewers?

Use the --reviewer flag with GitHub/GitLab usernames (not emails): tdt submit REQ@1 --reviewer jsmith,bwilson

How do I see approval history?

Use tdt history REQ@1 --workflow to see a formatted timeline of workflow events, or tdt log to query activity across all entities.

What happens with multi-signature approvals?

When configured, tdt approve records each approval but keeps the entity in "review" status until all requirements are met. Use tdt review pending-approvals to see which entities need more approvals.