GitHub PRs
Overview
Section titled “Overview”A GitHub PR trigger starts documentation work from pull request activity in the repositories you monitor. Choose whether Promptless runs when a PR opens, gets its first approval, merges, or receives new commits. To ask for documentation on one PR, mention @promptless in it.
When an event matches your trigger, Promptless reads the full pull request. That includes the title and description, the code diff, review comments, and every commit, including commits added after the PR opened. When a reviewer requests changes, Promptless reads both the feedback and the commits that address it. If the change needs a documentation update, Promptless creates documentation suggestions.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization, to connect GitHub and edit the Configuration page.
- The GitHub organization that holds the repositories you want to monitor, connected to Promptless. Promptless can’t save a GitHub PR trigger until it is. If the organization isn’t connected yet, connect it first.
Connect GitHub
Section titled “Connect GitHub”Skip this section if the organization already has a card on the Integrations page.
You need an admin role in your Promptless organization to start a GitHub connection. GitHub then asks you to authorize the Promptless GitHub App with your GitHub account. The connection completes only if that account administers the organization or account you connect. For a GitHub organization, that’s an organization owner. For a personal account, it’s the account owner.
On GitHub Enterprise Server, or on GitHub Enterprise Cloud when a policy blocks third-party apps, connect through a custom GitHub App. See GitHub Enterprise integration.
-
In the Promptless dashboard, open the Integrations page.
-
Select Connect GitHub.
-
In GitHub, select the organization to install Promptless into.
-
Select the repositories Promptless can access. These are typically your source code repositories and, if your docs live in GitHub, your documentation repository.
-
On the Integrations page, confirm that the organization appears on its own card.
The connection link stays valid for one hour. If it expires before you finish, start the connection again from the Integrations page.
Some GitHub organizations require an owner’s approval to install a third-party app. If yours does and you aren’t an owner, GitHub asks you to request approval. To connect in that case:
-
Complete GitHub’s approval request flow. The GitHub card on the Integrations page shows Waiting on an organization owner while the request is open.
-
Ask a GitHub organization owner to approve the Promptless GitHub App in the organization’s Third-party Access settings.
-
After the owner approves, confirm that the organization appears on its own card. Promptless connects the approved installation automatically. To check right away, select Check for approval on the card.
If GitHub can’t reuse the approved installation, uninstall the Promptless GitHub App in GitHub, and connect again.
If your GitHub organization enforces an IP allow list, GitHub blocks requests from Promptless until an owner allows them. See Organization IP allow lists.
Add a PR trigger
Section titled “Add a PR trigger”-
On the Configuration page, switch to YAML mode.
-
In the
triggerssection, add agithub_prtrigger with a match clause for the repositories you want to monitor:triggers:my-pr-trigger:trigger_type: github_prmatch:- repos:- acme/backend- acme/frontendtrigger_on:- opened # When PR opens- first_approval # After first approval- merge # When PR mergestrigger_directories:- src/ -
Save the configuration.
Each match clause takes these fields:
| Field | Required | Description |
|---|---|---|
repos | Yes | The repositories to monitor, in owner/repo format, or the literal all. A clause that lists updated needs an explicit list. |
trigger_on | Yes | One or more trigger modes: opened, first_approval, merge, or updated. |
trigger_directories | No | Only PRs that change files in these directories trigger documentation updates. See Limit a trigger to specific directories. |
repo_topics | No | Only repositories with at least one of these GitHub topics trigger documentation updates. See Limit a trigger to tagged repositories. |
A trigger runs when any of its match clauses matches. For every field, including repository exclusions and the base-branch and owner filters, see the Configuration Reference.
To catch up on pull requests that opened or merged before you configured the trigger, run a backfill from the saved trigger. Before you go live, review the first batch of backfilled suggestions to calibrate Promptless with your documentation style.
Choose trigger modes
Section titled “Choose trigger modes”List one or more trigger modes in each match clause’s trigger_on:
| Mode | trigger_on value | When Promptless runs | Choose it when |
|---|---|---|---|
| Opened | opened | Once, when the PR opens | You want documentation suggestions ready alongside the code changes, so reviewers can evaluate both. |
| First approval | first_approval | Once, on the PR’s first approval | You want documentation work to start after code review, so Promptless analyzes the reviewed changes. |
| Merge | merge | Once, when the PR merges | You want documentation only for changes that have landed. |
| Updated | updated | On every push to an open PR | You want an open PR re-reviewed as it changes. See Re-review open PRs on every push first. |
The first-approval mode triggers once per PR, on the first approval. Later approvals, including re-approvals after requested changes, don’t trigger more documentation updates.
Re-review open PRs on every push
Section titled “Re-review open PRs on every push”The updated mode re-reviews an open pull request each time someone pushes new commits to it. Promptless’s suggestions then stay current as the PR changes. It’s available for GitHub PR triggers only, and pushes start no work unless a match clause lists updated in trigger_on.
Each push starts a new review, so a PR with many incremental commits gets many reviews. Scope the clause tightly: name an explicit repos list, and narrow it further with trigger_directories.
Promptless skips pushes to draft PRs and to PRs that Promptless opened. A push from any other contributor, including an external or first-time contributor, starts a new review. On a push, an @promptless mention in the title or description doesn’t bypass these filters or start a review.
To turn updated on, add it to a clause’s trigger_on list. That clause must name an explicit repos list:
triggers: my-pr-trigger: trigger_type: github_pr match: - repos: - acme/backend - acme/frontend trigger_on: - opened # When PR opens - first_approval # After first approval - merge # When PR merges - updated # Re-review on each new push trigger_directories: - src/To re-review on each push without the other modes, give updated its own clause with an explicit repos list, scoped with trigger_directories:
triggers: docs-review-bot: trigger_type: github_pr match: - repos: - acme/docs trigger_on: - updated # Re-review on each new push trigger_directories: - docs/The explicit-repos requirement applies to each match clause, not to the whole trigger. One trigger can pair a repos: all clause for the other modes with a scoped updated clause:
triggers: my-pr-trigger: trigger_type: github_pr match: - repos: all # broad clause for one-time modes trigger_on: - opened - merge - repos: # scoped clause required for updated - acme/docs trigger_on: - updated trigger_directories: - docs/Limit which pull requests trigger a review
Section titled “Limit which pull requests trigger a review”Promptless checks each pull request event against these rules before it starts a review:
| Pull request | What Promptless does |
|---|---|
| A draft PR | Skips it until it’s marked ready for review. An @promptless mention in the title, description, or a comment still starts work. |
| A PR that Promptless opened | Skips it. |
A PR that changes only dot-directories, such as .github/, .circleci/, or .beads/, or root-level dot-files, such as .gitignore or .editorconfig | Skips it. These files are usually CI and tooling configuration. A PR that also changes other files gets a normal review. |
A PR with no changes in the clause’s trigger_directories | Skips it, unless another clause matches. See Limit a trigger to specific directories. |
A PR in a repository without any of the clause’s repo_topics | Skips it, unless another clause matches. See Limit a trigger to tagged repositories. |
To narrow a trigger further, add a directory or topic filter.
Limit a trigger to specific directories
Section titled “Limit a trigger to specific directories”Limit a trigger to pull requests that change files in specific directories, such as src/ or api/. Use it to focus documentation updates on the parts of your codebase your docs cover. In YAML, set the clause’s trigger_directories list. To set it in the dashboard:
-
On the Configuration page, select the Triggers tab.
-
Expand an existing GitHub pull requests trigger, or create one.
-
Open More filters (optional).
-
Select Only when files in these folders change.
-
Enter each folder path, and press Enter or type a comma after each one.
-
Select Save changes, or Add trigger for a new trigger.
Promptless then considers only PRs that change files in those directories, and ignores changes to other files.
Limit a trigger to tagged repositories
Section titled “Limit a trigger to tagged repositories”If you have many repositories and only some need documentation automation, use GitHub topics to choose which ones trigger Promptless. Promptless triggers on any repository that has at least one of the topics you configure. In YAML, set the clause’s repo_topics list. To set it up in GitHub and the dashboard:
-
In GitHub, add a topic, such as
docs-watchorpromptless, to each repository you want Promptless to monitor. -
On the Triggers tab of the Configuration page, expand a GitHub pull requests trigger, or create one.
-
Open More filters (optional).
-
Select Only repos tagged with these GitHub topics, and enter the topics.
-
Select Save changes, or Add trigger for a new trigger.
To add a repository to the trigger later, tag it with a configured topic in GitHub. To remove one, remove the topic from the repository.
Set how Promptless publishes suggestions
Section titled “Set how Promptless publishes suggestions”Set how Promptless publishes suggestions from PR triggers in your publishing policies:
| Option | Policy setting | Effect |
|---|---|---|
| Source PR comments | publishing.suppress_source_pr_comments | Posts a summary comment on the source PR that links to the documentation suggestions, so reviewers see them while reviewing the code. On by default. |
| Automatic PR creation | publishing.auto_create_pr | Opens a PR in your documentation repository with the suggested changes. |
Slack notifications are separate from source PR comments. Promptless sends them to the channel in your notification.slack_channel policy setting, whether or not source PR comments are on.
Suppress source PR comments
Section titled “Suppress source PR comments”Set suppress_source_pr_comments: true to stop comments on source PRs. Promptless still creates documentation suggestions.
policies: default: publishing: suppress_source_pr_comments: trueTeams commonly suppress comments:
- During pilot or onboarding periods, before Promptless has been introduced to the broader engineering team
- On public repositories, while keeping comments enabled for private repos
Tag Promptless in a pull request
Section titled “Tag Promptless in a pull request”To ask for documentation work on a specific pull request, mention @promptless or @promptless-for-oss in it. Matching is case-insensitive, and the repository needs the GitHub integration installed.
Where you put the mention decides when Promptless responds:
| Mention location | When Promptless responds |
|---|---|
| PR title or description | When the PR opens, reopens, or is marked ready for review, or when an edit adds the mention. |
| PR comment | When the comment is posted, on an open, draft, merged, or closed PR. |
| PR review summary or inline review comment | When the review is submitted. |
Add instructions after the mention to tell Promptless what to document:
@promptless please update the docs for this API changePromptless adds a 👀 reaction to the description, comment, or review that holds the mention, so you know it saw your request.
A mention doesn’t have to come from a person. A comment or review from an automated account, like a GitHub Actions workflow, triggers documentation work just as a teammate’s does. For example, a GitHub Actions step can comment on a pull request to ask Promptless to document the change:
- name: Ask Promptless for docs run: gh pr comment "$PR_NUMBER" --body "@promptless please update the docs for this change" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }}Promptless ignores bot comments and reviews that don’t mention it.
Talk to Promptless without a mention
Section titled “Talk to Promptless without a mention”Once Promptless has taken part in an open pull request, you can reply to it without tagging it:
- Review thread replies: A review thread is a comment thread on the PR’s changed lines. After Promptless comments in one, it acts on later replies from people in that thread.
- Listen to all comments: An admin can select this option in the organization’s comment setting. Promptless then acts on any comment from a person on a PR it opened, commented on, or reviewed. With Require a mention selected, other comments on the PR still need a mention.
To keep Promptless from acting on a comment, start it with aside or /aside. To make sure Promptless acts on a comment from an automated account, mention it. For details, see Talk to Promptless without a mention.
See also
Section titled “See also”- GitHub integration, for repository access, IP allow lists, and the authentication model
- GitHub commits, to start documentation work from direct pushes to a branch
- Review and edit Promptless PRs, to give Promptless feedback on the PRs it opens
- Configuration Reference, for every trigger and policy field