Connect GitHub to AltoRank

GitHub authenticates with a fine-grained token with contents:write on one repository that you create and can revoke yourself. Connecting it makes GitHub an available destination — it does not give AltoRank permission to publish. That still takes a person approving the draft.

What you will need

Repo owner
The user or organisation, e.g. acme
Repository
The repository the site builds from
Branch
The branch your host deploys, usually main
Content directory
Where posts live, e.g. src/content/blog. Files are only ever written inside it
GitHub token
Scoped to that one repository with Contents: read and write
Public URL of your blog
Optional
Read from your sitemap when you connect; used to record where each post will appear
Trailing slash
Optional
Whether your post URLs end in /. Read from your sitemap, not guessed
Also accepted by the connector, not asked for by the form (3)
extension
md (default) or mdx
frontmatterDefaults
Extra keys added to every post, e.g. an author or a layout
committer
Name and email on the commit. Defaults to the token’s owner

These keys are in the connection schema and work when a connection is created from your own code or on a self-hosted install. They are listed so the docs match the code, not because you need them.

Setup

  1. 1 Create the credential in GitHub

    Go to GitHub → Settings → Developer settings → Fine-grained personal access tokens. AltoRank never asks for your GitHub login: you create a scoped credential there and paste it here, so revoking our access later is one click on your side and does not change how you sign in.

  2. 2 Add the connection in AltoRank

    In your workspace, open Integrations, choose GitHub, and fill in repo owner, repository, branch, content directory, github token. The connection is tested before it saves, so a wrong value fails here rather than silently at publish time.

  3. 3 Approve an article

    Nothing publishes on connection. Open a draft, read the fact-check verdict, and approve it. Only then does AltoRank call GitHub. You can also turn on automatic publishing for the workspace, which ships after a hold you can veto; either way there is no agent route around the approval.

What approving does in GitHub

On approve
Commits one Markdown file to the branch at {content directory}/{slug}.md with YAML front matter (title, description, publishDate, tags, ogImage) and the body converted from HTML. Your host’s build deploys it; a commit is not a deploy, so the article is checked for going live afterwards.
On unpublish
Deletes that file in a second commit. The post disappears on the next build, which is the closest a static site has to unpublishing.

The file it commits

One Markdown file per article, written only inside the content directory you named. Any front matter defaults you configured come first, then the article’s own keys. The commit message is content: publish "<title>", or content: update "<title>" when the file already exists, and content: unpublish <path> when it is deleted. 

<content directory>/<slug>.md

---
title: "The article title"
description: "The approved meta description"
publishDate: "2026-09-05"
tags: ["only", "when set"]
ogImage: "https://... only when the article has a featured image"
---

The body, converted from the approved HTML to Markdown.

Whether those keys match your collection schema is something your own build answers. The editor’s “copy as Markdown” renders the identical file, so you can drop one into the repository and run the build before connecting anything.

Worth knowing

  • Listed in the picker as “Git / static site”. It is the answer for Astro, Hugo, Jekyll, Next and anything else that builds from Markdown in a repository; there is no plugin to install and nothing runs on your site.
  • Connecting checks two things: that the token can see the branch, and that the public blog URL actually responds. A wrong URL used to produce articles marked live at addresses that never existed.
  • GitHub is the only provider today. Republishing an approved article updates the same file rather than creating a duplicate.

The adapter behind this page is apps/web/lib/cms/git.ts . If this page and that file disagree, the file is right and the page has a bug.

Common questions

Does AltoRank publish to GitHub automatically?

Only after a person approves the specific draft. Connecting GitHub removes the copy-and-paste step; it does not hand over the decision. The publish path requires an approval recorded under a person, by click or by the rule they set, and the MCP server exposes no publish tool, so this holds even when an AI agent is driving the product.

What GitHub credentials does AltoRank need?

Repo owner, Repository, Branch, Content directory, GitHub token, Public URL of your blog (optional), Trailing slash (optional). Fine-grained token with contents:write on one repository. Nothing else, and never your GitHub account password.

Can I publish to GitHub as a draft instead of live?

Not from AltoRank: the review happens here, before anything is sent, so approving is the act of publishing. On approve, Commits one Markdown file to the branch at {content directory}/{slug}.md with YAML front matter (title, description, publishDate, tags, ogImage) and the body converted from HTML. Your host’s build deploys it; a commit is not a deploy, so the article is checked for going live afterwards. If you want a staging destination, connect Notion as well and approve there first. Unpublishing is available afterwards: Deletes that file in a second commit. The post disappears on the next build, which is the closest a static site has to unpublishing.

Can I revoke access without breaking my site?

Yes. The credential is created in GitHub and revoked there, independently of your login. Revoking it stops AltoRank publishing and changes nothing else. Articles already published stay where they are: they are ordinary content on your platform, not embeds pointed at us.

Can I use GitHub on the self-hosted version?

Yes. Self-hosting is the same product under an open-source licence with no feature gates, so every connector works and your credentials never leave your own infrastructure. The adapter is apps/web/lib/cms/git.ts in the repository.

Add your domain All destinations

Be the site the assistant names.

Add a domain and the first draft is written while you watch. Every publish is your decision, a click on the draft or a rule you set and can hold, and you can read the source or self-host it free.

Add your domain Self-host it free

Add a domain, it sets up your workspace