Installation

Riffle is an Atlassian Forge app that syncs Confluence pages with a GitHub repository as Markdown files. This guide covers installation, configuration, and connecting GitHub.

Prerequisites

• A Confluence Cloud instance (Riffle does not support Confluence Data Center or Server)
• A GitHub repository where synced Markdown files will live
• Space admin permissions in the Confluence space you want to sync
• A GitHub Personal Access Token with repo scope (or fine-grained token with contents: write)

Step 1: Install the Forge App

From the Atlassian Marketplace (coming soon)

Once listed, you’ll be able to install Riffle directly from the Marketplace.

From source (development)

If you’re running Riffle from source:

# Clone the repo
git clone https://github.com/trusthumankind/riffle.git
cd riffle

# Build the converter
cd packages/converter
npm install
npm run build

# Deploy the Forge app
cd ../forge-app
npm install
forge deploy

# Install on your Confluence site
forge install --site your-site.atlassian.net --product confluence

After installation, Riffle appears in Space Settings → Integrations → Riffle Sync for every space on the site.

Step 2: Configure a Space

1. Navigate to the Confluence space you want to sync
2. Go to Space settings → Integrations → Riffle Sync
3. Fill in the configuration:

Field	Description	Example
GitHub Repository	owner/repo format	trusthumankind/riffle
Target Directory	Path in the repo where Markdown files are stored	docs/riffle
GitHub Personal Access Token	A token with repo or contents:write scope	ghp_...
Sync Enabled	Toggle to enable/disable sync for this space	On

4. Click Save Settings
5. Click Test Connection to verify GitHub access

Step 3: Connect GitHub Webhooks

For bidirectional sync (GitHub → Confluence), you need to set up a GitHub webhook:

1. In the Riffle settings UI, enter a Webhook Secret (any strong random string) and save it
2. Copy the Webhook URL displayed in the settings
3. In GitHub, go to your repository → Settings → Webhooks → Add webhook
4. Configure:
   • Payload URL: the webhook URL from step 2
   • Content type: application/json
   • Secret: the same string from step 1
   • Events: select “Just the push event”
   • Active: checked
5. Click Add webhook

GitHub will send a test ping — check that it shows a green checkmark in the webhook delivery log.

Step 4: Verify

Confluence → GitHub

1. Create or edit a page in the synced Confluence space
2. Check your GitHub repository — a new Markdown file should appear (or an existing one should be updated)
3. The commit will be authored by Riffle Sync with the tag [riffle-sync] in the message

GitHub → Confluence

1. Edit a Markdown file in the target directory and push to main
2. Check the corresponding Confluence page — it should be updated
3. If the Markdown file has no confluence_id in its front matter, a new page will be created

Upgrading

When a new version of Riffle is available:

cd packages/converter
npm install
npm run build
cd ../forge-app
npm install
forge deploy

If the update adds new permission scopes, you’ll also need:

forge install --upgrade

Uninstalling

forge uninstall --site your-site.atlassian.net --product confluence

This removes the app from your Confluence site. Synced files in GitHub and pages in Confluence are not affected.