What Notra accesses
The GitHub App asks for:- Read access to repository metadata, branches and releases
- Write access to Contents and Pull requests, so Notra can open a draft pull request with the generated Markdown
- Write access to Issues, so Notra can add and remove status reactions on PR conversation comments through GitHub’s issue-comment API. Notra ignores mentions on ordinary issues.
- Webhook events for the repositories you choose
- Access only to the repositories you grant during installation
Existing installations stay read-only until you accept the updated permissions on GitHub, because reconnecting a repository in Notra doesn’t grant write access. Open Integrations, then GitHub and choose Review permissions on GitHub.
Install the GitHub App
1
Open the GitHub page
In the dashboard, open Settings, then Integrations, then GitHub. You can also go through Integrations in the sidebar and then the GitHub card. Click Connect GitHub or press
C.2
Install on GitHub
The dialog explains the permissions above, and from there you click Install on GitHub. GitHub asks you to choose a personal account or organization and to select All repositories or specific repositories, and you can change this selection later from GitHub.
If your Notra login isn’t linked to a GitHub account yet, Notra first sends you through GitHub sign-in and then continues to the App installation. You must be an admin of the GitHub account that owns the installation.
3
Pick repositories in Notra
Back in Notra, the Select repositories dialog opens automatically and lists the repositories the installation can see, grouped by GitHub account. Tick the ones Notra should track and click save. Each selected repository becomes its own integration with changelog, blog post and X post outputs enabled by default.
4
Add more accounts or repositories
Connected accounts appear as cards on the GitHub page. Use Add repositories on the page header or on an account card to change the selection, or start another installation to add a second GitHub account or organization.
Set up a webhook (optional)
Webhooks let event triggers react to activity in real time. Notra generates a secret per repository, but you register the webhook on GitHub yourself:- Open the repository’s page in Notra by clicking it on the GitHub page, then use the copy buttons in the Webhook section to copy the Payload URL and the Secret.
- Open Settings, then Webhooks, in the repository on GitHub and click Add webhook.
- Paste the Payload URL, set Content type to
application/jsonand paste the secret. - Choose Let me select individual events and tick Pushes, Releases and Pull requests.
- Save the webhook, and GitHub sends a
pingevent that Notra answers withPong! Webhook configured successfully.
https://app.usenotra.com/api/webhooks/github/{organizationId}/{integrationId}/{repositoryId}. Notra verifies every delivery with the X-Hub-Signature-256 header. You can regenerate the secret from the same section, and then you need to update it on GitHub.
Without a webhook you can still generate content manually or on a schedule, since you only need webhooks for event-based automation.
Webhook events Notra processes
Notra writes every delivery to the organization’s webhook log (Settings, then Logs). See Webhooks overview for response shapes.
Mention Notra on pull requests
Mention Notra in a pull request comment, for example@usenotra shorten the intro, and note that Notra ignores mentions on ordinary issues without a reply or reaction. You don’t need the exact App name, because @usenotra, @notra, @notra-ai and @notrabot all work. Notra reacts to your PR comment with 👀 while it works and swaps that for 👍 when it is done or 👎 when a safeguard declines the request. The reply and any commits come from the App’s bot account.
When your comment is about how something reads, such as “the intro feels heavy” or “show me a punchier opening”, Notra doesn’t commit and instead answers with a GitHub suggestion on those lines that you apply with Commit suggestion. To get another take, reply “shorter please”, and nothing on the branch changes until you accept one. Applying that suggestion, or a commit Notra makes itself, updates the matching Notra post. Notra commits directly when you tell it to (“apply it”, “go ahead”), for plain corrections such as a typo or a wrong number and for changes a suggestion can’t express, like edits across several files.
Notra writes in the brand voice the post was created with, and it reads the pull request description, so an edit from a comment sounds like the rest of the post.
After a commit, Notra replies right at the lines it edited under Files changed, with a before and after of the text and a link to the commit, and when you wrote in a review thread, the reply stays in that thread. You can also mention Notra in a review comment on specific lines or reply inside its thread (“shorter please”), and because it reads the earlier comments, you don’t have to repeat yourself.
- Questions get an answer in the thread, and Notra commits nothing.
- Change requests on a pull request Notra published commit the file onto that pull request and then synchronize the Notra post, which also happens when you apply a GitHub suggestion on that file.
- Separate pull request: say so in the comment (“open a separate PR”) and Notra commits to a new branch and opens a draft pull request stacked on the one you commented on. The Notra post stays as it is until you merge that pull request into the published one, and then the next change picks it up.
What a mention costs
Every mention runs an agent, so Notra bills it, and each plan includes a budget of pull request credits that only the bot spends:
Notra charges a mention what its model calls cost, the same way it charges AI credits elsewhere, and shows the remaining budget under Settings → Billing → Usage. Once the budget is used up, mentions keep working and fall back to your AI credits, so a busy week doesn’t stop the bot. When both are empty, Notra replies once that there is nothing left to spend and does nothing else, so top up credits or move to a bigger plan and then mention it again.
One organization can start 20 mention runs in 10 minutes, and above that Notra replies that it paused and says when to try again. Notra bills nothing for a mention it refuses.
If the GitHub App is missing a permission, Notra doesn’t retry. It replies once with the missing permission and a link to the installation settings, and the mention shows up as failed in the webhook log, so mention Notra again after an owner has approved the permissions.
Notra acknowledges a mention only after it queues a durable workflow, and it needs Redis to stop competing deliveries from running the same mention. If processing stops partway through, Notra records a failure instead of repeating GitHub writes that may already have completed, so check the pull request for a commit or reply before posting a new mention. Redelivering the interrupted delivery doesn’t start another agent run.
Notra never commits to the repository’s default branch, so ask for a separate pull request instead. Fork pull requests support answers only, even when you request a separate pull request.
Mentions edit content rather than code, so Notra commits Markdown, MDX and text files plus the JSON, YAML, TOML or CSV data that sits next to them, such as a docs navigation file. Whatever the comment asks for, Notra never commits code, scripts, dot files and folders like
.github or build and tool configuration such as package.json or vercel.json. If you ask for one of those, Notra tells you it needs a regular commit.
The same goes for active content inside Markdown and MDX. A mention can reword a page with unchanged standalone imports, but files containing exports or complex imports require a regular commit. It can’t add new import or export lines, MDX expressions such as {props.value} (plain literals like width={600} are fine), <script> tags, iframes, javascript: links or inline event handlers. Code samples in fenced blocks are fine, but if the sandbox blocks any change, Notra rejects the entire patch. Mentions can’t delete a linked publication.
If someone pushed to the pull request after Notra’s last commit, Notra continues from the file on the pull request, so edits made by hand are kept and flow back into the Notra post with the next change.
Mentions arrive through the GitHub App rather than the per-repository webhook above, so the App must subscribe to the Issue comment, Pull request review comment and Pull request events. GitHub uses Issue comment for ordinary PR conversation comments too, so you need this subscription even though Notra ignores issues. Closing or merging a pull request Notra published marks that publication as closed so the post can be published again.
Legacy: personal access token
If you can’t install the GitHub App, click Use the legacy flow at the bottom of the GitHub page.- Enter the repository as
https://github.com/owner/repo,git@github.com:owner/repo.gitorowner/repo. Notra detects the default branch, and you can change it. - Public repositories work without a token, but for private repositories expand Personal Access Token and paste a classic token with the
reposcope, or a fine-grained token with read access to the repository. Accepted prefixes areghp_,github_pat_,gho_,ghu_,ghs_andghr_. - Save, and Notra opens the Setup Webhook dialog with the Payload URL and secret described above.
Managing a repository
Open a repository from the GitHub page to:- Edit: change the display name, owner, repository or default branch, and enable or disable the integration. A disabled integration generates no outputs and rejects webhook deliveries with
403. - Schedules and Events: see and create the schedules and event triggers that use this repository.
- Webhook: copy the Payload URL, reveal or regenerate the secret and jump to GitHub’s webhook settings.
Troubleshooting
Webhook not firing. Check Recent Deliveries on the GitHub webhook. A
401 means the secret doesn’t match, so copy it again from Notra. A 403 means the integration is disabled in Notra, and a 404 means someone removed the repository from Notra.
No content generated. Confirm there was activity on the tracked branch in the lookback window, and that the schedule or trigger includes this repository.
Best practices
1
Use descriptive PR titles
Notra reads pull request titles and descriptions, so “Add dark mode to the dashboard” produces better content than “fix stuff”.
2
Write release notes
Notra uses release bodies as source material for changelogs and announcements.
3
Ship from the default branch
Notra only records webhook pushes on the repository’s default branch on GitHub, while the branch you set in Notra controls which branch Notra reads activity from when it generates content.
Next steps
Set up automation
Schedules and event triggers for GitHub activity
Webhooks overview
Request verification, responses and logs