beads/docs/PROTECTED_BRANCHES.md
Ben Madore 3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00

653 lines
16 KiB
Markdown

# Protected Branch Workflow
This guide explains how to use beads with protected branches on platforms like GitHub, GitLab, and Bitbucket.
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Setup](#setup)
- [Daily Workflow](#daily-workflow)
- [Merging Changes](#merging-changes)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
## Overview
**Note:** This document describes a workflow that has been **removed**. Beads now stores data in Dolt under `refs/dolt/data`, separate from standard Git refs. Beads does not commit to any Git branch, so protected branch workflows are not affected.
**Previous problem:** GitHub and other platforms let you protect branches (like `main`) to require pull requests for all changes. Previously, beads committed issue data to Git branches, which conflicted with branch protection.
**Current solution:** Beads uses Dolt-native sync (`bd dolt push` / `bd dolt pull`). No Git branch commits are needed. The information below is retained for historical reference and for users migrating from older versions.
**Benefits:**
- ✅ Works with any git platform's branch protection
- ✅ Main branch stays protected
- ✅ No disruption to your primary working directory
- ✅ Backward compatible (opt-in via config)
- ✅ Minimal disk overhead (uses sparse checkout)
- ✅ Platform-agnostic solution
## Quick Start
**1. Initialize beads with a separate sync branch:**
```bash
cd your-project
bd init
```
This creates a `.beads/` directory with a Dolt database. Sync is handled via `bd dolt push` / `bd dolt pull`.
**Important:** After initialization, you'll see some untracked files that should be committed to your protected branch:
```bash
# Check what files were created
git status
# Commit the beads configuration to your protected branch
git add .beads/.gitignore .gitattributes
git commit -m "Initialize beads issue tracker"
git push origin main # Or create a PR if required
```
**Files created by `bd init`:**
Files that should be committed to your protected branch (main):
- `.beads/.gitignore` - Tells git what to ignore in .beads/ directory
- `.gitattributes` - Configures merge driver for beads data
Files that are automatically gitignored (do NOT commit):
- `.beads/dolt/` - Dolt database directory (local only)
- `.beads/dolt/sql-server.pid`, `sql-server.log` - Dolt server runtime files
The sync branch (beads-sync) will contain:
- `.beads/metadata.json` - Metadata about the beads installation
- `.beads/config.yaml` - Configuration template (optional)
**2. Start the Dolt server:**
```bash
dolt sql-server
```
With git hooks installed (`bd hooks install`), issue changes are automatically committed to the `beads-sync` branch.
**3. When ready, merge to main:**
```bash
# Check what's changed
bd dolt show
# Merge to main
git merge beads-sync
```
That's it! The complete workflow is described below.
## How It Works
### Git Worktrees
Beads uses [git worktrees](https://git-scm.com/docs/git-worktree) to maintain a lightweight checkout of your sync branch. Think of it as a mini git clone that shares the same repository history.
**Directory structure:**
```
your-project/
├── .git/ # Main git directory
│ └── beads-worktrees/
│ └── beads-sync/ # Worktree (only .beads/ checked out)
│ └── .beads/
│ └── dolt/
├── .beads/ # Your main copy
│ ├── dolt/
│ └── .gitignore
├── .gitattributes # Merge driver config (in main branch)
└── src/ # Your code (untouched)
```
**What lives in each branch:**
Main branch (protected):
- `.beads/.gitignore` - Tells git what to ignore
- `.gitattributes` - Merge driver configuration
Sync branch (beads-sync):
- `.beads/metadata.json` - Repository metadata
- `.beads/config.yaml` - Configuration template
Not tracked (gitignored):
- `.beads/dolt/` - Dolt database directory (local only)
- `.beads/dolt/sql-server.*` - Dolt server runtime files
**Key points:**
- The worktree is in `.git/beads-worktrees/` (hidden from your workspace)
- Only `.beads/` is checked out in the worktree (sparse checkout)
- Changes to issues are committed in the worktree
- Your main working directory is never affected
- Disk overhead is minimal (~few MB for the worktree)
### Automatic Sync
When you update an issue:
1. Issue is updated in the Dolt database (`.beads/dolt/`)
2. Dolt automatically commits the change to its version history
3. Changes are synced to remotes via `bd dolt push`
4. Main branch stays untouched (no commits on `main`)
## Setup
### Option 1: Initialize New Project
```bash
cd your-project
bd init
```
This will:
- Create `.beads/` directory with Dolt database
- Prompt to install git hooks (recommended: say yes)
### Option 2: Migrate Existing Project
If you already have beads set up and want to switch to a separate branch:
```bash
# Set the sync branch
bd config set sync.branch beads-sync
# Start the Dolt server and install git hooks
bd dolt start
bd hooks install
```
### Sync Configuration
For automatic commits to the sync branch, install git hooks:
```bash
bd hooks install
```
Git hooks help maintain sync consistency. Use `bd dolt push` for manual sync when needed.
### Environment Variables
You can also configure the sync branch via environment variable:
```bash
export BEADS_SYNC_BRANCH=beads-sync
```
This is useful for CI/CD or temporary overrides.
## Daily Workflow
### For AI Agents
AI agents work exactly the same way as before:
```bash
# Create issues
bd create "Implement user authentication" -t feature -p 1
# Update issues
bd update bd-a1b2 --claim
# Close issues
bd close bd-a1b2 "Completed authentication"
```
All changes are automatically committed to the `beads-sync` branch via git hooks. No changes are needed to agent workflows!
### For Humans
**Check status:**
```bash
# See what's changed on the sync branch
bd dolt show
```
This shows the current Dolt configuration and connection status.
**Manual commit:**
```bash
bd dolt commit # Commit pending changes
```
**Pull changes from remote:**
```bash
# Pull updates from other collaborators
bd dolt pull
```
This pulls changes from the remote and imports them to your local database.
## Merging Changes
### Option 1: Via Pull Request (Recommended)
For protected branches with required reviews:
```bash
# 1. Push your sync branch
git push origin beads-sync
# 2. Create PR on GitHub/GitLab/etc.
# - Base: main
# - Compare: beads-sync
# 3. After PR is merged, update your local main
git checkout main
git pull
bd dolt pull # Pull latest changes
```
### Option 2: Direct Merge (If Allowed)
If you have push access to `main`:
```bash
# Sync via Dolt (no git branch merge needed)
bd dolt push
bd dolt pull
```
**Safety checks:**
- ✅ Verifies you're not on the sync branch
- ✅ Checks for uncommitted changes in working tree
- ✅ Detects merge conflicts and provides resolution steps
- ✅ Uses `--no-ff` for clear history
### Merge Conflicts
If you encounter conflicts during merge:
```bash
# git merge may detect conflicts and show:
Auto-merging .beads/...
CONFLICT (content): Merge conflict in .beads/...
To resolve:
1. Use bd vc conflicts to view conflicts
2. Resolve conflicts
3. Commit the resolution
```
**Resolving merge conflicts:**
Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects the conflict and allows resolution:
```bash
# After a Dolt pull with conflicts
bd vc conflicts # View conflicts
bd vc resolve # Resolve conflicts
```
## Troubleshooting
### "fatal: refusing to merge unrelated histories"
This happens if you created the sync branch independently. Merge with `--allow-unrelated-histories`:
```bash
git merge beads-sync --allow-unrelated-histories --no-ff
```
Or merge manually with `git merge beads-sync --allow-unrelated-histories --no-ff`.
### "worktree already exists"
If the worktree is corrupted or in a bad state:
```bash
# Remove the worktree
rm -rf .git/beads-worktrees/beads-sync
# Prune stale worktree entries
git worktree prune
# Restart Dolt server (it will recreate the worktree)
bd dolt stop && bd dolt start
```
### "branch 'beads-sync' not found"
The sync branch doesn't exist yet. It will be created on the first commit. Create it manually:
```bash
git checkout -b beads-sync
git checkout main # Switch back
```
### "Cannot push to protected branch"
If the sync branch itself is protected:
1. **Option 1:** Unprotect the sync branch (it's metadata, doesn't need protection)
2. **Option 2:** Use `--auto-commit` without `--auto-push`, and push manually when ready
3. **Option 3:** Use a different branch name that's not protected
### Dolt server won't start
Check server status and logs:
```bash
# Check status
bd dolt status
# View logs
tail -f .beads/dolt/sql-server.log
# Restart server
bd dolt stop && bd dolt start
```
Common issues:
- Port already in use: Another Dolt server is running
- Permission denied: Check `.beads/` directory permissions
- Git errors: Ensure git is installed and repository is initialized
### Changes not syncing between clones
Ensure all clones are configured the same way:
```bash
# On each clone, verify:
bd config get sync.branch # Should be the same (e.g., beads-sync)
# Pull latest changes
bd dolt pull
# Check Dolt server is running
bd dolt status
```
## FAQ
### Do I need to configure anything on GitHub/GitLab?
No! This is a pure git solution that works on any platform. Just protect your `main` branch as usual.
### Can I use a different branch name?
Yes! Use any branch name except `main` or `master` (git worktrees cannot checkout the same branch in multiple locations):
```bash
bd dolt remote add origin <remote-url>
bd dolt push
```
### Can I change the branch name later?
Yes:
```bash
bd config set sync.branch new-branch-name
bd dolt stop && bd dolt start
```
The old worktree will remain (no harm), and a new worktree will be created for the new branch.
### What if I want to go back to committing to main?
Unset the sync branch config:
```bash
bd config set sync.branch ""
bd dolt stop && bd dolt start
```
Beads will go back to committing directly to your current branch.
### Does this work with multiple collaborators?
Yes! Each collaborator configures their own sync branch:
```bash
# All collaborators use the same branch
bd config set sync.branch beads-sync
```
Everyone's changes sync via the `beads-sync` branch. Periodically merge to `main` via PR.
### How often should I merge to main?
This depends on your workflow:
- **Daily:** If you want issue history in `main` frequently
- **Per sprint:** If you batch metadata updates
- **As needed:** Only when you need others to see issue updates
There's no "right" answer - choose what fits your team.
### Can I review changes before merging?
Yes! Use `bd dolt show` to check current status, or use git to compare branches:
```bash
git log main..beads-sync --oneline
# Shows commits on beads-sync not yet in main
```
Or create a pull request and review on GitHub/GitLab.
### What about disk space?
Worktrees are very lightweight:
- Sparse checkout means only `.beads/` is checked out
- Typically < 1 MB for the worktree
- Shared git history (no duplication)
### Can I delete the worktree?
Yes, but it may be recreated on next sync. If you want to clean up permanently:
```bash
# Stop Dolt server
bd dolt stop
# Remove worktree
git worktree remove .git/beads-worktrees/beads-sync
# Unset sync branch
bd config set sync.branch ""
```
### Does this work with `bd dolt push`?
Yes! `bd dolt push` works normally. Related commands for the merge workflow:
- `bd dolt show` - Show current Dolt configuration and connection status
- `git merge beads-sync` - Merge sync branch to main
### Can AI agents merge automatically?
Not recommended! Merging to `main` is a deliberate action that should be human-reviewed, especially with protected branches. Agents should create issues and update them; humans should merge to `main`.
However, if you want fully automated sync:
```bash
# WARNING: This bypasses branch protection!
git merge beads-sync # Run periodically (e.g., via cron)
```
### What if I forget to merge for a long time?
No problem! The sync branch accumulates all changes. When you eventually merge:
```bash
git checkout main
git merge beads-sync --no-ff
git push
```
All accumulated changes will be merged at once. Git history will show the full timeline.
### Can I use this with GitHub Actions or CI/CD?
Yes! Example GitHub Actions workflow:
```yaml
name: Sync Beads Metadata
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight
workflow_dispatch: # Manual trigger
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Full history
- name: Install bd
run: |
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
- name: Pull changes
run: |
git fetch origin beads-sync
bd dolt pull
- name: Merge to main (if changes)
run: |
if git log main..beads-sync --oneline | grep -q '.'; then
git merge beads-sync --no-ff -m "Merge beads-sync metadata"
git push origin main
fi
```
**Note:** Make sure the GitHub Action has write permissions to push to `main`.
## Platform-Specific Notes
### GitHub
Protected branch settings:
1. Go to Settings → Branches → Add rule
2. Branch name pattern: `main`
3. Check "Require pull request before merging"
4. Save
Create sync branch PR:
```bash
git push origin beads-sync
gh pr create --base main --head beads-sync --title "Update beads metadata"
```
### GitLab
Protected branch settings:
1. Settings → Repository → Protected Branches
2. Branch: `main`
3. Allowed to merge: Maintainers
4. Allowed to push: No one
Create sync branch MR:
```bash
git push origin beads-sync
glab mr create --source-branch beads-sync --target-branch main
```
### Bitbucket
Protected branch settings:
1. Repository settings → Branch permissions
2. Branch: `main`
3. Check "Prevent direct pushes"
Create sync branch PR:
```bash
git push origin beads-sync
# Create PR via Bitbucket web UI
```
## Advanced Topics
### Multiple Sync Branches
You can use different sync branches for different purposes:
```bash
# Development branch
bd config set sync.branch beads-dev
# Production branch
bd config set sync.branch beads-prod
```
Switch between them as needed.
### Syncing with Upstream
If you're working on a fork:
```bash
# Add upstream
git remote add upstream https://github.com/original/repo.git
# Fetch upstream changes
git fetch upstream
# Merge upstream beads-sync to yours
git checkout beads-sync
git merge upstream/beads-sync
bd dolt pull # Pull merged changes
```
### Custom Worktree Location
By default, worktrees are in `.git/beads-worktrees/`. This is hidden and automatic. If you need a custom location, you'll need to manage worktrees manually (not recommended).
## Migration Guide
### From Direct Commits to Sync Branch
If you have an existing beads setup committing to `main`:
1. **Set sync branch:**
```bash
bd config set sync.branch beads-sync
```
2. **Restart Dolt server:**
```bash
bd dolt stop && bd dolt start
```
3. **Verify:**
```bash
bd config get sync.branch # Should show: beads-sync
```
Future commits will go to `beads-sync`. Historical commits on `main` are preserved.
### From Sync Branch to Direct Commits
If you want to stop using a sync branch:
1. **Unset sync branch:**
```bash
bd config set sync.branch ""
```
2. **Restart Dolt server:**
```bash
bd dolt stop && bd dolt start
```
Future commits will go to your current branch (e.g., `main`).
---
**Need help?** Open an issue at https://github.com/gastownhall/beads/issues