Selecting Repository

After connecting GitHub, choose which repository will store your synced documents.

Prerequisites

• ✅ GitHub account connected
• ✅ Admin role in ArchDoc
• ✅ Access to the repository you want to use

How to Select a Repository

Step 1: Access Integrations

1. Navigate to Dashboard > Integrations
2. Find the GitHub section
3. Confirm your account is connected

Step 2: View Available Repositories

1. Click Select Repository or the repository dropdown
2. A list of your repositories appears
3. Both personal and organization repos are shown (if accessible)

Step 3: Choose a Repository

1. Browse or search the list
2. Click on the repository you want
3. The selection is saved automatically

Step 4: Confirm Selection

After selecting:

• The repository name is displayed
• You can now sync documents to this repo

Repository Requirements

Access Level

You need write access to the repository:

• Owner: ✅
• Admin: ✅
• Write: ✅
• Read only: ❌

Visibility

Both public and private repositories work:

Choosing the Right Repository

Dedicated Documentation Repo

Create a repository specifically for documentation:

Pros:

• Clean separation from code
• Focused access control
• Dedicated documentation tooling

Example structure:

docs-repo/
├── adrs/
│   ├── 001-use-postgresql.md
│   └── 002-api-versioning.md
├── rfcs/
│   └── 001-notification-system.md
└── design-docs/
    └── payment-architecture.md

Alongside Code

Use your main project repository:

Pros:

• Docs versioned with code
• Single repository to manage
• Developers find docs easily

Example structure:

project-repo/
├── src/
├── tests/
└── docs/
    ├── adrs/
    ├── rfcs/
    └── design-docs/

Monorepo

For monorepos, you can organize by service:

monorepo/
├── services/
│   └── user-service/
│       └── docs/
├── packages/
└── docs/           # Shared documentation
    ├── adrs/
    └── rfcs/

Changing Repositories

You can switch repositories at any time:

1. Go to Dashboard > Integrations
2. Click on the current repository name
3. Select a different repository

Repository Considerations

Branch Strategy

• Documents sync to the default branch
• Consider branch protection rules
• You might want a separate branch for docs

File Organization

Documents are synced with paths like:

docs/adr/document-slug.md
docs/rfc/document-slug.md
docs/design-doc/document-slug.md

Existing Documentation

If the repo already has docs:

• ArchDoc syncs to its own paths
• Existing files aren't affected
• Consider consolidating over time

Organization Repositories

Access Requirements

For organization repos, you need:

• Write permission in the repo
• OAuth app approval (if required by org)

Getting Approval

If your organization restricts OAuth apps:

1. Ask an org admin for approval
2. They can approve in Organization Settings > Third-party access
3. Once approved, repos will appear

Not Seeing Organization Repos?

Check:

• You're a member of the organization
• OAuth app is approved
• You have write access to repos

Troubleshooting

No Repositories Shown

Possible causes:

• GitHub connection expired
• No write access to any repos
• Organization restrictions

Solutions:

• Reconnect GitHub
• Create a new repository
• Request access to existing repos

Organization Repos Not Showing

Solutions:

• Request OAuth approval from org admin
• Check your membership in the organization
• Verify write access to specific repos

Repository Not Found After Selection

Try:

• Refresh the page
• Disconnect and reconnect GitHub
• Verify the repo still exists

Creating a New Repository

If you need a new repository for documentation:

1. Go to GitHub
2. Create a new repository
3. Return to ArchDoc
4. Refresh the repository list
5. Select the new repository

Recommended Settings for a Docs Repo

• Name: docs, documentation, or technical-docs
• Visibility: Private (unless public docs needed)
• Initialize: With README
• License: As appropriate for your org