Erik Newhard

Guide: Easy Set Up For Automatic Roam Backups

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


  • 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

  1. Go to Settings, then Secrets.
  2. Click New secret.
  3. Under Name, type or copy/paste ROAMRESEARCH_DATABASE
  4. Under Value, put in the name of your Roam database (which you can find in your Roam's URL********* )
  5. Click Add secret.
  6. Repeat for the following names and values:
    <br>(Roam account email address)
    - ROAMRESEARCH_PASSWORD<br>(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

  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.

<pre><code class="language-yaml" id="backup_roam_in_github_main_yml"></code></pre>

Code source

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.

  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.<br>(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.

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 `/`