Git Providers

Integrations

One-way sync to GitHub, GitLab, or Bitbucket. Arbtr is the editor; Git is the archive.

The Philosophy

Git Sync is intentionally one-way. Arbtr pushes to Git; it does not pull from Git.

Why? Because Arbtr is optimized for decision-making workflows—arguments, voting, relationships, status changes. Git is optimized for storing files. Trying to round-trip between them creates complexity without value.

Arbtr

Editor

push only

Git

Integration Modes

Arbtr supports two integration modes to make it easier to get started, especially in enterprise environments with strict security requirements.

Read-OnlyRecommended to start

Perfect for getting started. Use Arbtr to analyze your codebase, search PRs, and browse repositories—all without write access.

• Arbtr code analysis
• PR/MR search
• Repository browsing
• Code search

Full Access

Everything in Read-Only, plus the ability to publish decisions as ADRs and create pull requests.

• All Read-Only features
• Publish decisions as ADRs
• Create PRs/MRs
• Auto-publish on conclusion

For enterprise teams: Start with Read-Only access—it's easier to get security approval. When you're ready to publish decisions, upgrade to Full Access. You can switch modes anytime in your team's Integrations settings.

Setup Guides

Choose your Git provider to get started. You can configure multiple providers and set one as the default for publishing.

GitHub

Connect via GitHub App for secure, scoped repository access.

GitLab

Connect via OAuth. Supports GitLab.com and self-hosted instances.

Bitbucket

Connect via OAuth. Bitbucket Cloud only (Data Center not supported).

What Gets Published

Included

• Concluded decisions (Approved/Rejected/Deferred)
• Decision title and context
• All positions and arguments
• Conclusion rationale
• Tags and domains
• Relationship references

Not Included

• Draft decisions
• Active/Under Discussion decisions
• Comments (only arguments)
• Vote details (just outcome)
• Audit history
• User attributions (optional)

Only concluded decisions sync by default. This keeps your Git repo clean—no half-finished discussions cluttering your docs.

File Structure

Arbtr creates ADR files using a numbered format in your configured directory:

docs/adr/
├── 0001-use-postgresql.md
├── 0002-adopt-typescript.md
├── 0003-frontend-framework.md
├── 0004-api-versioning-strategy.md
└── ...

Filename format:Zero-padded number + slugified title (e.g., "Use PostgreSQL" → 0001-use-postgresql.md)

Numbering:Arbtr automatically assigns the next available ADR number based on existing files

Auto-Publish on Conclusion

Enable automatic publishing so decisions are synced to Git the moment they're concluded. No manual "Publish to Git" step needed.

How to Enable

Go to Team Settings → Integrations
Configure at least one Git provider with Full Access mode
Toggle "Auto-publish on conclusion" (above the provider tabs)

How It Works

• Conclude a decision (Approved/Rejected/Deferred)
• Review and approve the AI-generated summary
• After saving, the decision is automatically published
• Uses your team's default Git provider
• The published ADR includes the comprehensive summary

Auto-publish is disabled by default. Team owners can enable it in Integrations settings. If you have multiple providers configured, auto-publish uses whichever is set as default.

How Publishing Works

Pull/Merge Requests

Each publish creates a PR (GitHub/Bitbucket) or MR (GitLab) for review. The PR contains a single commit with your ADR file. Review and merge to add the decision to your main branch.

New Decisions

Creates a new ADR file with the next available number. Commit message: docs: Record ADR - [title]

Updated Decisions

If you edit a published decision and republish, the existing file is updated. Commit message: docs: Update ADR - [title]

Archived Decisions

Archived decisions are NOT deleted from Git. Git history is preserved. To remove an ADR, delete the file manually in your repository.

Don't edit synced files in Git

Changes made directly in Git will be overwritten on the next publish. All edits should happen in Arbtr.

PR/MR Details

# Branch name
arbtr/adr-0012-use-postgresql

# PR/MR title
docs: Record ADR - Use PostgreSQL for primary database

# Commit message (same as PR title)
docs: Record ADR - Use PostgreSQL for primary database

Each decision creates its own PR/MR. The branch is automatically created and the PR is opened against your configured target branch.

Security

Token Security

• Encryption at Rest: OAuth tokens for GitLab and Bitbucket are encrypted using AES-256-GCM before storage
• Automatic Refresh: Tokens are automatically refreshed before expiry—no manual reconnection needed
• GitHub App: Uses installation tokens that are generated per-request, never stored long-term

Access Control

Only team owners can configure Git integrations. Team members can publish decisions but cannot view or modify connection settings.

OAuth Best Practices

Arbtr requests only the minimum required scopes for each provider. OAuth state parameters prevent CSRF attacks during authorization.

Troubleshooting

403 Forbidden

GitHub: The GitHub App doesn't have access to this repository. Reinstall the app or add the repository to the installation.
GitLab/Bitbucket: If tokens failed to auto-refresh, disconnect and reconnect to get a new authorization.

404 Not Found

Repository doesn't exist or you don't have access. Verify the repository owner/name (GitHub), project ID (GitLab), or workspace/slug (Bitbucket).

Branch doesn't exist

The configured target branch must exist in your repository. Create it first, or change to an existing branch like main.

Status tracking

Each decision shows its publish status (Synced, Out of Sync, Error) in the decision details. Click the status badge to view the PR/MR.