Connect GitHub Issues
Connect GitHub to a project with a fine-grained token so a theme can be pushed into a repository as an issue, with its evidence and quotes.
Connect GitHub and every theme gets a Create GitHub issue button that opens the case in whichever repository you pick.
Before you begin
- Role: project Editor or Lead. A workspace Admin is a lead on every project.
- In GitHub: the repositories you want issues in, with Issues enabled on each.
- To hand: a fine-grained personal access token granted to those repositories.
- Time: five minutes.
What Adduce sends
One issue per theme, on your click, and nothing else. The body is GitHub-flavoured markdown, sent as written.
| In the issue | What it is |
|---|---|
| Title | The theme's name, trimmed to 256 characters |
| Opening quote | The verdict — recommended, monitor, or not needed — and the reasoning behind it |
| Summary line | Evidence and source counts, strength as a percentage, and sentiment |
| Quotes | Up to five pieces of evidence, each with who said it and a link to it |
| Related findings | Each finding's title and its confidence |
| Footer | A link back to the theme in Adduce |
No labels, assignees, milestones or projects are set. GitHub has no attachment object, so the link back to the theme lives in that footer rather than in a sidebar.
Permissions the token needs
Use a fine-grained token, granted to the repositories you want and nothing else.
| Permission | Why |
|---|---|
| Issues: Read and write | Create the issue |
| Repository access on each target repository | So the repository appears in the picker at all |
Adduce reads your account name once, to name the connection, and lists the repositories the token can reach. It never reads your code, your existing issues or your pull requests.
Steps
In GitHub, open Settings → Developer settings → Fine-grained personal access tokens and create a token. Grant it the target repositories, with Issues: Read and write. Copy it; GitHub will not show it again.
In Adduce, open the project, choose Sources, and scroll past the sources list to Issue trackers.
On the GitHub card, paste the token into Personal access token and choose Connect GitHub. Adduce calls GitHub with the token before it stores anything; a token GitHub refuses is reported under the field and nothing is saved.
Open a theme and choose Create GitHub issue.
Pick a Repository and choose Create issue. The repository you chose is remembered in this browser, so the next theme opens on it.
The button becomes the repository and issue number, and opens the issue in GitHub. If it could not be created, the button reads Retry GitHub issue instead.
When Adduce sends
Only when you click. There is no schedule and no automatic push. A theme that changes later does not update its issue, and closing the issue in GitHub does not change the theme.
Disconnect or replace credentials
On the GitHub card choose Disconnect. The stored token is deleted and the create-issue button disappears from every theme in the project; issues already in GitHub are untouched. To rotate a token, disconnect and connect again.
If it did not work
Why is a repository missing from the picker?
Three causes, in order of likelihood: the token was never granted that repository; the repository is archived; or Issues are turned off on it. The picker also stops at 500 repositories. Regrant the token in GitHub, then disconnect and connect again so the new grant is used.
Why did creating the issue fail when the connection is fine?
The token can see the repository but cannot write issues to it, or GitHub is rate limiting the account. Adduce keeps the connection healthy in both cases, because neither means the token is dead. Check Issues: Read and write on that repository, then choose Retry GitHub issue.
Why was the token rejected when I chose Connect GitHub?
GitHub answered with a refusal, which means the token has expired, been revoked, or was pasted incompletely. Fine-grained tokens expire; create a fresh one and paste it again.
What's next
Connect Jira
Connect Jira Cloud to a project, choose the project and issue type new issues land in, and push a theme into your backlog in one click.
Set up outbound webhooks
Register an HTTPS endpoint, pick the events you want, and receive signed JSON from Adduce when themes change or a brief is published.