GitHub Commits

Promptless can monitor direct commits to your default branches for documentation updates. This is useful for teams that merge changes directly without pull requests, or when you want to capture documentation needs from hotfixes and emergency changes.

How It Works

When a commit is pushed directly to a monitored branch:

1. Commit Detection: Promptless receives notification of the new commit
2. Analysis: The system processes the code diff and commit message to understand the changes
3. Relevance Assessment: Promptless determines if the changes require documentation updates
4. Suggestion Creation: If relevant, Promptless creates documentation suggestions

Commit Triggers vs. Pull Request Triggers

You can use GitHub commit triggers alongside PR triggers, or as a standalone approach.

Use commits alongside PR triggers

If you configure both a GitHub PR project and a GitHub Commits project for the same repositories:

• Promptless comments on PRs while they’re open, providing early feedback on documentation needs
• After the PR merges, the commit trigger updates suggestions with the final merged content
• Useful when you want PR comments during review and updated suggestions after merge

Use commits only

If you configure only a GitHub Commits project, without a corresponding PR project:

• Promptless only runs after changes merge to your default branch
• Reduces notification noise if PR triggers are too frequent
• Since you won’t get PR comments, configure a Slack notification channel to stay informed about new suggestions

Configuration

Configure GitHub commit triggers in your Configuration page using the triggers section:

triggers:
  main-commits:
    trigger_type: github_commit
    match:
      - repos:
          - acme/backend
          - acme/frontend
        branches:
          - main
        trigger_directories:
          - src/
          - lib/

See the Configuration Reference for all available options.

Process Recent Commits

When creating a new project with a GitHub commit trigger, you can enable Process last 30 days of commits to generate initial documentation suggestions from your recent commit history. This is useful for:

• Initial calibration: Get an initial batch of suggestions to review and refine Promptless’s behavior before going live
• Repositories without PRs: Teams using forks or direct-commit workflows can still bootstrap their documentation suggestions
• Migrating from PR triggers: When switching from PR-based to commit-based triggers, catch up on recent changes

Merge commits are automatically skipped during replay to avoid duplicate processing.

Notification Channels

Commit triggers don’t create PR comments. To receive updates when Promptless creates or updates suggestions, configure a Slack notification channel in your publishing policies:

policies:
  default:
    notification:
      slack_channel: docs-updates

Note

For private Slack channels, invite Promptless first by tagging @Promptless in the channel.

Directory-Specific Commits

Similar to PR triggers, you can configure Promptless to only trigger on commits that affect specific directories. This is particularly useful for monitoring changelog directories or specific feature areas.

When trigger directories are specified, only commits that contain changes to those directories trigger documentation updates.

Use Cases

GitHub commit triggers are especially useful for:

• Changelog Monitoring: Automatically update documentation when changelog files are modified
• Hotfix Documentation: Capture documentation needs from emergency fixes that bypass the normal PR process
• Direct-to-Main Workflows: Support teams that commit directly to main branches
• Automated Updates: Trigger documentation updates from automated commit processes

Auto-merge Mode

Automatically merge documentation PRs into the default branch as soon as they’re created.

Auto-merge requires automatic PR creation to also be enabled.

Auto-merge is useful for:

• Internal documentation: When documentation PRs don’t require human review
• High-confidence workflows: Teams that want full automation
• Changelog-driven updates: When you want changelog updates to publish immediately

Enable auto-merge in your publishing policies:

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

Setup Instructions

To connect GitHub to Promptless, see the GitHub Integration setup guide.