Connecting GitHub

Connect your GitHub account to enable document syncing to your repositories using the ArchDoc GitHub App.

Prerequisites

Before connecting:

• ✅ You're on a Base or Premium plan
• ✅ You have the Admin role in ArchDoc
• ✅ You have a GitHub account with access to the repositories you want to use

How to Connect

Step 1: Access Integrations

1. Navigate to Dashboard
2. Click Integrations in the sidebar
3. Find the GitHub section

Step 2: Start Connection

1. Click the Connect GitHub button
2. You'll be redirected to the GitHub App installation page

Step 3: Install the GitHub App

On the GitHub App installation page:

1. Select the account (personal or organization) to install the App on
2. Choose which repositories to grant access to
3. Click Install

Step 4: Select a Repository

After installation you'll be prompted to select which repository ArchDoc should sync documents into. You can change this at any time from the Integrations page.

Step 5: Return to ArchDoc

1. You're redirected back to ArchDoc automatically
2. A success message appears
3. The GitHub section shows Connected with the account name

Permissions Requested

The ArchDoc GitHub App requests the minimum permissions needed:

What Gets Connected

When you install the App:

• Your GitHub App installation is linked to your ArchDoc organization
• Installation credentials are securely stored (tokens generated on-demand, never persisted)
• You can select which repository to sync to

After Connecting

Once connected, you'll see:

• Your GitHub account displayed with a Connected badge
• Option to select or change the synced repository
• Ability to disconnect

Next step: Select a repository

Using Organization Repositories

If you want to sync to a GitHub organization's repository:

1. During App installation, select the organization account
2. You must have admin rights in that organization, or an org admin must approve the install
3. Once installed on the org, select the desired repo in ArchDoc

GitHub Organization Settings

If your org requires approval for App installs:

1. Go to GitHub > Organization Settings > GitHub Apps
2. Find ArchDoc in pending requests
3. Have an org admin approve the installation

Troubleshooting

Authorization Failed

If the connection fails:

• Ensure you completed the GitHub App installation fully
• Try disconnecting and reconnecting
• Check you have the Admin role in ArchDoc

App Already Installed

If ArchDoc was previously installed on your GitHub account, clicking Connect again will generate a new CSRF state and re-verify the existing installation. You'll be taken through the install flow again — you can simply confirm the existing installation.

Missing Repositories

If expected repositories don't appear:

• The App may only have access to selected repos — update the installation permissions on GitHub
• For org repos, ensure the org has approved the App installation
• Verify you have write access to the repository

Possible causes:

• You denied the authorization
• Browser blocked the redirect
• GitHub is having issues

Solution:

• Try the connection again
• Use a different browser
• Check GitHub's status page

"Only Admins Can Connect"

You need Admin role in ArchDoc:

• Ask your current Admin to either:
  • Connect GitHub themselves
  • Promote you to Admin

Can't See Organization Repos

Ensure:

• You have access to the organization
• OAuth apps are allowed
• Your access hasn't been restricted

Token Expired

Access tokens may expire:

• Disconnect and reconnect
• Re-authorize with GitHub

Disconnecting

To disconnect GitHub:

1. Go to Dashboard > Integrations
2. Find the GitHub section
3. Click Disconnect
4. Confirm the disconnection

What Happens When Disconnecting

• Access token is deleted
• Repository selection is cleared
• Previously synced documents remain in GitHub
• You can no longer sync new documents

Reconnecting

To reconnect after disconnecting:

1. Click Connect GitHub again
2. Re-authorize with GitHub
3. Select a repository

Security Best Practices

Personal Access

• Use your own GitHub account
• Don't share GitHub credentials
• Enable 2FA on GitHub

Repository Choice

• Consider a dedicated docs repository
• Limit access to necessary people
• Use branch protection rules

Review Access

• Periodically review OAuth authorizations on GitHub
• Revoke access for apps you don't use
• Monitor repository activity

Revoking Access from GitHub

You can also revoke ArchDoc's access directly from GitHub:

1. Go to GitHub > Settings > Applications > Authorized OAuth Apps
2. Find ArchDoc
3. Click Revoke