GitHub

Rankturn can publish your articles straight into a GitHub repository as Markdown (.md) or Markdoc (.mdoc) files. Each article becomes a single file with a small block of details at the top (title, description, and so on), saved to the branch and folder you choose. This makes Rankturn a ready-to-use content source for git-based publishing tools such as Keystatic, Astro content collections, Next.js MDX blogs, Hugo, and similar static-site setups.

When you publish, Rankturn adds a new file (or updates the existing one) and marks the change with a [rankturn] label so it's easy to spot in your history.

For how this fits the broader two-way workflow, see Bidirectional Sync.

Connecting

1. Go to Settings → Integrations and find the GitHub card.
2. Click Connect to open the connection wizard.
3. Create a GitHub Personal Access Token (PAT):
   • Open github.com/settings/tokens/new.
   • Give it a name and select the repo scope (Rankturn needs read and write access to repository contents).
   • Generate the token and copy it — GitHub only shows it once.
4. Fill in the wizard fields:

5. Click Connect. Before saving, Rankturn tests the connection — it checks that the token works, that the repository and branch exist, and that the token can write (push) changes. If any check fails you'll see a specific message (see Troubleshooting).

Once connected, GitHub appears as a publishing destination when you publish or schedule an article.

Editing the connection. Click Edit Settings on the GitHub card to change the owner, repository, branch, directory, or file format. Leave the token field blank to keep the existing token — Rankturn only replaces it if you enter a new value.

Note on the token. A Personal Access Token grants write access to your repositories. Rankturn stores it encrypted; see Credentials & Security for details.

File Format

You choose one format per connection, which sets the file extension:

Every published file starts with a small block of details, followed by the article body in Markdown. That block includes the title, the meta description, the publish date, the author (when set), tags (when the article has them), the canonical URL (when set), and structured data (Schema.org) when it's been generated.

The article's slug isn't included in that block — instead it becomes the filename (your article is saved as your-slug.md / your-slug.mdoc). This keeps the output compatible with tools like Keystatic that don't expect a separate slug field. The keyword is intentionally left out for the same reason.

Bidirectional Sync

By default the GitHub integration is one-way: Rankturn pushes articles to your repo. Turning on Bidirectional Sync lets edits made in GitHub flow back into Rankturn, so your repository stays the source of truth even when collaborators edit files directly.

Enabling it. On the GitHub card, toggle Bidirectional Sync on. Rankturn then sets up an instant update notification on your repository, so every push you make notifies Rankturn right away. (Setting this up needs admin access to the repository's webhooks. The connection is secured behind the scenes.)

What happens on each push. When you push a change, Rankturn:

1. Confirms the notification genuinely came from your repository and ignores anything that doesn't check out.
2. Skips any change labelled [rankturn] — those are Rankturn's own publishes, so skipping them prevents an endless back-and-forth loop. If a push contains only Rankturn's own changes, it's ignored entirely.
3. Looks only at .md and .mdoc files inside the folder you chose; everything else is ignored.
4. For each changed file, matches it to an existing article and updates it, or creates a new article as a Draft if there's no match.

When the same article changed in both places. Rankturn keeps track of each synced article's latest version in GitHub. When a change comes in:

• If the file hasn't actually changed since the last sync, Rankturn skips it — no needless update.
• If the article was also edited in Rankturn since the last sync (a genuine conflict), the GitHub version wins — your repository is treated as the authoritative copy. The sync is marked as a conflict so you can see it happened.

Deleting a file won't delete the article. Removing a Markdown file from your repository does not delete the matching article in Rankturn. The removal is noted and skipped, so an accidental delete never destroys content in Rankturn.

Manual sync. You don't have to wait for a push. Click Sync from GitHub on the card to pull in every Markdown/Markdoc file currently in your chosen folder and match it against your articles in one pass. This is handy for the first import or after a batch of edits. Afterwards you'll see how many files synced and how many failed.

Disabling it. Toggle Bidirectional Sync off and Rankturn removes the update notification from GitHub and clears its stored details. (If you already removed it on GitHub's side, that's fine — Rankturn handles the missing case gracefully.)

Path Safety

The folder you enter is checked before any file is saved, which protects your repository from invalid or unsafe paths:

• Leading and trailing slashes and any surrounding spaces are removed.
• Only letters, numbers, hyphens (-), underscores (_), and forward slashes (/) are allowed — anything else is rejected.
• Folders containing .. or // are rejected, so files can never end up outside the folder you chose.

Unusual but valid characters in a slug are handled safely.

Troubleshooting

"Invalid GitHub token. Please check your Personal Access Token." — The token is wrong or expired. Generate a fresh PAT with the repo scope and reconnect.

"Repository … not found." — The owner or repository name is wrong. Enter the owner (username or organisation) and just the repository name, not the full URL.

"Branch '…' not found in repository." — The branch doesn't exist. Rankturn lists the available branches in the message so you can pick a valid one (or shows if the repository is empty).

"Your token does not have write access to this repository." — The token can read the repository but can't push to it. Recreate it with the repo scope so it has write (push) permission.

Bidirectional sync won't enable / "webhook permission" error — Setting up the update notification needs admin access to the repository's webhooks. Use a token (and account) that can manage webhooks on that repository.

Pushes aren't syncing back — Confirm Bidirectional Sync is on, that your edits are saved to the right branch and land inside the right folder, and that the files end in .md or .mdoc. Changes labelled [rankturn] are skipped by design. As a fallback, click Sync from GitHub to match things up manually.

An edit I made in Rankturn got overwritten — This is expected when the same article was also changed in GitHub: in a conflict, the GitHub version wins. Make the authoritative edit in the repository, or sync first and edit in Rankturn before your next push.

For more on how stored tokens and connection details are kept secure, see Credentials & Security.