Backup and Restore

The One Code's Protect module creates complete, verified backups of your clients' code repositories and gives you the tools to restore them when needed. This page covers backup scheduling, what gets included, integrity verification, retention management, and the restore process.

What Gets Backed Up

Each backup job captures a comprehensive snapshot of the repository:

Component	Included	Notes
Git mirror	Always	All branches, tags, full commit history
Issues	Yes	Open and closed, with comments
Pull requests	Yes	Open, merged, and closed, with reviews
Wiki	Yes	All pages
Releases	Yes	Release metadata and release notes
GitHub Actions workflows	Yes	Workflow YAML files
Repository settings	Yes	Branch protection rules, webhooks, deploy keys

The git mirror captures the complete repository history — every branch, every tag, every commit — not just the current state of the default branch. This is a true point-in-time snapshot.

Backup Types

Full backup — Captures all of the above components from scratch. Used for:

• First backup after connecting an org
• Manual backups triggered by a technician
• Weekly scheduled backups

Incremental backup — Captures only what changed since the last full backup. Used for:

• Daily and hourly scheduled backups

The Protect+ tier uses incremental backups for efficiency. Each backup record stores its type, size, and what it includes.

Backup Schedules

You configure schedules at the org level, with per-repo overrides available:

Schedule	Frequency	Best For
hourly	Every hour	Active development, compliance-critical repos
daily	Once per day	Most production repositories
weekly	Once per week	Archived or low-change repos

Configure the schedule from the Organization detail page under Settings, or per-repo from the Repository detail page under Settings.

You can also enable on-push backups for individual repos, which triggers a backup within a few minutes of any push to the default branch. This gives you near-real-time protection for your most critical repositories.

Retention Policy

Backup snapshots expire after the retention period configured on the organization. The default is 90 days.

Common retention configurations:

Use Case	Recommended Retention
Standard MSP agreement	90 days
SOC 2 evidence retention	365 days
Long-term archive	730 days (2 years)

When a backup's retention period expires, the snapshot is automatically deleted from Azure Blob Storage and the backup record is removed.

⚠️Legal hold prevents a backup from being deleted even after retention expires. Set legal hold on a repo if the client is involved in litigation or a compliance investigation. Only admins can set or clear legal hold, and clearing it while active will return an error.

Escrow

The One Code supports code escrow for client agreements that require it. When a repo is marked as escrowed:

1. A formal EscrowAgreement record is created
2. The backup for that repo is flagged is_escrowed: true
3. The backup cannot be deleted manually — it persists until the escrow is released or expired

Escrow use cases for MSPs:

• Client contracts that require the source code to be held by a neutral third party
• Situations where the MSP maintains custom-built software on behalf of a client
• Regulatory requirements in certain industries

To set escrow on a repository, you need Admin role. Navigate to the repo detail page and click Enable Escrow.

Backup Health and Monitoring

The Backups page shows a health view across all organizations and repositories:

• Backed Up — Latest backup is current and verified
• Pending — Backup job is queued or in progress
• Error — The most recent backup job failed
• Never — No backup has been run yet (repo was just connected)
• Paused — Backup is paused (org was disconnected)

The stats summary shows:

• Total repositories
• Repositories with active backup
• Repositories not yet backed up
• Repositories with backup failures
• Last backup date and next scheduled backup

For any repo in Error state, click into the backup detail to see the error message. Common causes include temporary GitHub API timeouts — triggering a manual backup usually resolves these.

Backup Integrity Verification

Every completed backup is automatically verified. The verification checks:

Check	What It Confirms
zip_integrity	The backup archive is not corrupted
git_fsck	The git mirror passes git fsck — no object corruption
metadata_valid	Backup metadata fields are populated correctly
commit_count_match	Commit count in backup matches GitHub's reported count
size_match	Backup size is within expected range of the previous backup

Each check reports pass, fail, or skipped. A backup is marked fully verified only when all applicable checks pass. You can re-run verification manually from the backup detail page.

Manual Backup

Trigger a manual backup for any repository:

1. Navigate to the repo detail page (via Portfolio or the org's repo list)
2. Click Trigger Backup
3. A full backup job is queued at high priority (priority 8 out of 10)
4. The job appears in the backup history with status pending, then running, then completed

Manual backups are always full backups — they capture everything regardless of what the scheduled type would be.

Browsing Backup Contents

From the backup detail page, you can browse the contents of a completed backup:

• Summary — Branch count, tag count, total commit count, issue count, PR count
• Issues — Browse issues stored in the backup
• Pull Requests — Browse PRs stored in the backup
• Download — Generate a time-limited SAS URL to download the full backup archive as a ZIP

The Restore Process

The One Code supports several restore types:

Restore Type	What It Does
full_repo	Restores the complete repository (git history + issues + PRs + wiki)
issues_only	Restores only issue history
wiki_only	Restores only wiki pages
releases_only	Restores only releases
download_zip	Provides a download link without creating a new GitHub repository

Restore targets:

Target	Where the Restore Goes
original_org	Back into the same GitHub organization
new_org	Into a different GitHub organization
download	Download the archive without restoring to GitHub

To initiate a restore:

1. Navigate to Backups and find the backup you want to restore
2. Click Restore
3. Select the restore type (full repo, issues only, etc.)
4. Select the restore target (original org, new org, or download)
5. For org restores, provide the repository name for the restored copy
6. Click Start Restore

The restore job is queued and processed by the worker fleet (Azure Service Bus + Consumption plan workers for burst scaling). Large repositories may take a few minutes.

You can monitor restore progress on the restore job detail page. When complete:

• GitHub restore — The restored repository appears in the target org
• Download — A time-limited download link appears (valid for several hours)

💡For disaster recovery scenarios, keep the download URL handy — it doesn't require GitHub App access. You can use it to get the code to any environment regardless of GitHub availability.

Repo Timeline

The Repo Timeline view shows the full backup history for a single repository — every snapshot in chronological order with its type (full/incremental), status, size, and verification status.

Navigate to it from the repo detail page by clicking View Timeline, or directly at /repos/:repoId/timeline.

Use the timeline to:

• Find a specific point-in-time snapshot for restore
• Compare backup sizes over time (large increases may indicate a large file was accidentally committed)
• Verify that backup frequency matches the configured schedule