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.
- Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Click "Generate new token"
- Give it a name like
specky-integration - Set expiration (90 days recommended)
- Under Repository access, select the repos you want to sync
- 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)
- 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
| Data | Used for |
|---|---|
| Issues | Feature requests, bug reports, customer feedback |
| Pull Requests | Engineering activity, spec deviation detection |
| PR Reviews | Technical 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.