Skip to content

For the complete documentation index, see llms.txt.

GitHub PRs

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.

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

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.

  1. In the Promptless dashboard, open the Integrations page.

  2. Select Connect GitHub.

  3. In GitHub, select the organization to install Promptless into.

    GitHub Organization Selection
  4. Select the repositories Promptless can access. These are typically your source code repositories and, if your docs live in GitHub, your documentation repository.

    Repository Selection
  5. 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:

  1. Complete GitHub’s approval request flow. The GitHub card on the Integrations page shows Waiting on an organization owner while the request is open.

  2. Ask a GitHub organization owner to approve the Promptless GitHub App in the organization’s Third-party Access settings.

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

  1. On the Configuration page, switch to YAML mode.

  2. In the triggers section, add a github_pr trigger with a match clause for the repositories you want to monitor:

    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
    trigger_directories:
    - src/
  3. Save the configuration.

Each match clause takes these fields:

FieldRequiredDescription
reposYesThe repositories to monitor, in owner/repo format, or the literal all. A clause that lists updated needs an explicit list.
trigger_onYesOne or more trigger modes: opened, first_approval, merge, or updated.
trigger_directoriesNoOnly PRs that change files in these directories trigger documentation updates. See Limit a trigger to specific directories.
repo_topicsNoOnly 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.

List one or more trigger modes in each match clause’s trigger_on:

Modetrigger_on valueWhen Promptless runsChoose it when
OpenedopenedOnce, when the PR opensYou want documentation suggestions ready alongside the code changes, so reviewers can evaluate both.
First approvalfirst_approvalOnce, on the PR’s first approvalYou want documentation work to start after code review, so Promptless analyzes the reviewed changes.
MergemergeOnce, when the PR mergesYou want documentation only for changes that have landed.
UpdatedupdatedOn every push to an open PRYou 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.

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 requestWhat Promptless does
A draft PRSkips 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 openedSkips it.
A PR that changes only dot-directories, such as .github/, .circleci/, or .beads/, or root-level dot-files, such as .gitignore or .editorconfigSkips 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_directoriesSkips it, unless another clause matches. See Limit a trigger to specific directories.
A PR in a repository without any of the clause’s repo_topicsSkips 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 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:

  1. On the Configuration page, select the Triggers tab.

  2. Expand an existing GitHub pull requests trigger, or create one.

  3. Open More filters (optional).

  4. Select Only when files in these folders change.

  5. Enter each folder path, and press Enter or type a comma after each one.

  6. Select Save changes, or Add trigger for a new trigger.

A GitHub pull requests trigger on the Configuration page, with More filters expanded and docs/ entered under Only when files in these folders change

Promptless then considers only PRs that change files in those directories, and ignores changes to other files.

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:

  1. In GitHub, add a topic, such as docs-watch or promptless, to each repository you want Promptless to monitor.

  2. On the Triggers tab of the Configuration page, expand a GitHub pull requests trigger, or create one.

  3. Open More filters (optional).

  4. Select Only repos tagged with these GitHub topics, and enter the topics.

  5. 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 from PR triggers in your publishing policies:

OptionPolicy settingEffect
Source PR commentspublishing.suppress_source_pr_commentsPosts 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 creationpublishing.auto_create_prOpens 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.

Set suppress_source_pr_comments: true to stop comments on source PRs. Promptless still creates documentation suggestions.

policies:
default:
publishing:
suppress_source_pr_comments: true

Teams 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

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 locationWhen Promptless responds
PR title or descriptionWhen the PR opens, reopens, or is marked ready for review, or when an edit adds the mention.
PR commentWhen the comment is posted, on an open, draft, merged, or closed PR.
PR review summary or inline review commentWhen the review is submitted.

Add instructions after the mention to tell Promptless what to document:

@promptless please update the docs for this API change

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

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.