Git Integration Overview
Connecting your Git repository to Archyl enables AI-powered architecture discovery, keeping your documentation in sync with your actual code.
Supported Providers
Archyl supports all major Git hosting platforms:
Cloud Providers
| Provider | OAuth | Features |
|---|---|---|
| GitHub | Yes | Full support |
| GitLab | Yes | Full support |
| Bitbucket | Yes | Full support |
Self-Hosted
| Provider | Auth Method | Features |
|---|---|---|
| GitHub Enterprise | Token | Full support |
| GitLab Self-Managed | Token | Full support |
| Gitea | Token | Full support |
| Azure DevOps | Token | Full support |
Connecting a Repository
Step 1: Navigate to Project Settings
- Open your project
- Click on Settings
- Go to "Repository" tab
Step 2: Choose Provider
- Click "Connect Repository"
- Select your Git provider
- Authorize Archyl (for OAuth providers)
Step 3: Select Repository
- Browse your available repositories
- Select the repository to connect
- Choose the default branch
- Click "Connect"
Authentication
OAuth (Recommended)
For GitHub, GitLab, and Bitbucket cloud:
- Click "Connect with [Provider]"
- Authorize Archyl in the popup
- Select repositories to grant access
OAuth tokens are securely stored and automatically refreshed.
Personal Access Tokens
For self-hosted or enterprise providers:
- Generate a token in your Git provider
- Required scopes:
repo(read access) - Enter the token in Archyl
Repository Access
What Archyl Reads
During AI Discovery, Archyl reads:
- File structure and names
- Source code content
- Configuration files (package.json, go.mod, etc.)
- README files
What Archyl Never Accesses
- Environment files (.env)
- Credentials or secrets
- Git history
- Other branches (unless explicitly selected)
Multiple Repositories
Connect multiple repositories to a single project:
Monorepo
For monorepos, connect once and specify paths:
/services/api
/services/web
/packages/shared
Multi-Repo
For separate repositories:
- Connect each repository
- Map to systems or containers
- Discovery runs across all repos
Webhooks (Coming Soon)
Automatic sync on push:
- Trigger discovery on code changes
- Update architecture automatically
- Keep documentation current
Troubleshooting
Authorization Failed
- Check your token has required permissions
- Ensure OAuth app is authorized
- Try reconnecting
Repository Not Found
- Verify you have access to the repository
- Check the repository URL
- Ensure the branch exists
Discovery Errors
- Check excluded paths
- Reduce concurrency settings
- Review AI provider limits