GitBackups

Storage guides

Back up GitHub to Cloudflare R2

Gitbackups backs up your GitHub repositories on a schedule into a bucket you own. This guide sets up Cloudflare R2 for it in about five minutes. You end up with:

  • A private bucketYours. The backups stay if you leave.
  • A narrow keyOnly what backups need, on one bucket.
  • A cleanup ruleClears the leftovers of a failed upload.

How Gitbackups connects to Cloudflare R2

  • Gitbackups talks to R2's S3-compatible API at https://<account-id>.r2.cloudflarestorage.com, with virtual-hosted addressing and the region set to auto.
  • Each run uploads every repository as a git bundle file, at <prefix><owner>/<repo>/<timestamp>-<id>.bundle. The files are yours: if you stop using Gitbackups, they stay where they are.
  • It never lists your bucket. Every file it writes is recorded on our side, so retention deletes only files Gitbackups wrote, and the newest backup of each repository is never deleted.
  • On GitHub, Gitbackups is a GitHub App that asks for read access to repository contents and nothing more.

1. Create the bucket

  • Cloudflare dashboard → R2 object storage → Create bucket.
  • The location can stay on automatic.

2. Create a key for Gitbackups only

  • R2 object storage → Overview → next to API Tokens, Manage → Create Account API token.
  • Permission: Object Read & Write.
  • Scope it to this one bucket, never all buckets.
  • Create the token. The page shows an Access Key ID, a Secret Access Key and your S3 endpoint. Copy all three now: the secret is shown only once.

3. Give it these four permissions, and no more

  • R2 tokens don't take a policy document, and their permission levels are broader than the four actions below.
  • Scoping the token to this single bucket is the step that matters.
  • Gitbackups only ever uses the four actions below.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GitbackupsArchives",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::BUCKET/gitbackups/*"
    }
  ]
}

4. Add the incomplete-upload cleanup rule

Bucket → Settings → Object lifecycle rules → Add rule.

“Abort multipart uploads” after 1 day.

5. Versioning: leave it off

We recommend no versioning. Every run uploads a full archive, and the newest backup of every repository is never deleted, whatever your retention setting says. Versioning on top of full archives multiplies your storage bill by the number of runs you keep, for a second copy of data you already have.

6. Connect it in Gitbackups

In Gitbackups, choose Cloudflare R2 as your storage. Here is each field in the form, and what Cloudflare calls the value that goes in it.

  1. Regionfixed
    No label of its own

    Always auto on R2. We fill it in and the field is fixed.

  2. Endpointrequired
    S3 API endpoint

    https://<account-id>.r2.cloudflarestorage.com. Shown at the bottom of the token page in step 2, and on R2 Overview. If your bucket has a jurisdiction (EU, FedRAMP), use the endpoint for that jurisdiction.

  3. BucketrequiredThe name only. Not a URL.
    No label of its own

    What you named the bucket in step 1.

  4. Path prefixoptionalUse one if anything else writes to this bucket.
    No label of its own

    A folder of your choice, e.g. gitbackups/. R2 tokens cover a whole bucket, so this keeps things tidy rather than fenced.

  5. Access key IDrequiredWe only ever show its last four characters.
    Access Key ID

    Shown when you create the token in step 2.

  6. Secret access keyrequiredEncrypted on arrival. Never shown again.
    Secret Access Key

    Shown once, on the same page. Lost it? Create a new token.

Then press Test connection. Gitbackups writes a small file under your prefix, reads it back, deletes it, and starts and aborts one empty multipart upload. If a step is refused, the screen tells you which permission is missing.

Start backing up

Sign up for Gitbackups, install the GitHub App, and point it at your Cloudflare R2 bucket.

Setting up a different provider? AWS S3 · Backblaze B2 · Wasabi · MinIO and other S3-compatible storage