Guide: Easy Set Up For Automatic Roam Backups

Aug 10, 2020
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 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.
  1. In the Secrets settings, add your Roam database name, email, and password.
  1. 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

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

Step 2: Add Secrets settings

notion image
  1. Go to Settings, then Secrets.
  1. Click New secret.
  1. Under Name, type or copy/paste:
  1. 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)
  1. Repeat for the following names and values:
    1. ROAMRESEARCH_USER (Roam account email address)
      ROAMRESEARCH_PASSWORD (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

notion image
  1. Go to Actions (in the top bar, not in the settings)
  1. Click set up a workflow yourself →
  1. Leave alone the name main.yml
  1. Under Edit new file, delete the code and copy/paste the code below.
  1. Click Start commit, then Commit new file.
name: "Roam Research backup" on: push: branches: - main schedule: - cron: "0 * * * *" jobs: backup: runs-on: ubuntu-latest name: Backup timeout-minutes: 15 steps: - uses: actions/checkout@v2 - name: Set up Python 3.8 uses: actions/setup-python@v1 with: 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 env: ROAMRESEARCH_USER: ${{ secrets.ROAMRESEARCH_USER }} ROAMRESEARCH_PASSWORD: ${{ secrets.ROAMRESEARCH_PASSWORD }} ROAMRESEARCH_DATABASE: ${{ secrets.ROAMRESEARCH_DATABASE }} - name: Commit changes uses: elstudio/actions-js-build/commit@v3 with: commitMessage: Automated snapshot
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.
notion image
  1. To check the progress of the first run, go back to Actions.
  1. 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.)
  1. Under Roam Research backup, click Backup.
It will take a couple of minutes for the process to complete.
notion image
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: