GitBackups

Storage guides

Back up GitHub to MinIO or any S3-compatible storage

Gitbackups backs up your GitHub repositories on a schedule into a bucket you own. This guide sets up MinIO and other S3-compatible storage 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 MinIO and other S3-compatible storage

  • Gitbackups talks to your service’s S3 API at the endpoint you give it, with path-style addressing, which is what most self-hosted services expect.
  • It does not send the newer S3 request checksum headers, which many S3-compatible services do not accept.
  • The endpoint must be reachable from the public internet: we refuse endpoints that resolve to private or internal addresses.
  • 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

Create a private bucket on your S3-compatible service (MinIO, Ceph, Garage, a storage appliance).

2. Create a key for Gitbackups only

  • Create a service account or user with its own access key and secret key.
  • It should not be an admin key.

3. Give it these four permissions, and no more

  • If your service takes S3 policy documents, use the one below unchanged.
  • If it only has read/write toggles, grant read and write on the prefix and leave any “list bucket” permission off.
{
  "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

If your service supports lifecycle rules, add one that aborts incomplete multipart uploads after 1 day. Your service's docs say where it lives.

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 MinIO and other S3-compatible storage as your storage. Here is each field in the form, and what your service calls the value that goes in it.

  1. Region
    No label of its own

    Whatever your service reports, or us-east-1 if it does not care.

  2. Endpointrequired
    No label of its own

    The full URL of your S3 API, e.g. https://s3.example.com. It must be reachable from the public internet.

  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

    The folder in your step 3 policy, e.g. gitbackups/. Must match it exactly.

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

    From the service account or user in step 2.

  6. Secret access keyrequiredEncrypted on arrival. Never shown again.
    Secret key

    Created alongside the access key, for the same account.

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 MinIO and other S3-compatible storage bucket.

Setting up a different provider? AWS S3 · Cloudflare R2 · Backblaze B2 · Wasabi