Guide: Easy Set Up For Automatic Roam Backups

Set up automatic backups for Roam to GitHub with "roam-to-git"

Guide: Easy Set Up For Automatic Roam Backups
The Roam backup being run in GitHub

The credit for this backup method goes to Matthieu Bizien. You can view his code and readme, as well as instructions for local backups, at

Important notice:

This guide is for Matthieu Bizien's roam-to-git backup. As of 2021-01-30, I have coded my own automatic backup solution called roam2github. It has support for EDN backups (full-fidelity Roam graph images), support for multiple graph backups in a single GitHub repo, unlimited minutes of runtime, extensive error-logging, and active support from me to help you get it working. You can find exact instructions for my Roam2Github backup here:

The following guide below is linked from roam-to-git's README, so I will leave it up. However, I consider it outdated, and will only provide support for Roam2Github.


  • A Roam Research account and database (also called "graph")
  • A GitHub account (You can sign up for free if you don't already have one.)

Steps Overview:

  1. Create a GitHub repository for your Roam backup.
  2. In the Secrets settings, add your Roam database name, email, and password.
  3. Create an action and copy/paste some code.


  • Your Roam database will be backed up into GitHub automatically every hour.

Step 1: Create a GitHub repository
  1. Once you have signed into GitHub, click New under Repositories.
  2. Type in a repository name, such as roam-backup
  3. Select Private. (If you select Public, anyone can access your backups. You may consider this if your Roam database is public.)
  4. Check Initialize this repository with a README.
  5. Click Create repository.

Step 2: Add Secrets settings secrets.gif
  1. Go to Settings, then Secrets.
  2. Click New secret.
  3. Under Name, type or copy/paste:

  4. Under Value, put in the name of your Roam graph. (You can find a list of your graph names on the Graphs and Settings page)
  5. Repeat for the following names and values:

    (Roam account email address)

    (Roam account password)

Note: This will not work if you used a Google login for your Roam account. In that case, you'd need to log out of Roam, and click the Forgot your password on the login page to reset it.

Step 3: Add Action actions.gif
  1. Go to Actions (in the top bar, not in the settings)
  2. Click set up a workflow yourself →
  3. Leave alone the name main.yml
  4. Under Edit new file, delete the code and copy/paste the code below.
  5. Click Start commit, then Commit new file.
name: "Roam Research backup"

      - main
    -   cron: "0 * * * *"

    runs-on: ubuntu-latest
    name: Backup
    timeout-minutes: 15
      -   uses: actions/checkout@v2
      -   name: Set up Python 3.8
          uses: actions/setup-python@v1
            python-version: 3.8

      -   name: Setup dependencies
          run: |
            pip install git+
      -   name: Run backup
          run: roam-to-git --skip-git . --formats json markdown formatted edn

      -   name: Commit changes
          uses: elstudio/actions-js-build/commit@v3
            commitMessage: Automated snapshot

Code source

Note: As of October 1st, the default branch name for new repos was changed from "master" to "main". The branch name here needs to match your repo's branch name.

Note: cron: 0 * * * controls how often the backup action runs. This is set to hourly, which is allowed in GitHub's free plan. If you know how to change cron settings, you can customize how often it runs.

And that's it!

The action should start running within several seconds.

Check the progress

To check the progress of the first run, go back to Actions. check running actions.gif
  1. To check the progress of the first run, go back to Actions.
  2. Under All Workflows, click the 3 dots on the first result, then click View workflow file.(If there are no results, try refreshing the page after several seconds.)
  3. Under Roam Research backup, click Backup.

It will take a couple of minutes for the process to complete. showresults.gif

When it's done, check that the backup completed successfully, by going to Code. There should be 3 new directories:

  • formatted (markdown files that re-create Roam's structure within GitHub, with links and backlinks)
  • json (the main json file which you can import back into Roam)
  • markdown (raw text of each page)

It will only update new or edited files as needed. Because of GitHub's version control, you can also see past edits under History.

Possible causes for failure:

  • using a Google account
  • having a page title that is too long
  • starting a page title with a backslash /

If you have any issues getting this to work, try my own backup solution: