Restic Backups

Restic Backups is a YAML configuration and CLI layer for multiple restic repositories, with optional SOPS decryption. It supports S3-compatible services, mounted local storage, multiple repositories and backup jobs, managed private metadata directories, and a complete macOS Voice Memos workflow. It can also maintain and snapshot complete GitHub repository mirrors and selected GitHub-hosted data, either from an explicit URL list or by discovering every repository owned by an organization or user.

Start here

  • Quick Start creates, validates, and restores a first backup.
  • Configuration describes storage, restic repositories, jobs, and Glacier policy.
  • Jobs describes the shared model and commands for every job type.
  • Generic Backups covers standard restic operations for any local files or directories.
  • GitHub Backups introduces explicit repository lists, organization or user discovery, and optional components.
  • GitHub Authentication covers laptops, containers, SSH, HTTPS, API tokens, and Kubernetes.
  • Run GitHub Backups covers execution and inspection; Restore GitHub Backups covers bare mirrors and working clones.
  • Voice Memos Backups covers backup, transcription, recovery, and diarization on macOS.

Architecture

restic_backups/
  cli.py                 root command wiring and global options
  config.py              YAML loading and validation
  jobs/
    cli.py               unified job commands and job-first TUI
    workflow.py          type dispatch and common snapshot execution
  generic/
    cli.py               generic restic command definitions
    local.py             local repository destruction
    sops.py              SOPS decryption
    repository.py        repository resolution and managed paths
    restic.py            restic execution and archive policy
    s3.py                permanent repository destruction
  github_repository/
    cli.py               GitHub repository commands and TUI
    workflow.py          Git, GitHub export, and snapshot updates
  voice_memos/
    cli.py               Voice Memos command definitions
    pipeline.py          transcription and diarization processing
    workflow.py          backup, restore, and recording lookup
    parallel.py          worker process orchestration
    dashboard.py         live Textual dashboard

The root TUI and job command route every configured type through the common job dispatcher. Type-specific modules prepare source data; generic restic modules resolve destinations and execute restic.

Private data boundary

Managed artifacts use:

data/<storage-id>/<repository-path>/<job-id>/

This path is relative to the selected configuration file. It does not constrain backup sources; commands may pass absolute source paths outside the repository. Everything below data/ is ignored.

GitHub repository jobs use data/github-repositories/<job-id>/ because their managed source workspace is shared by every selected restic destination.

Warning

Commit config.sops.yaml only while encrypted. Never commit credentials, recordings, transcripts, summaries, caches, restores, or restic data.