Skip to main content

​
The simplest integration

If you don’t want to write any code — install the pull/story GitHub App on your repo and you’re done. Every PR gets a pull story automatically within ~60 seconds of being opened, with the link posted to the PR description. This cookbook covers the manual knobs: when auto-gen runs, when it doesn’t, and how to combine it with the REST API.

​
Install

github.com/apps/pull-story/installations/new Pick specific repos or All repositories. You can change this later from your GitHub settings.

​
Default behavior

EventAuto-generates?
PR opened (ready for review)✅ yes
PR opened as draft❌ skipped (toggle in dashboard)
Draft marked ready✅ yes
New commit pushed to PR✅ yes (regenerates on new head SHA)
PR closed or mergedno change

​
Toggle per repo

pullstory.com/dashboard → Automations → per-repo switches:
  • Auto-generate on PR open
  • Auto-generate on new commits
  • Skip drafts
  • Post link in PR description

​
Combine with the API

The GitHub App and the REST API share the same minute quota and the same cache. So:
  • A PR auto-generated by the App is already at pullstory.com/pr/{owner}/{repo}/{number}
  • Calling POST /v1/stories on that PR returns the cached story immediately — no re-generation, no minutes charged
  • Passing force: true forces a fresh generation and charges fresh minutes
// Check if a PR already has a story (useful in CI)
const res = await fetch(
  `https://pullstory.com/api/v1/stories?owner=acme&repo=billing&number=482&limit=1`,
  { headers: { Authorization: `Bearer ${process.env.PULLSTORY_API_KEY}` } },
);
const { data } = await res.json();
if (data[0]?.status === "ready") {
  console.log("Story ready:", data[0].url);
}

​
Webhook for story-ready (coming soon)

Instead of polling, subscribe to a webhook that fires when a story completes. Configure at pullstory.com/dashboard/webhooks.

​
Next

Claude Code

Skip the “open PR, wait for App” loop entirely.

Embed stories

Drop auto-generated pull stories into docs, changelogs, blog posts.