Connect GitHub
For organisation admins. Connects your Speclr organisation to GitHub once, so project teams can hand stories over to repositories and GitHub Issues.
Updated
Use a dedicated machine account
- Clear authorshipEvery pull request, issue and comment Speclr creates appears under the account you connect.
- Survives people leavingA personal account takes all hand-overs down with it when its owner leaves.
- Own request budgetGitHub limits requests per account. A machine account keeps Speclr's status reads for all projects apart from anyone's own work.
Create the account and invite it to your organisation
Sign up a GitHub account such as
speclr-bot-acmewith a team mailbox. Invite it to your GitHub organisation and give it write access to the repositories your projects use.- Two-factor authentication on, recovery codes stored with the team
- Role "Write" on each repository, not organisation owner
- Write access to the GitHub Projects your teams use as their ticket system
Approve Speclr in your organisation
If your GitHub organisation restricts OAuth app access, Speclr reaches only its public resources until an organisation owner approves it once. Private repositories and projects stay invisible to Speclr without the approval.
The approval happens on GitHub's authorisation screen, under "Organization access": an owner chooses "Grant" next to the organisation. Anyone else, the machine account included, chooses "Request", and the owners are notified. An owner then approves Speclr under the organisation's Settings › Third-party Access › OAuth app policy, with "Review" and "Grant access".
Connect in Speclr, signed in as the machine account
Open Organisation settings › Integrations › Discover and choose Connect on GitHub. Only organisation admins see the integrations. When GitHub asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups. GitHub's authorisation screen names the app "Speclr by speclr-dev".
Back in Speclr, the connection appears under Yours and names the account it acts as. Check that it is the machine account.
Check the permissions
Speclr requests the GitHub OAuth scopes
repo project read:org. With them, the account needs:- Repositories
- read and write
- Issues
- read and write
- Pull requests
- read and write
- Projects
- read and write
- Organisations
- read, to offer them as allowed owners
Optional: allowed owners
Limit project teams to repositories of chosen owners, e.g. acme-studio. Targets outside the list receive nothing.
Reconnect or disconnect
Reconnect when the connection shows "Needs reconnect", as the same machine account. Another account first names the affected projects.
Disconnecting names them too. Targets and links stay; status turns unknown.
Troubleshooting
- Wrong account connected: reconnect as the machine account.
- A repository is missing: check the organisation approval, the account’s access and the allowed owners.
- Authorisation cancelled or failed: nothing was connected. Start again from Discover.
