# Codeberg First ...
... Multi-Mirror Quick Start Strategies
**Version:** 1.0
**Last Updated:** 2025-12-30
**Author:** FOSSEA³M / c3hamm e.V.
[toc]
## TL;DR
**Already have a repo on GitHub/GitLab?** Use Codeberg's Migration Assistant:
1. Codeberg → **"New Migration"**
2. Paste GitHub/GitLab URL (authenticate if not public)
3. Done in 5 minutes
**Want automatic mirrors FROM Codeberg?**
1. Create tokens on GitHub/GitLab
2. Codeberg → Settings → Repository → Mirrors → Add Push Mirror
3. Push to Codeberg → auto-syncs to mirrors
**That's it.**
## Intro
### Why Codeberg First?
**Codeberg-First** means:
- Primary development on Codeberg (FOSS, EU-based, GDPR-compliant)
- GitHub/GitLab as read-only mirrors (visibility & discovery)
- No vendor lock-in, full control
- Support European FOSS infrastructure
### Prerequisites
- [ ] Codeberg account (free)
- [ ] GitHub account (for mirror)
- [ ] GitLab account (for mirror)
- [ ] 15 minutes of time
### How It Works
```
Codeberg (Origin)
↓ push
├─→ GitHub (Mirror, auto-sync)
└─→ GitLab (Mirror, auto-sync)
```
Push once to Codeberg → mirrors update automatically within seconds.
## Flow
### Step 1: Create Codeberg Repository
**Option A: New Project**
```bash
mkdir my-project && cd my-project
git init
echo "# My Project" > README.md
git add README.md && git commit -m "Initial commit"
git remote add origin git@codeberg.org:username/my-project.git
git push -u origin main
```
**Option B: Use Migration Assistant** (see Outro)
### Step 2: Create Mirror Repositories
#### GitHub
1. github.com → New repository
2. Name: `my-project` (same as Codeberg)
3. **Important:** Leave empty (no README, no .gitignore)
4. Create repository
#### GitLab
1. gitlab.com → New project → Create blank project
2. Name: `my-project`
3. **Important:** Uncheck "Initialize repository with a README"
4. Create project
### Step 3: Create Access Tokens
#### GitHub Token
1. Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token (classic)
3. Scopes: Check **repo**
4. Generate & copy token: `ghp_...`
#### GitLab Token
1. Preferences → Access Tokens
2. Scopes: Check **write_repository**
3. Create & copy token: `glpat-...`
### Step 4: Configure Push Mirrors
**In your Codeberg repository:**
1. Settings → Repository → scroll to **"Mirrors"**
2. Click **"Add Push Mirror"**
**For GitHub:**
- Mirror Repository URL: `https://github.com/username/my-project.git`
- Username: Your GitHub username
- Password: Paste GitHub token
- [x] Sync on push
- Add Push Mirror
**For GitLab:**
- Mirror Repository URL: `https://gitlab.com/username/my-project.git`
- Username: Your GitLab username
- Password: Paste GitLab token
- [x] Sync on push
- Add Push Mirror
### Step 5: Add Mirror Badges
Add to your `README.md`:
```markdown
> **Primary Repository:** [Codeberg](https://codeberg.org/username/my-project)
>
> **Read-only Mirrors:**
> [](https://github.com/username/my-project)
> [](https://gitlab.com/username/my-project)
```
Commit and push:
```bash
git add README.md
git commit -m "docs: Add mirror badges"
git push
```
Wait 30 seconds → check GitHub/GitLab → mirrors updated!
## Outro
### Quick Troubleshooting
**"Authentication failed"**
- Regenerate token, update in Codeberg mirror settings
**"Remote repository not found"**
- Check URL (must end with `.git`)
- Verify repository exists and is public
**Mirror not syncing**
- Check: Settings → Mirrors → ensure [x] "Sync on push" is enabled
- Manual trigger: Click "Sync Now" button
**Initial push failed**
- Mirror repo wasn't empty → delete mirror repo, recreate empty, reconfigure
### Resources
- [Codeberg Docs](https://docs.codeberg.org/)
- [Forgejo Mirroring](https://forgejo.org/docs/latest/user/repo-mirror/)
- [GitHub Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
- [GitLab Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
### One Last Thing... Migration is So Simple
**Already have repos on GitHub or GitLab?** Don't manually recreate them!
Codeberg has a **Migration Assistant** that handles everything:
#### How to Migrate (5 Minutes)
1. Codeberg → Click **+** icon → **"New Migration"**
2. Select source: **GitHub** or **GitLab**
3. Authentication:
- **GitHub:** Paste GitHub token (needs `repo` scope)
- **GitLab:** Paste GitLab token (needs `read_repository` scope)
4. Enter repository URL: `https://github.com/username/repo-name`
5. Configure:
- [x] Migrate repository
- [x] Migrate issues (optional)
- [x] Migrate pull requests (optional)
- [x] Migrate releases (optional)
- [x] Migrate wiki (optional)
6. Click **"Migrate Repository"**
**That's it.** Codeberg clones everything:
- Complete commit history
- All branches and tags
- Issues (with comments)
- Pull requests
- Releases
- Wiki
**After migration:**
- Your GitHub/GitLab repo stays untouched
- Now follow steps 2-4 above to set up mirrors back to GitHub/GitLab
- You've come full circle: Codeberg primary, others as mirrors
**Pro tip:** After successful migration, update your GitHub/GitLab repo description:
```
[Mirror] Development moved to Codeberg → https://codeberg.org/username/repo-name
```
Pin an issue explaining the migration, archive the old repo if desired.
### Best Practices
**Checklist for production:**
- [ ] Add LICENSE file
- [ ] Update README with mirror badges
- [ ] Pin issue on mirrors explaining Codeberg-first approach
- [ ] Update repo descriptions on GitHub/GitLab
- [ ] Configure issue templates on Codeberg
- [ ] Add CONTRIBUTING.md pointing to Codeberg
**Mirror notices:** Add to GitHub/GitLab repo descriptions:
```
[Mirror] Read-only | Development on Codeberg → codeberg.org/username/repo
```
## License
- Code snippets: CC0 (Public Domain)
- Documentation: CC-BY-SA 4.0
## Colophon
Created by FOSSEA³M Research Group / c3hamm e.V.
Maintained on Codeberg.org, mirrored to GitHub & GitLab.
Made for the FOSS community.