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

# GitHub App

> Install once. Eligible PRs get pull stories automatically.

## Zero-setup pull stories

The pull/story GitHub App is the easiest way to use PR automation. Install it on a repo and eligible ready-for-review PR events can generate a pull story automatically. No API calls or scripts are required per PR.

The story link is posted back to the PR description after generation finishes.

<Frame>
  <img src="https://pullstory.com/brand/github-app-demo.png" alt="PR description with auto-generated pull story link" />
</Frame>

## Install

<Steps>
  <Step title="Click install">
    Visit [github.com/apps/pull-story/installations/new](https://github.com/apps/pull-story/installations/new).
  </Step>

  <Step title="Pick repos">
    Choose **All repositories** or a specific list. You can change this later from your GitHub settings.
  </Step>

  <Step title="Authorize">
    Click **Install & Authorize**. You'll be redirected to [pullstory.com/dashboard](https://pullstory.com/dashboard) where your installed repos will appear.
  </Step>
</Steps>

## What happens on each PR

<AccordionGroup>
  <Accordion title="PR opened">
    Pull/story fetches the diff, generates a pull story with diagrams, narration, and artifacts, and posts the link to the PR description.
  </Accordion>

  <Accordion title="New commits pushed">
    The story is regenerated automatically on new commits. The URL is **deterministic** so the link in the PR description keeps working — it always serves the latest version.
  </Accordion>

  <Accordion title="PR reopened / ready for review">
    If a draft PR is marked ready, a pull story is generated (drafts are skipped by default).
  </Accordion>

  <Accordion title="PR closed / merged">
    No changes. Existing pull stories remain accessible forever.
  </Accordion>
</AccordionGroup>

## Permissions required

The GitHub App asks for minimal permissions:

| Permission               | Why                                                   |
| ------------------------ | ----------------------------------------------------- |
| **Pull requests: read**  | To fetch the PR diff, commits, and metadata           |
| **Contents: read**       | To resolve file contents for the narration            |
| **Metadata: read**       | Standard for all GitHub Apps                          |
| **Pull requests: write** | To update the PR description with the pull story link |

The App **cannot** write code, push commits, merge PRs, or access any repo you didn't explicitly install it on.

## Turn off auto-generation

From [pullstory.com/dashboard](https://pullstory.com/dashboard) → **Automations**, toggle automatic generation for your account.

* **Auto-generate on PR open / new commits** — default on
* **Skip drafts** — drafts are skipped by default

## Combining App + API

The GitHub App and the REST API share the same minute quota. So:

* A PR auto-generated by the App counts against your monthly minutes
* The public REST API creates brief-based stories from caller-supplied code context
* PR automation and brief API generation are separate flows with separate story URLs

<Tip>
  If the GitHub App is installed on a repo, you don't need to call `POST /api/v1/stories` for that PR. Use the dashboard or push a new commit to drive PR automation.
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/integrations/claude-code">
    Combine the App with the Claude Code MCP for full automation.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/stories/create-story">
    On-demand generation via the REST API.
  </Card>
</CardGroup>