Setting Up Your Three-Layer Backup
This is Part 3 of a series. In Part 1, I argued that open source licenses protect your code but not the infrastructure around it. In Part 2, I surveyed the landscape of options for keeping your code somewhere other than GitHub.
Today: I am setting it up.
At the end of Part 2, I said the strategy I would pick is three layers: an archive, a live mirror, and a local backup. Here is what that looks like in practice, start to finish.
Layer 1: Software Heritage (The Archive)
Software Heritage automatically crawls most public GitHub repositories, but “most” is not “all,” and crawl frequency varies. The first step is confirming your repos are actually in the archive.
Check if your repo is archived
Use the Software Heritage API to check the last visit:
|
1 |
curl -s "https://archive.softwareheritage.org/api/1/origin/https://github.com/your-username/your-repo/visit/latest/" | python3 -m json.tool |
If the response includes "status": "full" and a recent "date", you are covered. If you get a 404, the repo has never been crawled.
Trigger an archive if needed
For repos that have not been crawled (or were last visited months ago), use “Save Code Now”:
- Go to archive.softwareheritage.org/save/
- Select “git” as the origin type
- Enter the full repository URL (e.g.,
https://github.com/your-username/your-repo) - Submit
The visit is queued and typically completes within a few hours. You can also do this via the API:
|
1 |
curl -X POST "https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/your-username/your-repo/" |
Verify the archive
Once the visit completes, you can browse your archived code at:
|
1 |
https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://github.com/your-username/your-repo |
Every commit in the archive gets a SWHID (SoftWare Hash IDentifier). For git commits, the SWHID revision hash is the same as the git commit SHA, so swh:1:rev:abc123... maps directly to commit abc123... in your repo.
Batch-check multiple repos
If you have more than a handful of repositories, checking them one at a time gets tedious. Here is a bash script that checks all public repos for a GitHub user:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
#!/bin/bash # Check Software Heritage archive status for all public repos USERNAME="your-username" gh repo list "$USERNAME" --visibility=public --limit 100 --json nameWithOwner -q '.[].nameWithOwner' | while read -r repo; do status=$(curl -s -o /dev/null -w "%{http_code}" \ "https://archive.softwareheritage.org/api/1/origin/https://github.com/${repo}/visit/latest/") if [ "$status" = "200" ]; then echo "[archived] $repo" else echo "[MISSING] $repo" fi sleep 1 # respect rate limits done |
And the PowerShell equivalent. Save this as Check-SoftwareHeritage.ps1 and run it from any directory. It has full comment-based help, so Get-Help .\Check-SoftwareHeritage.ps1 -Full works out of the box.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 |
<# .SYNOPSIS Checks public GitHub repos against the Software Heritage archive. .DESCRIPTION Queries the Software Heritage API for each public repository belonging to the specified GitHub user. Reports archive status and last visit date. Optionally submits unarchived or stale repos for crawling via the "Save Code Now" API. Requires the GitHub CLI (gh) to be installed and authenticated. .PARAMETER Username GitHub username whose public repositories will be checked. .PARAMETER SubmitMissing When specified, automatically submits repos that have never been archived to Software Heritage for crawling. .PARAMETER SubmitStale When specified, resubmits repos whose last archive visit is older than the StaleDays threshold. .PARAMETER StaleDays Number of days after which an archived repo is considered stale. Defaults to 90. Only used when -SubmitStale is specified. .PARAMETER ActiveDays When specified, only checks repos that have been pushed to within the last N days. Skips dormant repos to reduce API calls and focus on actively developed projects. .PARAMETER IncludeForks When specified, includes forked repositories in the check. By default, forks are skipped since the upstream owner is responsible for archiving the original. .EXAMPLE .\Check-SoftwareHeritage.ps1 -Username your-username Status report only. No submissions. .EXAMPLE .\Check-SoftwareHeritage.ps1 -Username your-username -SubmitMissing Submits any unarchived repos for crawling. .EXAMPLE .\Check-SoftwareHeritage.ps1 -Username your-username -SubmitStale -StaleDays 30 Submits repos not visited in the last 30 days. .EXAMPLE .\Check-SoftwareHeritage.ps1 -Username your-username -ActiveDays 60 -SubmitMissing Only checks repos with commits in the last 60 days, submitting any that are unarchived. .EXAMPLE .\Check-SoftwareHeritage.ps1 -Username your-username -IncludeForks Checks all public repos including forks. #> [CmdletBinding()] param ( [Parameter(Mandatory)] [string]$Username, [switch]$SubmitMissing, [switch]$SubmitStale, [int]$StaleDays = 90, [int]$ActiveDays = 0, [switch]$IncludeForks ) $ghArgs = @("repo", "list", $Username, "--visibility=public", "--limit", "200", "--json", "nameWithOwner,pushedAt") if (-not $IncludeForks) { $ghArgs += "--source" } $ghJson = & gh @ghArgs 2>&1 if ($LASTEXITCODE -ne 0) { Write-Error "gh repo list failed (exit code $LASTEXITCODE). Is the GitHub CLI installed and authenticated?" Write-Error "gh output: $ghJson" exit 1 } $repoList = $ghJson | ConvertFrom-Json if (-not $repoList -or $repoList.Count -eq 0) { Write-Warning "No public repositories found for '$Username'." exit 0 } $activeThreshold = if ($ActiveDays -gt 0) { (Get-Date).AddDays(-$ActiveDays) } else { $null } $staleThreshold = (Get-Date).AddDays(-$StaleDays) $submitted = 0 $submitFailed = 0 $skipped = 0 $errors = 0 $swhHeaders = @{ "Accept" = "application/json" "User-Agent" = "Check-SoftwareHeritage/1.0 (PowerShell; +https://github.com/$Username)" } foreach ($entry in $repoList) { $repo = $entry.nameWithOwner $pushedAt = [datetime]$entry.pushedAt if ($activeThreshold -and $pushedAt -lt $activeThreshold) { $skipped++ continue } Start-Sleep -Seconds 1 # respect rate limits $uri = "https://archive.softwareheritage.org/api/1/origin/https://github.com/${repo}/visit/latest/" try { $response = Invoke-RestMethod -Uri $uri -Method GET -Headers $swhHeaders -ErrorAction Stop if ($response -is [string] -and $response -match "<!doctype html") { $errors++ Write-Host "[BLOCKED] $repo - SWH returned a bot-challenge page instead of JSON" -ForegroundColor Magenta continue } if (-not $response.date) { $errors++ Write-Host "[ERROR] $repo - SWH returned no visit date (origin may exist but has no completed visits)" -ForegroundColor Magenta continue } $visitDate = [datetime]$response.date $age = ((Get-Date) - $visitDate).Days if ($SubmitStale -and $visitDate -lt $staleThreshold) { Write-Host "[STALE] $repo (last archived ${age}d ago, submitting...)" -ForegroundColor Yellow $saveUri = "https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/${repo}/" try { Invoke-RestMethod -Uri $saveUri -Method POST -Headers $swhHeaders -ErrorAction Stop | Out-Null $submitted++ } catch { $submitFailed++ $submitStatus = $_.Exception.Response.StatusCode.value__ Write-Host "[FAILED] $repo save request failed (HTTP $submitStatus)" -ForegroundColor Magenta } } else { Write-Host "[OK] $repo (last archived ${age}d ago)" -ForegroundColor Green } } catch { $statusCode = $_.Exception.Response.StatusCode.value__ if ($statusCode -eq 404) { if ($SubmitMissing) { Write-Host "[MISSING] $repo (submitting...)" -ForegroundColor Red $saveUri = "https://archive.softwareheritage.org/api/1/origin/save/git/url/https://github.com/${repo}/" try { Invoke-RestMethod -Uri $saveUri -Method POST -Headers $swhHeaders -ErrorAction Stop | Out-Null $submitted++ } catch { $submitFailed++ $submitStatus = $_.Exception.Response.StatusCode.value__ Write-Host "[FAILED] $repo save request failed (HTTP $submitStatus)" -ForegroundColor Magenta } } else { Write-Host "[MISSING] $repo" -ForegroundColor Red } } elseif ($statusCode -eq 429) { $errors++ Write-Host "[RATELIM] $repo - rate limited by SWH API; wait a few minutes and retry" -ForegroundColor Magenta } else { $errors++ $msg = $_.Exception.Message Write-Host "[ERROR] $repo - HTTP $statusCode - $msg" -ForegroundColor Magenta } } } Write-Host "" if ($submitted -gt 0) { Write-Host "Submitted $submitted repo(s) to Software Heritage for archival." } if ($submitFailed -gt 0) { Write-Host "WARNING: $submitFailed submission(s) failed. Check [FAILED] entries above." -ForegroundColor Yellow } if ($skipped -gt 0) { Write-Host "Skipped $skipped dormant repo(s) (no pushes in last $ActiveDays days)." } if ($errors -gt 0) { Write-Host "Encountered $errors API error(s). Check [ERROR] and [RATELIM] entries above." -ForegroundColor Yellow } |
Here are some example command lines to get you started:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# Status report only; skips forks, checks all your non-fork public repos .\Check-SoftwareHeritage.ps1 -Username your-username # Same thing, but automatically submit any unarchived repos for crawling .\Check-SoftwareHeritage.ps1 -Username your-username -SubmitMissing # Only check repos you have pushed to in the last 60 days .\Check-SoftwareHeritage.ps1 -Username your-username -ActiveDays 60 # Resubmit repos not archived in the last 30 days, and submit any missing ones .\Check-SoftwareHeritage.ps1 -Username your-username -SubmitMissing -SubmitStale -StaleDays 30 # Include forked repos in the check (skipped by default) .\Check-SoftwareHeritage.ps1 -Username your-username -IncludeForks |
The script produces color-coded output: [OK] in green, [MISSING] in red, [STALE] in yellow. If something goes wrong with the API, you will see [ERROR], [RATELIM], or [BLOCKED] with an explanation of what happened and what to do about it. Forked repos are skipped by default since the upstream maintainer is typically responsible for archiving the original.
Any repo showing [MISSING] or [STALE] without the submission switches needs a “Save Code Now” submission (or rerun with the switch).
Total effort: About 15 minutes for a personal collection of 20-30 repos. Zero ongoing maintenance; Software Heritage handles future crawls automatically.
Layer 2: Codeberg Mirror (The Live Copy)
A Codeberg mirror gives you a functional forge that stays in sync with GitHub. If GitHub becomes unavailable, you can point people to Codeberg and they can clone, browse, and (if you choose to accept contributions there) open issues.
Step 1: Create a Codeberg account
Sign up at codeberg.org. Use the same username as GitHub if it is available; this makes URLs predictable.
Step 2: Create the mirror repository on Codeberg
For each repo you want to mirror, create a new empty repository on Codeberg. Do not initialize it with a README, license, or .gitignore. It needs to be completely empty so the first push from GitHub succeeds cleanly.
Step 3: Generate an SSH key pair
Create a dedicated key pair for the mirror workflow. This key should not be your personal SSH key; it is a deploy key with a single purpose.
|
1 |
ssh-keygen -t ed25519 -f ~/.ssh/codeberg-mirror -C "github-to-codeberg-mirror" -N "" |
The -N "" flag creates the key without a passphrase. This is required for unattended CI/CD use; GitHub Actions cannot type a passphrase interactively. The private key is protected by GitHub’s encrypted secrets storage rather than a passphrase, so this is the expected pattern for deploy keys.
This creates two files: ~/.ssh/codeberg-mirror (private key) and ~/.ssh/codeberg-mirror.pub (public key). On Windows, ssh-keygen ships with the built-in OpenSSH client (Windows 10 1809 and later); the same command works from PowerShell or Command Prompt, just use $env:USERPROFILE\.ssh\codeberg-mirror instead of ~/.ssh/codeberg-mirror if the tilde does not resolve.
A word about secrets. The private key file (codeberg-mirror, no .pub extension) must never be committed to a repository, pasted into a public issue, or shared in a chat log. Only the public key goes to Codeberg; only the GitHub Secrets web UI should ever see the private key. If you accidentally expose it, delete the Codeberg deploy key immediately and generate a new pair. Consider adding **/codeberg-mirror to your global .gitignore as an extra safeguard.
Step 4: Add the public key to Codeberg
In Codeberg, go to your mirror repository, then Settings, then Deploy Keys. Add the contents of ~/.ssh/codeberg-mirror.pub as a deploy key. Enable “Write” access; the mirror needs to push.
If you are mirroring multiple repos, you can add the public key to your Codeberg account settings (SSH/GPG Keys) instead of per-repo, which covers all repos at once.
Step 5: Add the private key to GitHub Actions
In your GitHub repository, go to Settings, then Secrets and variables, then Actions. Create a new repository secret named CODEBERG_SSH_KEY and paste the contents of ~/.ssh/codeberg-mirror (the private key).
Step 6: Create the workflow
Create .github/workflows/mirror-codeberg.yml in your repository:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
name: Mirror to Codeberg on: push: branches: [main] delete: workflow_dispatch: jobs: mirror: runs-on: ubuntu-latest steps: - name: Checkout with full history uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up SSH uses: webfactory/ssh-agent@v0.10.0 with: ssh-private-key: ${{ secrets.CODEBERG_SSH_KEY }} - name: Mirror to Codeberg run: | ssh-keyscan -t ed25519 codeberg.org >> ~/.ssh/known_hosts git remote add codeberg git@codeberg.org:your-username/your-repo.git || true git push --force --mirror codeberg |
What this does:
fetch-depth: 0clones the full history, not a shallow copywebfactory/ssh-agentloads the private key into the SSH agent for the workflow runssh-keyscanadds Codeberg’s host key so SSH does not prompt for confirmation--force --mirrorpushes all refs (branches, tags) and prunes anything on Codeberg that no longer exists on GitHub- Triggers on pushes to main, branch deletions, and manual dispatch
Step 7: Test it
Push a commit to main (or trigger the workflow manually via the Actions tab). Check the Actions run log. Then visit your Codeberg repo and verify the code, branches, and tags all match GitHub.
Security note
Pin the webfactory/ssh-agent action to a commit SHA rather than a tag for production use. Tags can be moved; commit SHAs cannot. Check the release page for the current SHA.
Also be aware: anyone with write access to the workflow file in your GitHub repo can modify it to exfiltrate the SSH private key. If you have collaborators, use a per-repo deploy key on Codeberg (not an account-wide key) to limit the blast radius.[2] In Codeberg, navigate to your repository, then Settings, then Deploy Keys; each key added there is scoped to that single repository.
Multiple repos
You need one workflow file per repo, but the pattern is identical. The only things that change are the repository secret name (if you use different keys per repo) and the Codeberg remote URL. If you use an account-wide SSH key on Codeberg, the same CODEBERG_SSH_KEY secret works across all repos; you just need to create the secret in each GitHub repo’s settings.
Layer 3: git bundle (The Local Backup)
A git bundle is the simplest possible backup: one file per repo, containing the complete git history, storable anywhere.
One-time backup
|
1 2 3 |
cd /path/to/your-repo git bundle create ~/backups/your-repo.bundle --all git bundle verify ~/backups/your-repo.bundle |
The verify command confirms the bundle is valid and lists what it contains.
Automated backups on Linux
Create a script that loops through your repos and produces dated bundles:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
#!/bin/bash # backup-repos.sh - Create git bundles for all local repos BACKUP_DIR="$HOME/backups/git-bundles" REPOS_DIR="$HOME/repos" DATE=$(date +%Y-%m-%d) mkdir -p "$BACKUP_DIR" for repo_dir in "$REPOS_DIR"/*/; do repo_name=$(basename "$repo_dir") if [ -d "$repo_dir/.git" ]; then echo "Bundling $repo_name..." cd "$repo_dir" git fetch --all --prune 2>/dev/null git bundle create "$BACKUP_DIR/${repo_name}-${DATE}.bundle" --all echo " -> $BACKUP_DIR/${repo_name}-${DATE}.bundle" fi done # Clean up bundles older than 90 days find "$BACKUP_DIR" -name "*.bundle" -mtime +90 -delete echo "Done. $(ls -1 "$BACKUP_DIR"/*-${DATE}.bundle 2>/dev/null | wc -l) repos backed up." |
Add it to crontab to run weekly:
|
1 2 3 |
crontab -e # Add this line: 0 3 * * 0 /home/your-username/backup-repos.sh >> /home/your-username/backups/backup.log 2>&1 |
That runs every Sunday at 3:00 AM, logging output for review.
Automated backups on Windows
The equivalent PowerShell script:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
# backup-repos.ps1 - Create git bundles for all local repos $BackupDir = "$env:USERPROFILE\Backups\git-bundles" $ReposDir = "$env:USERPROFILE\repos" $Date = Get-Date -Format "yyyy-MM-dd" New-Item -ItemType Directory -Path $BackupDir -Force | Out-Null Get-ChildItem -Path $ReposDir -Directory | ForEach-Object { $repoName = $_.Name $gitDir = Join-Path $_.FullName ".git" if (Test-Path $gitDir) { Write-Host "Bundling $repoName..." Push-Location $_.FullName git fetch --all --prune 2>$null git bundle create "$BackupDir\$repoName-$Date.bundle" --all Write-Host " -> $BackupDir\$repoName-$Date.bundle" Pop-Location } } # Clean up bundles older than 90 days Get-ChildItem -Path $BackupDir -Filter "*.bundle" | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-90) } | Remove-Item $count = (Get-ChildItem -Path $BackupDir -Filter "*-$Date.bundle").Count Write-Host "Done. $count repos backed up." |
Schedule it with Task Scheduler:
- Open Task Scheduler and click “Create Basic Task”
- Name it “Git Bundle Backup” and set it to run weekly
- Action: Start a program
- Program:
powershell.exe - Arguments:
-ExecutionPolicy Bypass -File "C:\Users\your-username\backup-repos.ps1" - Check “Open the Properties dialog” on finish, then set “Run whether user is logged on or not”
Restoring from a bundle
If you ever need to restore:
|
1 2 3 |
git clone your-repo-2026-05-26.bundle your-repo cd your-repo git remote set-url origin https://github.com/your-username/your-repo.git |
The clone creates a fully functional repo. Set the remote URL back to your actual upstream and you are right where you left off.
Putting It All Together
Here is what the complete setup looks like:
Software Heritage (one-time, 15 minutes)
- Checked all public repos via the API
- Submitted “Save Code Now” for any that were missing
- No ongoing maintenance needed
Codeberg mirror (per-repo, 10 minutes each)
- Created matching repos on Codeberg
- Generated a dedicated SSH key pair
- Added the workflow file to each GitHub repo
- Every push to main automatically mirrors to Codeberg
git bundle (one-time setup, runs automatically)
- Script loops through all local repos
- Creates dated bundle files weekly
- Cleans up bundles older than 90 days
- Runs on a schedule via crontab or Task Scheduler
Total cost: zero. Total ongoing effort: near zero, aside from occasionally checking that the Codeberg mirror workflow is still green.
Is this overkill for a personal project collection? Maybe. But the point of Part 1 was that platforms change, companies get acquired, and policies shift in ways we cannot predict. The total investment here is an afternoon of setup and a few hundred kilobytes of bundle files per week. Compared to the alternative (hoping everything will be fine), that seems like a reasonable trade.
What Comes Next
The three-layer strategy covers preservation and mirroring. But there is a step beyond mirroring: running your own forge.
Self-hosting a Forgejo instance as your primary source of truth, with GitHub acting as a distribution mirror rather than the canonical home, inverts the dependency entirely. Your code lives on your infrastructure, under your control, in whatever jurisdiction you choose. GitHub becomes a convenience, not a requirement.
That is a larger project with its own set of decisions (hosting, CI/CD runners, database backends, reverse proxy configuration), and it deserves its own writeup. Stay tuned.
Have you set up your own backup strategy? Find me on Bluesky or LinkedIn.
Notes
[1] Software Heritage’s “Save Code Now” feature queues an immediate crawl of any publicly accessible git repository. Processing time varies based on queue depth but typically completes within a few hours. The feature is available both via the web interface and the REST API. Rate limits apply to the API (approximately 120 requests per hour for unauthenticated users). Source: Software Heritage Save Code Now. ↩
[2] Codeberg deploy keys are repository-scoped by default. When “Write” access is enabled, the key can push to that specific repository. Account-level SSH keys (added via user settings) grant access to all repositories under that account. For mirroring, account-level keys reduce setup effort but increase blast radius if compromised. Source: Codeberg SSH key documentation. ↩
[3] The webfactory/ssh-agent GitHub Action loads an SSH private key into the agent for the duration of the workflow run. The key is not written to disk in plaintext; it is loaded directly into the agent via ssh-add. However, any step in the workflow can access the agent, so malicious or compromised actions in the same job could use the key. Pinning to a commit SHA (rather than a version tag) prevents tag-reassignment attacks. Source: webfactory/ssh-agent repository. ↩
[4] git bundle create --all includes all refs: branches, tags, and any other refs (e.g., refs/stash). The --all flag is equivalent to listing every ref manually. Bundle files are self-contained and can be verified with git bundle verify, which checks that all prerequisite commits are present. Incremental bundles (using a basis bundle) are possible for reducing transfer size in ongoing backup scenarios. Source: git-bundle documentation. ↩
[5] git push --mirror pushes all local refs (branches, tags, notes) to the remote and deletes any remote refs that do not exist locally. This makes the remote an exact copy of the local refs. Combined with --force, it overwrites any divergence on the remote. Caution: if used carelessly, --mirror can delete branches on the remote that were created there independently. For a one-way mirror (GitHub to Codeberg), this is the desired behavior. Source: git-push documentation. ↩