Syncing Documents to GitHub

Once GitHub is connected and a repository is selected, you can sync documents to keep them in version control.

Prerequisites

• ✅ GitHub connected
• ✅ Repository selected
• ✅ Document ready to sync

How to Sync a Document

Step 1: Open the Document

1. Navigate to Dashboard > Documents
2. Open the document you want to sync
3. Ensure it's saved and ready

Step 2: Initiate Sync

1. Look for the GitHub section or button
2. Click Sync to GitHub or the GitHub icon
3. The sync process starts

Step 3: Confirmation

Once synced:

• A success message appears
• The sync status updates
• A link to the file in GitHub may be shown

What Gets Synced

Document Content

Your document is converted to a Markdown file:

---
title: Use PostgreSQL for Database
type: ADR
category: ACCEPTED
author: John Doe
created: 2026-02-15
updated: 2026-02-17
---

# Use PostgreSQL for Database

## Context
...

## Decision
...

## Consequences
...

Metadata (Frontmatter)

File Location

Documents are synced to paths based on type:

Sync Behavior

First Sync

• Creates the file in the repository
• Creates directories if needed
• Commits with a descriptive message

Subsequent Syncs

• Updates the existing file
• Creates a new commit
• Shows the changes in Git history

Commit Messages

ArchDoc creates descriptive commit messages:

docs: Add ADR - Use PostgreSQL for Database

Synced from ArchDoc by john.doe@company.com

When to Sync

Manual Sync

Sync whenever you want the latest version in GitHub:

• After major edits
• When document is finalized
• Before important milestones

Recommended Workflow

1. Draft in ArchDoc (frequent saves)
2. Review with sign-offs
3. Sync when accepted
4. Update and re-sync as needed

Viewing Synced Documents

In GitHub

After syncing, find your document:

1. Go to your GitHub repository
2. Navigate to the docs/ directory
3. Find the file by type and slug
4. View the rendered Markdown

In ArchDoc

The document shows:

• Last sync status
• Link to GitHub file
• Sync button for updates

Linked PRs and Commits

When you sync documents, ArchDoc can track:

Linked Pull Requests

• Documents can be associated with PRs
• Shows PR status (open, merged, closed)
• Quick links to GitHub

Linked Commits

• Track which commits relate to the document
• View commit history
• Link implementation to documentation

Syncing Best Practices

Sync Accepted Documents

Focus on syncing finalized documents:

• Drafts change frequently
• Accepted documents are stable
• Reduces noise in Git history

Regular Updates

When documents change:

• Update in ArchDoc
• Sync to GitHub
• Maintains consistency

Don't Edit in Both Places

Avoid editing in both ArchDoc and GitHub:

• ArchDoc is the source of truth
• Edits in GitHub won't sync back
• Conflicts may arise

Review Before Syncing

Ensure the document is ready:

• Proofread content
• Check formatting
• Verify accuracy

Troubleshooting

Sync Failed

Common causes:

• GitHub connection expired
• Repository access revoked
• Network issues

Solutions:

• Check GitHub integration status
• Reconnect if needed
• Try again later

File Not Appearing in GitHub

Check:

• Sync completed successfully
• Looking in the correct path
• Repository is correct

Permission Denied

Causes:

• Lost write access to repo
• Repository deleted or moved
• OAuth token expired

Solutions:

• Verify repository access
• Reconnect GitHub integration
• Select a different repository

Content Not Updated

If changes aren't appearing:

• Ensure you saved in ArchDoc
• Click sync again
• Check the commit in GitHub

Sync vs. Export

Security Notes

What's Shared

Only document content and metadata go to GitHub:

• ✅ Document text
• ✅ Basic metadata
• ❌ Sign-offs (stay in ArchDoc)
• ❌ Comments (stay in ArchDoc)
• ❌ User details beyond author

Repository Privacy

Your repository's visibility controls access:

• Private repo: Only collaborators see docs
• Public repo: Anyone can see docs

Choose visibility appropriate for your documentation.