Simple tool to back up all repos on a GitHub/Gitea account to a local folder.

hydrun CI Docker CI Go Version Go Reference Matrix Binary Downloads


Octarchive is a simple backup utility that clones all repos from a GitHub/Gitea account to a local folder for storage.

It enables you too …

  • Backup your work: In case your GitHub account is breached or gets banned, Octarchive ensures you always have a local copy available.
  • Mirror your account: If your internet connection is slow or GitHub is banned in your jurisdiction, you can use Octarchive and a web server to mirror your repos.
  • Automate processes: By exposing all of your repos to the filesystem, otherwise tedious processes such as bumping copyright dates or updating names become easy.



You can get the OCI image like so:

$ podman pull ghcr.io/pojntfx/octarchive


Static binaries are available on GitHub releases.

On Linux, you can install them like so:

$ curl -L -o /tmp/octarchive "https://github.com/pojntfx/octarchive/releases/latest/download/octarchive.linux-$(uname -m)"
$ sudo install /tmp/octarchive /usr/local/bin

On macOS, you can use the following:

$ curl -L -o /tmp/octarchive "https://github.com/pojntfx/octarchive/releases/latest/download/octarchive.darwin-$(uname -m)"
$ sudo install /tmp/octarchive /usr/local/bin

On Windows, the following should work (using PowerShell as administrator):

PS> Invoke-WebRequest https://github.com/pojntfx/octarchive/releases/latest/download/octarchive.windows-x86_64.exe -OutFile \Windows\System32\octarchive.exe

You can find binaries for more operating systems and architectures on GitHub releases.


1. Do a manual backup with octarchive

First, export your GitHub (or Gitea) API token like so:

$ export GITHUB_TOKEN='mygithubtoken'

If you’re using Gitea, also export your API endpoint like so:

$ export GITHUB_API='https://try.gitea.io/api/'

Now, start the manual backup, including all the repos of the organizations that you’re part of:

$ octarchive --orgs
{"level":"info","time":"2022-08-15T00:25:39+02:00","message":"Getting user"}
{"level":"info","time":"2022-08-15T00:25:40+02:00","message":"Getting organizations for user"}
# ...
Cloning   6% [========>                                                                                                                                                           ] (16/263, 7 repo/s) [1s:32s]{"level":"info","cloneURL":"https://github.com/pojntfx/dwm.git","filePath":"/home/pojntfx/.local/share/octarchive/var/lib/octarchive/data/1660518181/pojntfx/dwm","time":"2022-08-15T01:03:09+02:00","message":"Cloning repo"}
# ...

You should now find the repos in ${HOME}/.local/share/octarchive/var/lib/octarchive/data.

For more information, see the reference.

2. Schedule backups with systemd Timers

In most cases, you’ll want to schedule backups periodically; an excellent way to do so is to use systemd Timers. To schedule a weekly backup of all of your repos, run the following:

$ sudo tee /etc/systemd/system/octarchive.service<<'EOT'
Description=Octarchive backup

ExecStart=/usr/local/bin/octarchive --orgs

$ sudo tee /etc/systemd/system/octarchive.timer<<'EOT'
Description=Run Octarchive weekly


$ sudo systemctl daemon-reload
$ sudo systemctl enable octarchive.timer --now

Note that this will create a fresh directory every time you run the backup, which might fill up your disk space quite quickly; if you want to instead remove the old backup every time you do a new one, append --timestamp current to the ExecStart line of the service.

You should find the repos in /root/.local/share/octarchive/var/lib/octarchive/data.

For more information, see the reference.

🚀 That’s it! We hope you enjoy using Octarchive.


Command Line Arguments

$ octarchive --help
Usage of octarchive:
  -api string
        GitHub/Gitea API endpoint to use (can also be set using the GITHUB_API env variable) (default "https://api.github.com/")
  -concurrency int
        Maximum amount of repositories to clone concurrently (default 20)
  -dst string
        Base directory to clone repos into (default "/home/pojntfx/.local/share/octarchive/var/lib/octarchive/data")
        Clear timestamp directory before starting to clone
        Also clone repos of all orgs that the user is part of
  -timestamp string
        Timestamp to use as the directory for this clone session (default "1660513831")
  -token string
        GitHub/Gitea API access token (can also be set using the GITHUB_TOKEN env variable)
  -verbose int
        Verbosity level (0 is disabled, default is info, 7 is trace) (default 5)

Environment Variables

You can set the following environment variables, which correspond to the values that can be set using the following flags:

Environment Variable Flag


To all the rest of the authors who worked on the dependencies used: Thanks a lot!


To contribute, please use the GitHub flow and follow our Code of Conduct.

To build and start a development version of Octarchive locally, run the following:

$ git clone https://github.com/pojntfx/octarchive.git
$ cd octarchive
$ make depend
$ make && sudo make install
$ export GITHUB_TOKEN='mygithubtoken'
$ octarchive

Have any questions or need help? Chat with us on Matrix!


Octarchive (c) 2022 Felicitas Pojtinger and contributors

SPDX-License-Identifier: AGPL-3.0


View Github