Connect GitHub Repository

md0 CMS uses GitHub OAuth to securely connect to your repositories. This guide explains the connection process, permissions, and repository management.

GitHub OAuth Connection

Initial Connection

1. Click "Connect GitHub" on the md0 CMS homepage
2. You'll be redirected to GitHub's authorization page
3. Review the permissions md0 CMS requests
4. Click "Authorize md0 CMS"
5. You'll be redirected back to md0 CMS

Required Permissions

md0 CMS requests the following GitHub permissions:

• Read repository contents: To display your files and collections
• Write repository contents: To save content changes
• Read repository metadata: To list repositories and branches
• User email: To attribute commits to you

These permissions allow md0 CMS to function as a content editor while keeping your content in GitHub.

Selecting a Repository

After authorization, you'll see a list of your accessible repositories.

Repository Requirements

• Must be a public repository (private repo support coming soon)
• You must have write access to the repository
• Repository should contain markdown files (or be ready for them)

Selecting Your Repository

1. Browse or search your repositories
2. Click on the repository you want to manage
3. md0 CMS will analyze the repository structure
4. You'll be taken to the collection setup screen

Repository Settings

Once connected, you can configure repository-specific settings.

Branch Selection

By default, md0 CMS works with your default branch (usually main or master).

To change branches:

1. Go to Settings > Repository
2. Select "Change Branch"
3. Choose from available branches
4. Content will load from the selected branch

Branch Protection

If your repository has branch protection rules:

• md0 CMS respects pull request requirements
• Changes may require review before merging
• Status checks must pass before commits

Multiple Repositories

You can connect multiple repositories to md0 CMS.

Adding Additional Repositories

1. Click your profile icon
2. Select "Add Repository"
3. Authorize access if needed
4. Select the new repository

Switching Between Repositories

Use the repository switcher in the top navigation to move between connected repositories.

Repository Structure

md0 CMS works with any repository structure. Common patterns:

Blog Structure

my-blog/
├── content/
│   ├── posts/
│   │   ├── 2024-01-01-first-post.md
│   │   └── 2024-01-15-second-post.md
│   └── pages/
│       ├── about.md
│       └── contact.md
└── public/
    └── images/

Documentation Structure

my-docs/
├── docs/
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quick-start.md
│   ├── guides/
│   └── api/
└── static/

Multi-Site Structure

monorepo/
├── blog/
│   └── content/
├── docs/
│   └── pages/
└── marketing/
    └── content/

md0 CMS collections use path patterns to target specific directories within any structure.

Security and Privacy

Data Security

• OAuth tokens are encrypted and stored securely
• Repository access is scoped to only what you authorize
• No data storage: Content remains in your GitHub repository
• Secure connections: All communication uses HTTPS

Revoking Access

To revoke md0 CMS access to your GitHub account:

1. Go to GitHub Settings > Applications
2. Find "md0 CMS" in Authorized OAuth Apps
3. Click "Revoke"

Alternatively, disconnect from md0 CMS settings.

Audit Trail

All changes made through md0 CMS appear in your GitHub commit history:

• Commits are attributed to your GitHub user
• Commit messages indicate the action taken
• Full Git history is preserved

Connection Management

Reconnecting

If your connection expires or is revoked:

1. You'll see a "Reconnect GitHub" prompt
2. Click to reauthorize
3. Your settings and collections are preserved

Connection Status

Check your connection status:

• Green indicator: Connected and active
• Yellow indicator: Connection warning (token expiring)
• Red indicator: Disconnected (reauthorization needed)

Troubleshooting

Can't See My Repository

Possible causes:

• Repository is private (not yet supported)
• You don't have write access
• Repository is archived

Solutions:

• Make repository public
• Request write access from repository owner
• Unarchive the repository

Authorization Failed

Common issues:

• GitHub is down or experiencing issues
• Browser blocking third-party cookies
• Ad blocker interfering with OAuth flow

Solutions:

• Try again in a few minutes
• Allow cookies for md0.io and github.com
• Temporarily disable ad blocker
• Try a different browser

Repository Not Loading

Possible causes:

• Very large repository (thousands of files)
• Network connectivity issues
• GitHub API rate limits

Solutions:

• Wait a moment and refresh
• Check your internet connection
• Contact support if issue persists

Best Practices

Repository Organization

• Use clear, consistent folder structures
• Keep content separate from code
• Use descriptive file names
• Follow a naming convention

Branch Strategy

• Use main or master for production content
• Create feature branches for major content updates
• Use branch protection for team workflows
• Merge via pull requests for review

Commit Messages

md0 CMS generates commit messages automatically:

Create new post: "Getting Started with md0 CMS"
Update post: "Quick Start Guide"
Delete post: "Deprecated Tutorial"

You can customize commit message templates in settings.

Next Steps

Once your repository is connected:

1. Create Collections to organize content
2. Define Schemas for frontmatter validation
3. Start Editing your content

Related Documentation

• GitHub Sync - How synchronization works
• Collection Patterns - Path pattern configuration
• Media Management - Managing repository assets