---
title: "GitHub"
url: "/help/buuk/github"
updated: "2026-10-25T16:58:19.085Z"
---
# GitHub

Connect GitHub and your repository starts feeding the help center. Releases become changelog material, markdown files become draft articles, and pushes that touch docs file suggestions for you to review.

Open **Integrations** and pick **GitHub**. Depending on how this deployment is configured, the card connects with one of:

- **OAuth **— the standard authorization flow against your GitHub account, when the deployment has a GitHub OAuth app configured.
- **GitHub App **— one installation for your organization, with repositories chosen from GitHub’s side. Buuk authenticates with short-lived installation tokens and renews them on every sync.
- **Personal access token **— the fallback shown when the deployment has no platform OAuth app configured. One token with repo access so markdown, releases, and specs can be read.

Only editors can connect an integration, and disconnecting is available from the same card.

## Step by step — OAuth

1. **Press Connect on the GitHub card**
   Buuk opens github.com in the same tab. Use a browser session that is signed in where you expect — GitHub always asks you to pick the account, which is your chance to get the right one.

2. **Pick the GitHub account that can see the repository**
   The account selector lists every account signed in on the device. Choose the account with access to the repository your help articles should follow — the repos Buuk can list are exactly the ones that account can reach.

3. **Approve the authorization prompt**
   The prompt lists the access Buuk requests: repository contents (including private repositories your account can read) and profile details. Press **Authorize**.

4. **Back in Buuk: choose the repository to follow**
   Buuk lists the repositories the credential can reach. Pick the one whose releases and markdown should feed the help center, optionally adjust the include/exclude path filters in the same dialog, and save. The README stays excluded unless you allow it.

5. **Let the first sync run**
   Buuk imports the markdown it finds into the appropriate collections, stores repo files as searchable context, and checks for releases and OpenAPI specs — usually within a minute on fresh repositories.

6. **Work the suggestions**
   Open [**Suggestions**](./suggested-updates) to review what arrived: draft changelog entries, updates to affected articles, and new pages from repository docs.

## Step by step — personal access token

This path appears when the deployment has no GitHub OAuth app configured. The card shows a token field instead of a redirect.

1. **Create the token on github.com**
   Sign in to github.com, open the profile photo menu at the top right, and go to **Settings**.
   
   In the left sidebar choose **Developer settings** at the bottom.
   
   Choose **Personal access tokens** — **Tokens (classic)** for the simple route, or fine-grained tokens if your organization prefers them. Press **Generate new token (classic)**.

2. **Give it the scopes Buuk needs**
   For a classic token tick **repo** — that covers reading markdown files and releases. Fine-grained tokens only need read access to Contents and Metadata for the specific repository.
   
   Set a sensible expiry. The token sits on the connection until you replace it.

3. **Copy and paste**
   Press Generate, copy the token (it starts with `ghp_` or `github_pat_`), and paste it into the Buuk field. Tokens are shown once — if you lose it, generate a new one and reconnect.
   
   Press Connect with token. Buuk verifies the token against GitHub right away, so a wrong or expired token fails on the spot instead of at the first sync.

## If your organization blocks third-party access

**GitHub says “Access restricted” on the authorize page**

Your organization limits which third-party applications can read its repositories. A member can press **Request access** on that page and an organization owner approves the app under **Organization settings → Third-party Access**. Until then, connecting personal repositories still works.

## What it reads

On each sync, Buuk pulls from the linked repository’s default branch:

- Markdown files, filtered by an include and exclude path config you can change. The README stays excluded until you explicitly allow it.
- Releases — the most recent ten, with tag, name, and release notes.
- OpenAPI or Swagger specs in preferred locations. Repo-root specs stay opt-in by default, so an internal openapi.json is not published by accident.
- Pushes that add or modify any of those paths — synced right away and filed as suggestions.

## What it creates

- A changelog entry generated from each release, plus a suggestion to add it to What’s new.
- Release-impact suggestions on the articles a release touched, so docs catch up with what shipped.
- An update suggestion for every push that changes a doc or spec path, traced to the exact file.
- Versioned OpenAPI snapshots tagged with the branch head commit, so the API reference keeps its history.

> [!NOTE]
> Nothing publishes itself. Changelog entries and doc updates are suggestions until an owner or editor accepts and publishes them.

## Plan

Starter holds two integration slots — GitHub plus one support source. Growth connects the full catalog. See [Plans and billing](./plans-and-billing).

## Troubleshooting

**A sync failed but the card still shows connected**

That is intentional. GitHub rate limits, secondary rate limits, and transient 5xx responses are treated as temporary, so the connection is not marked broken and the next sync retries.

**A markdown file I edited in the repo did not become a suggestion**

Only the default branch is watched, and the path has to pass your include and exclude filters. README.md is stricter still: it is skipped unless you allowed it in the path config.

## Related

- The catalog at a glance: [Integrations overview](./connect-integrations).
- Where the suggestions land: [Suggested updates](./suggested-updates).
- One thing specs feed directly: [Import an OpenAPI spec](./import-openapi).
- Publish decisions for changelog entries: [Changelog](./changelog).
- Slot and plan limits: [Plans and billing](./plans-and-billing).