Getting Started

Gitea Backuper is an open source service that creates encrypted, full-mirror backups of a Gitea instance and stores them in S3-compatible object storage (such as MinIO). It supports both backup and restore operations. Available as an open web service in Eyevinn Open Source Cloud.

Gitea Backuper is a one-shot service: each instance run performs a single backup or restore operation, then stops. Schedule it as an OSC Agent Task (or run it manually) to automate regular backups.

Prerequisites

  • If you have not already done so, sign up for an Eyevinn OSC account
  • A running Gitea instance on OSC
  • A running MinIO instance (or other S3-compatible storage) with a bucket created
  • A Gitea admin API token (generated in Gitea under Settings → Applications → Access Tokens)

Step 1: Store credentials as secrets

Navigate to the Gitea Backuper service. Go to the Service Secrets tab and create the following secrets:

Secret name Value
giteatoken Your Gitea admin API token
s3accesskey Your MinIO/S3 access key
s3secretkey Your MinIO/S3 secret key
encryptionkey A passphrase for AES-256-CBC encryption (keep this safe — you need it to restore)

Step 2: Create a backup instance

Go to My gitea-backupers and click Create gitea-backuper. Fill in:

  • Name: a name for this run (alphanumeric only, e.g. mybackup)
  • Operation: backup
  • GiteaUrl: the URL of your Gitea instance (e.g. https://myorg-mygitea.go-gitea-gitea.auto.prod.osaas.io)
  • GiteaToken: {{secrets.giteatoken}}
  • S3Endpoint: the URL of your MinIO instance (e.g. https://myminio.minio-minio.auto.prod.osaas.io)
  • S3Bucket: the name of your backup bucket (e.g. backups)
  • S3ObjectKey: a path for the backup archive (e.g. gitea/2026-05-12T08:00:00Z.tar.gz.enc)
  • S3AccessKey: {{secrets.s3accesskey}}
  • S3SecretKey: {{secrets.s3secretkey}}
  • EncryptionKey: {{secrets.encryptionkey}}

Click Create. The service performs the backup and stops when complete. Check the instance logs to confirm success.

Step 3: Restore from backup

To restore, create a new instance with:

  • Operation: restore
  • All the same connection fields as above
  • S3ObjectKey: the object key of the backup archive to restore from

The service will download, decrypt, and restore the archive to the target Gitea instance.

Using the CLI

# Create secrets first
osc secret create eyevinn-gitea-backuper giteatoken --value "<your-admin-token>"
osc secret create eyevinn-gitea-backuper s3accesskey --value "<access-key>"
osc secret create eyevinn-gitea-backuper s3secretkey --value "<secret-key>"
osc secret create eyevinn-gitea-backuper encryptionkey --value "<passphrase>"

# Run a backup
osc create eyevinn-gitea-backuper mybackup \
  -o Operation="backup" \
  -o GiteaUrl="https://myorg-mygitea.go-gitea-gitea.auto.prod.osaas.io" \
  -o GiteaToken="{{secrets.giteatoken}}" \
  -o S3Endpoint="https://myminio.minio-minio.auto.prod.osaas.io" \
  -o S3Bucket="backups" \
  -o S3ObjectKey="gitea/2026-05-12T08:00:00Z.tar.gz.enc" \
  -o S3AccessKey="{{secrets.s3accesskey}}" \
  -o S3SecretKey="{{secrets.s3secretkey}}" \
  -o EncryptionKey="{{secrets.encryptionkey}}"

Notes

  • The EncryptionKey must match exactly between backup and restore operations. Store it securely — there is no way to recover a backup without it.
  • The backup archive format is compatible with Database Backuper.
  • Omitting EncryptionKey stores the archive unencrypted — not recommended for production use.

Resources