Help

How to use Speclr

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.
  1. Create the account and invite it to your organisation

    Sign up a GitHub account such as speclr-bot-acme with 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
  2. 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".

  3. 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.

  4. 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.