Service: Gitea Backuper - EyevinnOSC/community GitHub Wiki

Gitea Backuper

Gitea Backuper (serviceId eyevinn-gitea-backuper, license MIT) creates encrypted, full Git mirror backups of a Gitea instance and stores them in S3-compatible object storage such as MinIO. It also restores such backups. In Eyevinn Open Source Cloud (OSC) it is a job (one-shot) service: each instance performs a single backup or restore operation and then stops. Schedule it as an OSC Agent Task, or create a new instance each time, to automate regular backups.

What it can do

  • Back up a Gitea instance (repositories, user lists, organization data) as a full Git mirror archive.
  • Encrypt the archive with AES-256-CBC using a passphrase you provide.
  • Store the archive in MinIO or any S3-compatible bucket.
  • Restore an archive from the bucket to a target Gitea instance (download, decrypt, restore).
  • Use an archive format compatible with Database Backuper (same encryption format).

Creating an instance

Prerequisites, created and running first:

  • A Gitea instance on OSC.
  • A MinIO instance (or other S3-compatible storage) with a bucket already created.
  • A Gitea admin API token (generated in Gitea under Settings, Applications, Access Tokens).

Store credentials as service secrets with create-service-secret (serviceId eyevinn-gitea-backuper):

Secret name Value
giteatoken Gitea admin API token
s3accesskey MinIO/S3 access key
s3secretkey MinIO/S3 secret key
encryptionkey Passphrase for AES-256-CBC encryption (keep it safe, it is needed to restore)

Then call create-service-instance with serviceId: "eyevinn-gitea-backuper":

{
  "name": "mybackup",
  "Operation": "backup",
  "GiteaUrl": "https://myorg-mygitea.go-gitea-gitea.auto.prod-se.osaas.io",
  "GiteaToken": "{{secrets.giteatoken}}",
  "S3Endpoint": "https://myminio.minio-minio.auto.prod-se.osaas.io",
  "S3Bucket": "backups",
  "S3ObjectKey": "gitea/2026-05-12T08:00:00Z.tar.gz.enc",
  "S3AccessKey": "{{secrets.s3accesskey}}",
  "S3SecretKey": "{{secrets.s3secretkey}}",
  "EncryptionKey": "{{secrets.encryptionkey}}"
}

The service performs the backup and stops. Check get-logs-for-instance to confirm success.

To restore, create a new instance with "Operation": "restore", the same connection fields, and S3ObjectKey set to the object key of the archive to restore from. The EncryptionKey must match the one used for the backup.

Equivalent OSC CLI usage:

osc secret create eyevinn-gitea-backuper giteatoken --value "<your-admin-token>"
osc create eyevinn-gitea-backuper mybackup \
  -o Operation="backup" \
  -o GiteaUrl="https://myorg-mygitea.go-gitea-gitea.auto.prod-se.osaas.io" \
  -o GiteaToken="{{secrets.giteatoken}}" \
  -o S3Endpoint="https://myminio.minio-minio.auto.prod-se.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}}"

Options

Option Required Type Meaning
name Yes string Name of the instance (a name for this run). Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
Operation Yes string backup to create a full Git mirror backup, or restore to restore from a previously created backup.
GiteaUrl Yes string Base URL of the Gitea instance to back up or restore. Example: https://acme-acmegit.go-gitea-gitea.auto.prod.osaas.io.
GiteaToken Yes string, sensitive Admin API token for the Gitea instance. Needed to access all repositories, user lists and organization data.
S3Endpoint No string Endpoint URL of the MinIO or S3-compatible storage. Example: https://minio.example.com. Needed in practice to store or fetch archives.
S3Bucket No string Bucket where backups are stored or retrieved from. Example: backups. The bucket must exist and be accessible with the credentials.
S3ObjectKey No string Object key (path) of the archive in the bucket. For backup it often includes a timestamp, for example gitea/my-instance/2026-05-01T12:00:00Z.tar.gz.enc; for restore it points to the existing archive.
S3AccessKey No string, sensitive Access key for the S3/MinIO storage; used together with S3SecretKey.
S3SecretKey No string, sensitive Secret key for the S3/MinIO storage; used together with S3AccessKey.
S3Region No string Region of the S3 service. Optional for S3-compatible storage.
EncryptionKey No string, sensitive AES-256-CBC passphrase for encrypting or decrypting the archive. If omitted, the archive is stored unencrypted. Must match between backup and restore.

The S3 options are marked optional in the catalog but are needed in practice to store or retrieve an archive. Sensitive options should be given as {{secrets.NAME}}, which must be the entire field value.

Limitations

  • Each instance performs one operation and stops.
  • There is no way to recover an encrypted backup without the EncryptionKey; store it securely.
  • Omitting EncryptionKey stores the archive unencrypted, which is not recommended for production.

Resources