- 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.)
- Create a GitHub repository for your Roam backup.
- In the Secrets settings, add your Roam database name, email, and password.
- 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
- Once you have signed into GitHub, click New under Repositories.
- Type in a repository name, such as roam-backup
- Select Private. (If you select Public, anyone can access your backups. You may consider this if your Roam database is public.)
- Check Initialize this repository with a README.
- Click Create repository.
Step 2: Add Secrets settings
- Go to Settings, then Secrets.
- Click New secret.
- Under Name, type or copy/paste (with the clipboard icon)<br><span class="copy-to-clipboard">ROAMRESEARCH_DATABASE</span>
- Under Value, put in the name of your Roam graph.<br>(You can find a list of your graph names on the Graphs and Settings page)
- Repeat for the following names and values:
- <span class="copy-to-clipboard">ROAMRESEARCH_USER</span><br>(Roam account email address)
- <span class="copy-to-clipboard">ROAMRESEARCH_PASSWORD</span><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
- Go to Actions (in the top bar, not in the settings)
- Click set up a workflow yourself →
- Leave alone the name main.yml
- Under Edit new file, delete the code and copy/paste the code below.
- Click Start commit, then Commit new file.
<pre class="copy-to-clipboard"><code class="language-yaml" id="backup_roam_in_github_main_yml"></code></pre>
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.
- To check the progress of the first run, go back to Actions.
- 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.)
- 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 <code>/</code>
If you have any issues getting this to work, let me know at firstname.lastname@example.org
If possible, please attach the log archive of a failed backup job: