GitHub setup

The GitHub connector delivers each article as a pull request. BirchSeek writes an MDX file with frontmatter matched to your content schema, commits it to a new branch, and opens a PR against your base branch. You review and merge.

What BirchSeek does in your repo

For each published article:

1. Reads your base branch’s current commit.
2. Creates a branch named birchseek/{slug} from it. BirchSeek never commits to your base branch.
3. Commits one file at your configured path template - default src/content/blog/{slug}.mdx.
4. Opens a pull request titled Add article: <article title> from that branch into your base branch.

Publishing is idempotent: if a delivery is retried, BirchSeek finds its existing branch and PR instead of creating duplicates.

Step 1 - install the GitHub App

There is no token to create, copy, or renew. BirchSeek authenticates as a GitHub App and mints a short-lived credential for each publish.

1. In onboarding (or Connectors → GitHub later), press Connect GitHub.

2. GitHub asks which account to install on - your personal account or an organization. Organization installs may need an owner to approve; GitHub tells you inline and BirchSeek shows the request as pending until they do.

3. Under Repository access, choose Only select repositories and pick your content repo. You can add or remove repositories later from GitHub without touching BirchSeek.

4. Approve the two permissions BirchSeek asks for:

   • Contents: Read and write - to create the branch and commit the article file.
   • Pull requests: Read and write - to open the PR and track its merge status.

   Metadata: Read is added automatically by GitHub.

Branches, commits and pull requests are made with the app’s own installation credential rather than a human account, so BirchSeek’s activity is always distinguishable from yours in the repository history. The commit itself carries the commit-author name and email you set on the connector.

If you uninstall the app, suspend it, or remove the repository from the installation, BirchSeek detects it - immediately by webhook, and within six hours by reconciliation either way - marks the connector failing, and emails you. Publishing resumes when you reconnect.

Step 2 - configure the connection

Pick the installation and repository, then configure:

Setting	Meaning	Default
Repository	The owner/repo articles are published to	-
Base branch	Where PRs target	the repo’s default branch
Path template	Where the article file lands	src/content/blog/{slug}.mdx
Branch template	Branch name per article	birchseek/{slug}
Frontmatter preset	How article fields map to frontmatter keys	Astro content collections
Commit author	Name/email on the commit	BirchSeek, bot@birchseek.com

Frontmatter mapping

The Astro content collections preset maps article fields to the conventional keys out of the box:

---
title: "How to choose a CRM in 2026"
description: "A buyer's guide built on what the data actually says."
publishDate: "2026-07-17"
tags: [crm, buying-guides]
faq:
  - question: "How many CRM vendors should I evaluate?"
    answer: "Recent buyer research suggests most teams now shortlist two or fewer…"
---

Every key is remappable (publishDate → date, description → summary), and you can pin static frontmatter such as author: "Jane" or layout: post onto every article. If your schema has no faq field, unmap it and the pairs are appended to the body as a rendered FAQ section.

Frontmatter never carries the citations, on any path - the keys above are the complete list. The claim-to-source mapping rides in the body instead.

The ## Sources block in the committed file

Below the closing ---, the article body ends by default with a ## Sources heading and a numbered list pairing each verified claim with the page it was checked against:

## Sources

1. 38% of small teams replace their first CRM within two years — [Small-team CRM replacement rates](https://example.com/research/crm-replacement-2026)

It is part of the file you merge, so your content collection renders it like any other section - no schema field to add, and nothing for you to append. BirchSeek composes it once before any connector sees it, which is why every connector publishing to your own site writes the same block. (A syndicated copy to dev.to, Hashnode or Medium carries the same block, and the canonical link back to your page besides. That copy is not covered by the project setting: those three platforms have no citation field of their own, so the body is the only place the evidence can travel.) The block is on by default, and there is no switch for it in the dashboard: it is a project setting called append_sources_section, kept for a repo whose layout prints its own reference list. The only way to change it today is PATCH /v1/projects/{id} carrying the whole settings object, because that request replaces the object rather than merging into it.

The block lists only claims that came back verified, and it prints no quote. Each line says one thing: this claim was checked against this source.

The pull request body

The PR is where the evidence goes, because it is the one surface only your reviewer reads. Its body opens with a summary line BirchSeek really emits:

- **Verified sources:** 6 claims checked against the page they cite

and then repeats the same numbered list under its own ## Sources heading, with a note under each claim saying how the fetch confirmed it. A blockquote is text the fetch located on that page, matched word for word - with case set aside and every run of characters that are not letters or digits collapsed to a space, so up-to-date matches a page that writes up to date, and a $ or a % is folded away on both sides. Anything else is stated as what it is - the claim’s own wording found on the page, where the writer asserted no excerpt to quote; wording overlap rather than a word-for-word match; a model judging the page to support the claim; or a check whose method was not recorded - so a reviewer never reads an asserted excerpt as a found one. Claims that could not be verified are counted here too, and named as unverified.

That per-claim note is deliberately not in the committed file: only one of the four ways a claim passes proves the quote is on the page as written - and in a second of them there is no quote on the record to print - so the caveat has to travel with the quote. The pull request carries both; the published page carries the link.

If the project has the Sources block switched off, the PR body says so and tells the reviewer that its own list is the only place the claim-to-source mapping appears.

Step 3 - check access

Setup ends with an access check: BirchSeek verifies push access and pull-request reads without creating a branch, file, or pull request. The first write happens on your first approved publish.

Security notes

• The connector holds no secret of yours. It stores your installation id and the settings above, and no credential at all. There is no long-lived token in our database to leak, because there is no long-lived token.
• Each publish mints a fresh installation token from GitHub, scoped to your installation and good for one hour. It is used for that publish and never stored.
• Its write access covers contents and pull requests, in the repositories you picked and no others.
• You end access from GitHub, not from here: remove the repository from the installation, or uninstall the App. The next publish fails and the connector is marked failing.

Troubleshooting

• 404 on connect - the installation no longer includes that repository. Open the app’s settings on GitHub and grant it, then re-test.
• 403 on test - the installation is suspended, or an organization owner has not approved it yet.
• Connector says “reconnect” - installations moved from personal access tokens to the GitHub App; press Connect GitHub once to re-authorize.
• PR opened against the wrong branch - the base branch setting defaults to the repo’s default branch; change it in the connector settings.
• Branch already exists - a previous publish attempt for the same slug; BirchSeek reuses it. If it’s stale, delete the branch and retry.