Wiki Integration

Wiki Integration

git-adr can synchronize your Architecture Decision Records to GitHub or GitLab wikis, making decisions accessible to team members who prefer browsing documentation over command-line tools.

---

Installation

Install git-adr with wiki support:

pip install "git-adr[wiki]"

# Or with all features
pip install "git-adr[all]"

---

Quick Start

Initialize Wiki Sync

# Auto-detect platform from remote URL
git adr wiki init

# Or specify explicitly
git adr wiki init --provider github --repo owner/repo

Sync ADRs to Wiki

git adr wiki sync

This creates or updates wiki pages for all your ADRs.

---

Supported Platforms

Platform	Wiki Type	Features
GitHub	GitHub Wiki	Full support, auto-detect
GitLab	GitLab Wiki	Full support, auto-detect

---

Configuration

adr.wiki.platform

Set the wiki platform:

# Auto-detect from remote URL (default)
git adr config set adr.wiki.platform auto

# Explicitly set GitHub
git adr config set adr.wiki.platform github

# Explicitly set GitLab
git adr config set adr.wiki.platform gitlab

adr.wiki.auto_sync

Automatically sync to wiki after ADR changes:

# Enable auto-sync
git adr config set adr.wiki.auto_sync true

# Disable (default)
git adr config set adr.wiki.auto_sync false

When enabled, wiki sync runs automatically after:

• git adr new
• git adr edit
• git adr supersede
• git adr rm

---

Wiki Commands

git adr wiki init

Initialize wiki synchronization for the repository.

git adr wiki init [options]

Options:

Option	Description
--provider <platform>	Wiki platform (github, gitlab, auto)
--repo <owner/repo>	Repository identifier

What it does:

1. Detects or sets the wiki platform
2. Configures wiki repository settings
3. Clones the wiki repository if needed
4. Creates initial wiki structure

Examples:

# Auto-detect from origin remote
git adr wiki init

# Explicit GitHub setup
git adr wiki init --provider github --repo myorg/myproject

# GitLab setup
git adr wiki init --provider gitlab --repo mygroup/myproject

---

git adr wiki sync

Synchronize ADRs to the wiki.

git adr wiki sync [options]

Options:

Option	Description
--push	Push changes to remote wiki
--status <status>	Only sync ADRs with specific status
--dry-run	Show what would be synced without making changes

What it does:

1. Exports all ADRs to wiki-formatted markdown
2. Creates/updates wiki pages
3. Updates navigation (sidebar, index)
4. Optionally pushes to remote wiki

Examples:

# Sync all ADRs
git adr wiki sync

# Sync and push
git adr wiki sync --push

# Only sync accepted ADRs
git adr wiki sync --status accepted

# Preview changes
git adr wiki sync --dry-run

---

Wiki Structure

When synced, your wiki will have this structure:

Home.md                     # Main landing page with overview
_Sidebar.md                 # Navigation sidebar
Getting-Started.md          # Quick start guide
Commands-Reference.md       # Command documentation
Configuration-Guide.md      # Configuration options
ADR-Templates.md            # Template formats
Architecture-Decisions.md   # Index of all ADRs

# Individual ADR pages
ADR-<id>-<title>.md
ADR-00000000-use-adrs-Use-Architecture-Decision-Records.md
ADR-20250115-use-postgresql-Use-PostgreSQL-for-primary-database.md
...

---

GitHub Wiki Setup

Prerequisites

1. Wiki must be enabled for your repository
2. You need write access to the wiki
3. SSH or HTTPS authentication configured

Enable Wiki

In your GitHub repository:

1. Go to Settings
2. Scroll to Features
3. Check "Wikis"

Clone Wiki Manually (Optional)

git clone https://github.com/owner/repo.wiki.git

Or with SSH:

git clone git@github.com:owner/repo.wiki.git

First Sync

cd your-project
git adr wiki init --provider github
git adr wiki sync --push

---

GitLab Wiki Setup

Prerequisites

1. Wiki must be enabled for your project
2. You need write access to the wiki
3. SSH or HTTPS authentication configured

Enable Wiki

In your GitLab project:

1. Go to Settings > General
2. Expand "Visibility, project features, permissions"
3. Enable "Wiki"

Clone Wiki Manually (Optional)

git clone https://gitlab.com/group/project.wiki.git

Or with SSH:

git clone git@gitlab.com:group/project.wiki.git

First Sync

cd your-project
git adr wiki init --provider gitlab
git adr wiki sync --push

---

Customizing Wiki Output

Page Naming

Wiki page names are derived from ADR IDs and titles:

ADR-{id}-{sanitized-title}.md

Titles are sanitized to be wiki-friendly:

• Spaces replaced with hyphens
• Special characters removed
• Truncated if too long

Sidebar Generation

The sidebar (_Sidebar.md) is automatically generated with:

• Link to Home
• Links to documentation pages
• Grouped ADR links by status
• Recently modified ADRs highlighted

Index Page

The Architecture Decisions index page includes:

• Summary statistics
• ADR list grouped by status
• Quick links to important decisions
• Search guidance

---

Best Practices

When to Sync

Recommended sync points:

1. After finalizing a new ADR
2. When accepting/rejecting a proposal
3. Before team meetings or reviews
4. On release milestones

Consider NOT syncing:

• Draft/proposed ADRs (if you want them private)
• Immediately after every small edit

Wiki vs Git Notes

Use Wiki For	Use Git Notes For
Team browsing	Source of truth
Sharing with stakeholders	Developers
Search engine indexing	Git integration
Non-technical readers	Commit linking

Remember: git notes are the source of truth. The wiki is a derived view for accessibility.

Permissions

Wiki permissions typically follow repository permissions. Consider:

• Public repos: Wiki is public
• Private repos: Wiki is private
• Separate wiki access: Not usually supported

---

Troubleshooting

"Wiki not found"

# Check wiki is enabled in repository settings
# Then re-initialize
git adr wiki init --provider github

"Permission denied"

# Check your git credentials
git credential reject

# Re-authenticate
git clone https://github.com/owner/repo.wiki.git
# Enter credentials when prompted

"Push failed"

# Pull latest changes first
cd path/to/wiki
git pull origin master

# Then sync again
cd path/to/project
git adr wiki sync --push

"Platform auto-detection failed"

# Check remote URL
git remote -v

# Set platform explicitly
git adr config set adr.wiki.platform github

Wiki Out of Sync

If the wiki has manual changes that conflict:

# Option 1: Force overwrite (loses manual changes)
git adr wiki sync --force --push

# Option 2: Manual merge
cd path/to/wiki
git pull origin master
# Resolve conflicts
git push origin master

---

Integration Workflows

CI/CD Wiki Sync

Automatically sync wiki on merge to main:

# .github/workflows/wiki-sync.yml
name: Wiki Sync
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install "git-adr[wiki]"
      - run: |
          git adr wiki init --provider github
          git adr wiki sync --status accepted --push
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pre-release Checklist

# Before release, ensure wiki is current
git adr wiki sync --dry-run        # Preview changes
git adr wiki sync --push           # Apply changes

---

See Also

• Configuration Guide#wiki-settings - Wiki configuration options
• Commands Reference - Full command documentation
• GitHub Wiki Documentation
• GitLab Wiki Documentation