Separate Repositories Setup
Separate repositories keep your writing in a vault repository and the site implementation in a site repository. A push to the vault starts a deployment of the site.
This guide walks through the GitHub and Cloudflare screens, including where to click and what to enter. It takes about 20–30 minutes.
You need:
- A GitHub account
- Node.js
^20.19.0or>=22.12.0 - A Cloudflare account
- A terminal
GitHub sometimes moves or renames settings. This page matches the UI as of November 2026. If you cannot find an item, use the search box in Settings.
Do the GitHub setup in a browser. The GitHub mobile app does not include Developer settings.
Official sample: site and vault — repositories.riebeckite.dev
my-vault/ my-site/
├── index.md ├── app/
├── notes/ ├── riebeckite.config.ts
└── assets/ ├── package.json
├── wrangler.jsonc
└── .github/workflows/publish.yml
1. Create the site locally
In a terminal, go to the folder where the site should live and run:
npx create-riebeckite my-site \
--preset starter \
--github-actions \
--content-repository OWNER/my-vault \
--site-repository OWNER/my-site
cd my-site
npm install
Replace OWNER with your GitHub username or organization. The my-vault and my-site names must match the repositories you create in step 2.
To use the interactive prompts instead, run npx create-riebeckite my-site and answer:
| Prompt | Answer |
|---|---|
| Where will you write content? | Separate GitHub repository |
| Content repository | OWNER/my-vault |
| Site repository | OWNER/my-site |
| Install dependencies now? | Yes or No |
The CLI also asks about a template and optional feature packs. Keep the defaults unless you have a preference.
When content lives in a separate repository, the CLI does not ask Set up deployment?. It adds the GitHub Actions deployment setup automatically.
github/notify-site.yml does nothing yet. You will move it to the vault in step 6.
Once you know the public URL, set it in site.baseUrl in riebeckite.config.ts. If you use a custom domain, also set routes in wrangler.jsonc. Follow step 2 of Integrated Setup. For a first publish on workers.dev, the generated settings work as they are.
2. Create two repositories on GitHub
Select + in the top right of GitHub → New repository, and create two repositories:
| Repository | Purpose | Visibility |
|---|---|---|
my-site |
Site implementation | Private |
my-vault |
Content | Private or public |
Do not select a README, .gitignore, or license under Initialize this repository with. Leave both repositories empty so the first local push goes through.
Do not push the site yet. Pushing before the Cloudflare secret is registered makes the first deployment fail. You will push the site in step 5.
Next, create the vault content. If you already have an Obsidian vault, use that folder as it is.
my-vault/
├── index.md
├── notes/
└── assets/
A minimal index.md needs frontmatter:
---
publish: true
title: Home
---
# Home
In the vault folder, run:
git init
git branch -M main
git add .
git commit -m "Add vault"
git remote add origin https://github.com/OWNER/my-vault.git
git push -u origin main
Empty folders are not tracked by Git, so index.md alone is fine at first. The vault can stay private. Step 3 sets up the token the site uses to read it.
3. Set up the GitHub App and secrets
To tell the site about a vault push, a workflow in the vault sends a notification to the site. This guide uses a GitHub App.
3-1. Create the GitHub App
- Profile picture in the top right → Settings.
- Developer settings at the bottom of the left sidebar.
- GitHub Apps → New GitHub App.
- Fill in the form as follows.
| Field | Value |
|---|---|
| GitHub App name | A unique name (for example, riebeckite-notify-OWNER) |
| Homepage URL | https://github.com/OWNER/my-site |
| Webhook → Active | Clear the checkbox |
| Repository permissions → Contents | Read and write |
| Where can this GitHub App be installed? | Only on this account |
- Click Create GitHub App.
The App ID appears at the top of the app settings page. Note it for later. It is not the Client ID.
If the repositories belong to an organization, create the app under the organization's Settings → Developer settings → GitHub Apps.
3-2. Create a private key
- In the app settings, open Credentials → Key pairs in the left sidebar.
- Click New key. GitHub downloads a
.pemprivate key. You can download it only once. - On the older UI, the labels are Private keys → Generate a private key.
3-3. Install the app on the site repository
- In the app settings, click Install App in the left sidebar.
- Click Install next to
OWNER. - Select Only select repositories and choose only
my-site. - Click Install.
Do not install the app on the vault repository.
3-4. Add the secrets to the vault
Open the vault repository, then go to Settings → Secrets and variables → Actions → New repository secret and add:
| Name | Secret |
|---|---|
RIEBECKITE_APP_ID |
The App ID from 3-1 |
RIEBECKITE_APP_PRIVATE_KEY |
The contents of the .pem file |
Paste the whole file, from -----BEGIN ... PRIVATE KEY----- to -----END ... PRIVATE KEY-----.
The notification token goes in the vault repository. The token that reads the vault goes in the site repository. It is easy to mix them up.
3-5. Let the site read a private vault
If the vault is private or internal, the site repository needs one more secret. Skip this section for a public vault.
- Profile picture → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
- Set Token name to something like
riebeckite-content-read. - Choose an Expiration.
- Choose the vault owner under Resource owner.
- Repository access → Only select repositories →
my-vault. - Permissions → Repository permissions → Contents → Read-only.
- Click Generate token and copy the token.
- In the site repository, go to Settings → Secrets and variables → Actions → New repository secret and add
RIEBECKITE_CONTENT_READ_TOKEN.
3-6. Use a personal access token instead
To notify the site without a GitHub App, add SITE_DISPATCH_TOKEN to the vault repository. Limit the token to the site repository and give it Contents: Read and write. Follow the steps in 3-5, but choose my-site and Read and write.
4. Configure Cloudflare
4-1. Copy the account ID
- Sign in to the Cloudflare dashboard.
- Open Workers & Pages.
- Account Details on the right shows the Account ID. Copy it.
You can also use Copy account ID in the profile menu.
4-2. Create an API token
- Profile picture → My Profile.
- API Tokens → Create Token.
- Choose Create Custom Token.
- Add these three permissions.
| Scope | Permission | Level |
|---|---|---|
| Account | Workers Scripts | Edit |
| Zone | Workers Routes | Edit |
| Zone | Zone | Read |
- Under Zone Resources, choose the zone for your custom domain. If you have not decided yet, All zones is fine.
- Continue to summary → Create Token.
- Copy the token. You cannot see it again after closing the page.
4-3. Add them to the site repository
In the site repository, go to Settings → Secrets and variables → Actions:
- Secrets tab → New repository secret:
CLOUDFLARE_API_TOKENwith the token from 4-2. - Variables tab → New repository variable:
CLOUDFLARE_ACCOUNT_IDwith the account ID from 4-1.
4-4. Set the public URL
For a workers.dev URL, you can leave the settings as they are. For a custom domain, follow step 2 of Integrated Setup to set routes in wrangler.jsonc and site.baseUrl in riebeckite.config.ts.
5. Push the site
Clone the content repository into content/ for the local check (or generate with --clone-content). Until content/ exists, check and build fail with "Could not find the content directory":
cd my-site
git clone https://github.com/OWNER/my-vault.git content
npm exec riebeckite check
npm exec riebeckite build
A dist/ folder means the build succeeded. Do not commit dist/, node_modules/, or content/.
Push the site repository:
git init
git branch -M main
git add .
git commit -m "Add site"
git remote add origin https://github.com/OWNER/my-site.git
git push -u origin main
Open the Actions tab in the site repository and confirm that Deploy to Cloudflare Workers succeeds. The first run takes a few minutes.
After the first deployment, the workflow creates a
publication-statebranch to store publication state. Do not delete it.
6. Add the notification workflow and test
In the vault repository:
- Add file → Create new file.
- Enter
.github/workflows/notify-site.ymlas the file name. Typing/creates folders. - Paste the contents of
my-site/github/notify-site.ymlfrom your local copy. - Commit changes... → Commit changes.
This commit is a push to main, so the notification workflow runs for the first time. In the vault repository's Actions tab, confirm that Notify Riebeckite site succeeds.
Then open the site repository's Actions tab and confirm that Deploy to Cloudflare Workers starts with content-updated and succeeds. Open the public URL. If the content of the vault's index.md appears, the setup is complete.
From then on, every Markdown push to the vault runs the same flow.
If something fails
| Symptom | What to check |
|---|---|
| Notify Riebeckite site does not appear in the vault's Actions | The file is at .github/workflows/notify-site.yml. The vault's default branch is main. |
| Notify Riebeckite site fails | RIEBECKITE_APP_ID and RIEBECKITE_APP_PRIVATE_KEY exist in the vault. The App ID is not the Client ID. The private key includes the BEGIN and END lines. |
| The site's Actions do not start | The app is installed on my-site. Its Contents permission is Read and write. With a PAT, SITE_DISPATCH_TOKEN exists in the vault. |
| The site's checkout fails | For a private vault, RIEBECKITE_CONTENT_READ_TOKEN exists in the site. Its Contents permission is Read-only. |
| The Cloudflare deployment fails | Check the permissions of CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. |
| The page does not change | The site's Actions succeeded. Wait a few minutes for Cloudflare to update. |
Which notification method?
| Method | Setup | Lifetime | Best for |
|---|---|---|---|
| GitHub App | Create an App and install it | Minutes per run | Recommended default |
| Fine-grained PAT | Create one token | Long-lived | A quick trial |
| Schedule polling | Add a cron trigger | None | A vault that changes infrequently |
Riebeckite's generated workflow supports the GitHub App and PAT fallback. Schedule polling is not generated because it delays publication and consumes runs.
Next
Powered by Riebeckite