Skip to content

For the complete documentation index, see llms.txt.

GitHub commits

A GitHub commit trigger starts documentation work from commits pushed to a branch you monitor. Promptless reads each commit’s diff and message, and creates documentation suggestions when the change needs a documentation update. Add one when changes reach your default branch without a pull request:

Use caseWhy a commit trigger fits
Changelog monitoringUpdates documentation when changelog files change. Scope it with trigger_directories.
Hotfix documentationCatches documentation needs from emergency fixes that skip the normal PR process.
Direct-to-main workflowsCovers teams that commit directly to the default branch.
Automated updatesStarts documentation updates from commits that automated processes push.

This guide covers choosing between commit and PR triggers, adding the trigger, and setting how Promptless notifies you and publishes its 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 commit 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.

Choose commit triggers, PR triggers, or both

Section titled “Choose commit triggers, PR triggers, or both”

A commit trigger activates on commits pushed to a monitored branch. A GitHub PR trigger activates on pull request activity. The two overlap in a standard GitHub workflow. When a pull request merges, its merge commit lands on the default branch. The commit trigger then activates along with the PR trigger’s merge event.

Use a commit trigger on its own or alongside PR triggers for the same repositories:

SetupWhen Promptless runsComments on PRsChoose it when
Commit and PR triggersWhile the PR is open, and again after it mergesYesYou want documentation feedback during review, and suggestions updated with the final merged content.
Commit trigger onlyAfter changes merge to the monitored branchNoPR triggers create too much notification noise. Send notifications to a Slack channel to hear about new suggestions.
  1. On the Configuration page, switch to YAML mode.

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

    triggers:
    main-commits:
    trigger_type: github_commit
    match:
    - repos:
    - acme/backend
    - acme/frontend
    branches:
    - main # omit to match only the repository's default branch
    trigger_directories:
    - src/
    - lib/
  3. Save the configuration.

Each match clause takes these fields:

FieldRequiredDescription
reposYesThe repositories to monitor, or the literal all.
branchesNoThe branches to monitor. Omit it to monitor only each repository’s default branch.
trigger_directoriesNoOnly commits that change files in these directories trigger documentation updates, such as a changelog directory.

For every field, including repository exclusions and topic and owner filters, see the Configuration Reference.

Commit triggers don’t comment on PRs, so tell Promptless where to report suggestions and how far to automate publishing. Set these options in your publishing policies:

OptionPolicy settingEffect
Slack notificationsnotification.slack_channelPosts to a Slack channel when Promptless creates or updates suggestions.
Automatic PR creationpublishing.auto_create_prOpens a documentation PR for each suggestion.
Auto-mergepublishing.auto_mergeMerges documentation PRs into the default branch as soon as Promptless creates them. Requires automatic PR creation.

For a private Slack channel, first invite Promptless by tagging @Promptless in the channel. Then set the channel in a policy:

policies:
default:
notification:
slack_channel: docs-updates

Auto-merge publishes documentation PRs without human review. Use it for internal documentation, high-confidence workflows that want full automation, or changelog updates that should publish immediately.

Turn on both automatic PR creation and auto-merge in a policy rule scoped to the commit trigger:

policies:
rules:
- if:
trigger: main-commits
then:
publishing:
auto_create_pr: true
auto_merge: true