> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kolaria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Install the Kolaria GitHub App, pick repositories, and generate content from commits, merged pull requests, and releases

The GitHub integration reads activity from your repositories so Kolaria can generate changelogs, blog posts, and social posts. It can also **publish a draft pull request** back to the repository. Since August 2026 the primary way to connect is the **Kolaria GitHub App**. The older personal access token flow still works and is labelled **Legacy** in the dashboard.

## What Kolaria accesses

The GitHub App asks for:

* Read access to repository metadata, branches, and releases
* Write access to Contents and Pull requests, so Kolaria can open a draft pull request with the generated Markdown
* Write access to Issues, so Kolaria can add and remove status reactions on PR conversation comments through GitHub's issue-comment API. Mentions on ordinary issues are ignored.
* Webhook events for the repositories you choose
* Access only to the repositories you grant during installation

From that access Kolaria reads commits on the branch you track, merged pull requests, and published releases. Publishing a changelog or blog post creates a branch and a **draft** pull request — it does not merge or change repository settings.

<Note>
  Existing installations stay read-only until you accept the updated permissions on GitHub. Reconnecting a repository in Kolaria does not grant write access. Open **Integrations**, then **GitHub**, and choose **Review permissions on GitHub**.
</Note>

## Install the GitHub App

<Steps>
  <Step title="Open the GitHub page">
    In the dashboard, open **Settings**, then **Integrations**, then **GitHub**. You can also use the sidebar: **Integrations**, then the **GitHub** card. Click **Connect GitHub** (or press `C`).
  </Step>

  <Step title="Install on GitHub">
    The dialog explains the permissions above. Click **Install on GitHub**. You are sent to GitHub to choose a personal account or organization and to select **All repositories** or specific repositories. You can change this selection later from GitHub.

    <Note>
      If your Kolaria login is not yet linked to a GitHub account, Kolaria first sends you through GitHub sign-in, then continues to the App installation. You must be an admin of the GitHub account that owns the installation.
    </Note>
  </Step>

  <Step title="Pick repositories in Kolaria">
    Back in Kolaria, the **Select repositories** dialog opens automatically. It lists the repositories the installation can see, grouped by GitHub account. Tick the ones Kolaria should track and click save. Each selected repository becomes its own integration with changelog, blog post, and X post outputs enabled by default.
  </Step>

  <Step title="Add more accounts or repositories">
    Connected accounts appear as cards on the GitHub page. Use **Add repositories** on the page header or on an account card to change the selection, or start another installation to add a second GitHub account or organization.
  </Step>
</Steps>

## Set up a webhook (optional)

Webhooks let event triggers react to activity in real time. Kolaria generates a secret per repository, but you register the webhook on GitHub yourself:

1. Open the repository's page in Kolaria (click it from the GitHub page). The **Webhook** section shows the **Payload URL** and a **Secret**. Click the copy buttons.
2. Open **Settings**, then **Webhooks**, in the repository on GitHub and click **Add webhook**.
3. Paste the Payload URL, set **Content type** to `application/json`, and paste the secret.
4. Choose **Let me select individual events** and tick **Pushes**, **Releases**, and **Pull requests**.
5. Save. GitHub sends a `ping` event, which Kolaria answers with `Pong! Webhook configured successfully`.

The Payload URL has the form `https://app.kolaria.com/api/webhooks/github/{organizationId}/{integrationId}/{repositoryId}`. Kolaria verifies every delivery with the `X-Hub-Signature-256` header. You can regenerate the secret from the same section; update GitHub afterwards.

<Note>
  Without a webhook you can still generate content manually or on a schedule. Webhooks are only needed for [event-based automation](/automation/event-based).
</Note>

### Webhook events Kolaria processes

| GitHub event | What Kolaria does |
| - | - |
| `push` | Records commits pushed to the repository's default branch on GitHub. Pushes to other branches are ignored. |
| `release` | Records published releases and their notes. |
| `pull_request` | Records pull requests when they are **closed and merged**. Other actions are ignored. |
| anything else | Logged as ignored and answered with `200`. |

Every delivery is written to the organization's webhook log (**Settings**, then **Logs**). See [Webhooks Overview](/api/webhooks/overview) for response shapes.

## Mention Kolaria on pull requests

Mention Kolaria in a pull request comment, for example `@usenotra shorten the intro`. Mentions on ordinary issues are ignored without a reply or reaction. You do not need the exact App name: `@usenotra`, `@notra`, `@notra-ai`, and `@notrabot` all work. Kolaria reacts to your PR comment with 👀 while it works and swaps that for 👍 when it is done or 👎 when a safeguard declines the request. The reply and any commits come from the App's bot account.

When your comment is about how something reads ("the intro feels heavy", "show me a punchier opening"), Kolaria does not commit. It answers with a GitHub suggestion on the lines in question, and you apply it with **Commit suggestion**, or reply "shorter please" to get another take. Nothing on the branch changes until you accept one. Applying that suggestion, or a commit Kolaria makes itself, updates the matching Kolaria post. Kolaria commits directly when you tell it to ("apply it", "go ahead"), for plain corrections such as a typo or a wrong number, and for changes a suggestion cannot express, like edits across several files.

Kolaria writes in the brand voice the post was created with, and it reads the pull request description, so an edit from a comment sounds like the rest of the post.

After a commit, Kolaria replies right at the lines it edited under **Files changed**, with a before and after of the text and a link to the commit. When you wrote in a review thread, the reply stays in that thread. You can also mention Kolaria in a review comment on specific lines, or reply inside its thread ("shorter please"); it reads the earlier comments, so you do not have to repeat yourself.

* **Questions** get an answer in the thread. Nothing is committed.
* **Change requests** on a pull request Kolaria published commit the file onto that pull request, then synchronize the Kolaria post. The same happens when you apply a GitHub suggestion on that file.
* **Separate pull request**: say so in the comment ("open a separate PR") and Kolaria commits to a new branch and opens a draft pull request stacked on the one you commented on. The Kolaria post stays as it is. Once you merge that pull request into the published one, the next change picks it up.

Kolaria only acts on comments from members of your Kolaria organization whose login is linked to the commenting GitHub account. Other mentions are ignored and logged as skipped. Mentions inside code, quotes, or email addresses do not count.

Comments written by bots never start Kolaria, so a review from Greptile or CodeRabbit is left alone. To have Kolaria act on such a finding, reply inside the bot's review thread and mention Kolaria ("@notra fix this"). Kolaria reads the finding you replied to and follows your instruction.

### What a mention costs

Every mention runs an agent, so it is billed. Each plan includes a budget of pull request credits that only the bot spends:

| Plan | Included |
| - | - |
| Free | \$1, once |
| Starter | \$10 per month |
| Growth | \$15 per month |
| Scale | \$25 per month |

A mention is charged what its model calls cost, the same way AI credits are charged elsewhere in Kolaria. The remaining budget is shown under **Settings → Billing → Usage**. Once it is used up, mentions keep working and fall back to your AI credits, so a busy week does not stop the bot. When both are empty, Kolaria replies once that there is nothing left to spend and does nothing else; top up credits or move to a bigger plan, then mention it again.

One organization can start 20 mention runs in 10 minutes. Above that Kolaria replies that it paused and when to try again. Nothing is billed for a mention it refuses.

If the GitHub App is missing a permission, Kolaria does not retry. It replies once with the permission that is missing and a link to the installation settings, and the mention shows up as failed in the webhook log. Mention Kolaria again after an owner has approved the permissions.

Kolaria acknowledges a mention only after a durable workflow has been queued. Redis is required to prevent competing deliveries from running the same mention. If processing is interrupted after it starts, Kolaria records a failure instead of automatically repeating potentially completed GitHub writes. Check the pull request for a commit or reply before posting a new mention. Redelivering the interrupted delivery does not start another agent run.

Kolaria never commits to the repository's default branch. Ask for a separate pull request instead. Fork pull requests support answers only, including when a separate pull request is requested.

Mentions edit content, not code. Kolaria commits Markdown, MDX, and text files, plus the JSON, YAML, TOML, or CSV data that sits next to them, such as a docs navigation file. Code, scripts, dot files and folders like `.github`, and build or tool configuration such as `package.json` or `vercel.json` are never committed, whatever the comment asks for. If you ask for one of those, Kolaria tells you it needs a regular commit.

The same goes for active content inside Markdown and MDX. A mention can reword a page with unchanged standalone imports, but files containing exports or complex imports require a regular commit. It cannot add new `import` or `export` lines, MDX expressions such as `{props.value}` (plain literals like `width={600}` are fine), `<script>` tags, iframes, `javascript:` links, or inline event handlers. Code samples in fenced blocks are fine. If any sandbox change is blocked, the entire patch is rejected. Deleting a linked publication is not supported.

If someone pushed to the pull request after Kolaria's last commit, Kolaria continues from the file on the pull request, so edits made by hand are kept and flow back into the Kolaria post with the next change.

Mentions arrive through the GitHub App, not the per-repository webhook above. The App must be subscribed to the **Issue comment**, **Pull request review comment**, and **Pull request** events. GitHub uses **Issue comment** for ordinary PR conversation comments too, so this subscription is required even though Kolaria ignores issues. Closing or merging a pull request Kolaria published marks that publication as closed so the post can be published again.

## Legacy: personal access token

If you cannot install the GitHub App, click **Use the legacy flow** at the bottom of the GitHub page.

1. Enter the repository as `https://github.com/owner/repo`, `git@github.com:owner/repo.git`, or `owner/repo`. Kolaria detects the default branch; you can change it.
2. Public repositories work without a token. For private repositories, expand **Personal Access Token** and paste a classic token with the `repo` scope, or a fine-grained token with read access to the repository. Accepted prefixes are `ghp_`, `github_pat_`, `gho_`, `ghu_`, `ghs_`, and `ghr_`.
3. Save. Kolaria opens the **Setup Webhook** dialog with the Payload URL and secret described above.

Legacy integrations are listed under **Personal access token (Legacy)** on the GitHub page. You can update the token from the legacy integration's card if it expires.

The same flow is available from the API with `POST /v1/integrations/github`, which accepts `owner`, `repo`, an optional `branch`, and an optional `token`. The GitHub App flow is dashboard-only.

## Managing a repository

Open a repository from the GitHub page to:

* **Edit**: change the display name, owner, repository, or default branch, and enable or disable the integration. A disabled integration generates no outputs and rejects webhook deliveries with `403`.
* **Schedules** and **Events**: see and create the [schedules](/automation/scheduled) and [event triggers](/automation/event-based) that use this repository.
* **Webhook**: copy the Payload URL, reveal or regenerate the secret, and jump to GitHub's webhook settings.

To remove a GitHub account, click **Disconnect** on its card. This disables the installation and every repository that belongs to it in Kolaria. Uninstall the app from GitHub as well to revoke access there.

<Warning>
  Removing a repository or disconnecting an account stops every schedule and event trigger attached to those repositories.
</Warning>

## Troubleshooting

| Message in Kolaria | What it means |
| - | - |
| GitHub write access needed / GitHub still shows read-only | The GitHub App installation has not accepted Contents and Pull requests **write**. Reconnecting the repository is not enough. On GitHub, open the installation and accept any pending permission request. In Kolaria: **Settings → Integrations → GitHub**, then **Review permissions on GitHub**. |
| The GitHub installation was cancelled. | You left the GitHub install screen. Start again from **Connect GitHub**. |
| The GitHub installation link expired. | Install links are valid for 30 minutes. Start again. |
| You need to be an admin of the GitHub account that owns this installation. | Ask an owner of the GitHub organization to run the installation, or make you admin. |
| GitHub needs to be reconnected to authorize organization access. | Kolaria re-runs GitHub sign-in to read organization membership, then finishes the install. |
| Too many GitHub connection attempts. | Wait a moment and try again. |

**Webhook not firing**: check **Recent Deliveries** on the GitHub webhook. A `401` means the secret does not match; copy it again from Kolaria. A `403` means the integration is disabled in Kolaria. A `404` means the repository was removed from Kolaria.

**No content generated**: confirm there was activity on the tracked branch in the lookback window, and that the schedule or trigger includes this repository.

## Best practices

<Steps>
  <Step title="Use descriptive PR titles">
    Kolaria reads pull request titles and descriptions. "Add dark mode to the dashboard" produces better content than "fix stuff".
  </Step>

  <Step title="Write release notes">
    Release bodies are used as source material for changelogs and announcements.
  </Step>

  <Step title="Ship from the default branch">
    Webhook pushes are only recorded on the repository's default branch on GitHub. The branch you set in Kolaria controls which branch activity is read from when content is generated.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Set up automation" icon="wand-magic-sparkles" href="/automation/overview">
    Schedules and event triggers for GitHub activity
  </Card>

  <Card title="Webhooks overview" icon="webhook" href="/api/webhooks/overview">
    Request verification, responses, and logs
  </Card>
</CardGroup>