Product workflow4 min readKeep one real product question in mind as you read.
A useful way through

Start with one real question and leave with a next step.

Start with the question in front of you, then use the guide to make the next decision easier.

Try saying

“I am trying to make this decision. What should I look at first?”

Start with context

Bring the smallest useful example.

Look for the signal

Separate what is known from what is assumed.

Take one step

Choose an action you can review.

GitHub Integration

What this connection is for

Choose the repos Specky can see, then send reviewable validation tests to a branch your team can inspect.

How your data reaches Specky

Specky pulls from GitHub on a schedule. A sync runs when you open your workspace if the data is stale, and you can also start one by hand from the integration card.

Before you start

  • Personal Access Token (Required) — Fine-grained PAT scoped to the repos you want Specky to read and write validation artifacts to.

Setup

Open Connect tools in the sidebar and find GitHub. Its card has two rows. Under Graph sync, click Connect to read your GitHub data into your Product Graph: a form asks for the credentials described below. Under Live tools in chat, click Connect to let chat read and act in GitHub live; you will be sent to GitHub to approve access. Specky never sees your password.

Recommended: install the Specky GitHub App

Use Connect to install the App into the GitHub account or organisation you want Specky to work with. GitHub lets you choose specific repositories. Specky then uses short-lived installation tokens and remembers a default repository and base branch for validation artifacts, issue sync, chat tools, and MCP.

If your workspace has not enabled the App yet, the button falls back to OAuth. Existing OAuth connections continue to work, but the App gives you clearer repository-scoped access.

OAuth fallback / personal token

If your administrator cannot install the App, use the OAuth fallback or a fine-grained personal access token with only the repositories Specky should access.

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Click "Generate new token"
  3. Give it a name like specky-integration
  4. Set expiration (90 days recommended)
  5. Under Repository access, select the repos you want to sync
  6. Under Permissions → Repository permissions, enable:
    • Issues: Read and write (required for syncing and pushing tickets)
    • Pull requests: Read and write (required to open optional draft PRs)
    • Contents: Read and write (required for validation branches and files)
    • Metadata: Read-only (required)
  7. Click "Generate token" and copy it

What Specky does with your token

  • Reads open/closed issues and their comments
  • Reads pull request descriptions, reviews, and comments
  • Imports this data as product graph nodes for AI analysis
  • Creates issues on your repo when you push tickets from Build → Generate Tickets
  • Creates or updates a specky/validation/... branch with a complete fake-door page, validation manifest, and README when you deliver a validation page to a repository
  • Optionally opens a draft pull request so engineering can review the copy before it reaches product traffic

Data synced

DataUsed for
IssuesFeature requests, bug reports, customer feedback
Pull RequestsEngineering activity, spec deviation detection
PR ReviewsTechnical context for PRD generation

Pushing tickets to GitHub

When you push tickets from Build → Generate Tickets, pick the Target Repository. The tickets are created as issues in that repo.

Putting a validation test in the repository

Publish a validation page from an experiment, then choose Create GitHub branch in the validation-page panel. Specky creates a reviewable specky/validation/<slug> branch containing a self-contained index.html, validation.json, and README. The CTA points back to the hosted Specky page so responses, attribution, and Product Graph links remain intact. You can also ask for a draft PR after the branch is created.

Copilot auto-PR (optional)

Add the specky label to your repo. When Specky pushes an issue with this label, GitHub Copilot coding agent can automatically pick it up and open a PR. Enable this in your repo under Settings → Copilot → Copilot coding agent.

After connecting

New GitHub items appear in Explore feedback alongside your other sources. You can search them, ask questions about them, and cite them in product work without opening another tab.

Disconnecting GitHub removes the connection and the signals it brought in.

Troubleshooting

  • Connected, but nothing appears. Open the GitHub card and run a sync by hand. If it errors, the card shows the reason.
  • "Upgrade to connect". Your plan caps how many integrations you can connect at once, and a few providers are Scale-only. Usage in the sidebar shows where you stand.
  • Credentials stopped working. Tokens expire and get revoked. Reconnect with a fresh one — your existing signals are kept.

See the GitHub integration page for what it's for and the questions people usually ask first, or the Integrations Overview for how integrations work in general.

Ready to apply this?

Start with your own product and keep the first read grounded. You'll create an account before the guided result so it can be saved to your workspace.

Try the guided start