Configuration Reference

All Promptless configuration lives in a single promptless.yaml file in your organization’s Agent Knowledge Base. This file defines your doc collections, triggers, context sources, and publishing policies in one place.

Configuration Editor

View and edit your configuration in the dashboard at app.gopromptless.ai/configuration. The Configuration page provides a YAML editor with syntax highlighting, schema-driven completions, and inline validation. Use it when you need precise control over the file format or want to copy configurations between environments.

Click Review changes to see a diff of the YAML, then Save & commit to apply it.

Permissions and Conflict Detection

Every organization member can view the configuration, but only admins can edit and save changes. Non-admins see a read-only view.

The editor uses compare-and-swap to avoid overwriting concurrent changes. If someone else modifies the configuration while you’re editing, you see a conflict warning and can reload to get the latest version.

Changes saved in the Configuration page take effect immediately for new triggers. Policies resolve at publish time, so mid-session config edits apply when suggestions are finalized.

Initial Configuration from Onboarding

When you complete the setup wizard, Promptless creates your promptless.yaml with sensible defaults based on the integrations you connected:

Connected Integration	Generated Trigger	Generated Context Source
GitHub (docs or trigger app)	`github_pr` (opened, first_approval, merge) and `github_commit` with `repos: all`	—
GitLab	`gitlab_mr` (opened, merge) with `repos: all`	—
Bitbucket	`bitbucket_pr` (opened, merge) with `repos: all`	—
Jira / Confluence	—	Unscoped `jira` and/or `confluence` entries
Linear	—	Unscoped `linear` entry
Notion	—	Unscoped `notion` entry

These broad defaults let Promptless start listening for documentation-worthy events immediately. You can edit your configuration anytime to narrow scope, like restricting triggers to specific repositories or limiting context sources to particular projects.

Note

Automatic configuration is additive and idempotent. If you’ve already manually configured a trigger type or context source, onboarding won’t overwrite it.

File Structure

The configuration file has four top-level sections:

doc_collections:   # Where documentation lives (keyed by repo)
context_sources:   # Integrations for additional context
triggers:          # Events that initiate documentation work
policies:          # Publishing and notification rules

All sections are optional. Unknown keys are rejected with validation errors.

Doc Collections

Doc collections define the documentation repositories where Promptless publishes updates. Each collection is keyed by its GitHub repository name in owner/repo format.

doc_collections:
  acme/docs:
    docs_framework: docusaurus
    docs_root_url: https://docs.acme.com
    filter:
      - docs/
      - guides/

Fields

Field	Description
`platform`	Repository platform: `github` (default), `github_oss`, or `github_enterprise`
`host`	GitHub Enterprise hostname (required when `platform: github_enterprise`)
`default_branch`	Branch to target for PRs (defaults to repository’s default branch)
`docs_framework`	Documentation framework (docusaurus, mkdocs, starlight, etc.)
`docs_root_url`	Published documentation site URL
`config_file_path`	Path to framework config file (e.g., `docusaurus.config.js`)
`vale_config_path`	Path to Vale config file to enable prose linting
`doc_detective`	Doc Detective configuration (presence enables the feature)
`filter`	List of directory prefixes or file paths Promptless can modify

Note

One repository can have at most one doc collection per organization. Collection “names” are the repository names. There’s no separate display name field.

Path Scope (filter)

The filter field controls which files Promptless can modify:

Empty or omitted: Promptless can modify any file in the repository.
Directory paths: Entries ending with / allow modifications to any file in that directory tree.
File paths: Exact file paths allow only that specific file.

doc_collections:
  acme/docs:
    filter:
      - docs/           # All files under docs/
      - CHANGELOG.md    # Only this specific file

Context Sources

Context sources give Promptless access to your organization’s tools for additional context. They’re used for narrowing scope when you want to limit which projects, spaces, or databases Promptless can query. Each entry requires a source_type field.

An empty entry (or no entry) for a context source means full access to that integration. Only add entries when you need to restrict scope.

context_sources:
  jira:
    source_type: jira
    project_keys:
      - DOCS
      - PLATFORM
  confluence:
    source_type: confluence
    space_keys:
      - ENGINEERING
  linear:
    source_type: linear
    team_keys:
      - engineering
      - product
  notion:
    source_type: notion
    database_ids:
      - abc123def456

Available Sources

Source Type	Scope Fields	Description
`jira`	`project_keys`	Restrict to specific Jira project keys
`confluence`	`space_keys`	Restrict to specific Confluence space keys
`linear`	`team_keys`	Restrict to specific Linear team identifiers
`notion`	`database_ids`, `page_ids`	Restrict to specific Notion databases or pages

Triggers

Triggers define events that automatically initiate documentation work. These are passive intake events that require explicit configuration. Each trigger has a trigger_type and a match list—the trigger fires when any clause in the list matches, and fields within a clause are ANDed together.

triggers:
  github-prs:
    trigger_type: github_pr
    match:
      - repos:
          - acme/backend
          - acme/api
        trigger_on:
          - opened
          - first_approval
        trigger_directories:
          - src/
          - lib/

  slack-support:
    trigger_type: slack_listen
    match:
      - channels:
          - support
          - customer-questions

Trigger Types

github_pr

Triggers when pull requests are opened, approved, or merged in specified repositories.

Match clause fields:

Field	Description
`repos`	Required. The literal `all` or a list of repositories (`owner/repo` format)
`excluded_repos`	Repositories to exclude from monitoring
`trigger_on`	Required. Events that fire: `opened`, `first_approval`, `merge`
`trigger_directories`	Only trigger when changes touch these directories
`branches`	Only trigger for PRs targeting these branches
`repo_topics`	Only trigger for repos with these GitHub topics
`repo_owners`	Only trigger for repos owned by these owners (the `owner` segment of `owner/repo`)

github_commit

Triggers when commits are pushed to specified branches.

Match clause fields:

Field	Description
`repos`	Required. The literal `all` or a list of repositories
`excluded_repos`	Repositories to exclude
`branches`	Branches to monitor (omit to match only the default branch)
`trigger_directories`	Only trigger when changes touch these directories
`repo_topics`	Only trigger for repos with these GitHub topics
`repo_owners`	Only trigger for repos owned by these owners

gitlab_mr

Triggers when merge requests are opened or merged in GitLab projects.

Match clause fields:

Field	Description
`repos`	Required. The literal `all` or a list of GitLab projects
`excluded_repos`	Projects to exclude
`trigger_on`	Required. Events that fire: `opened`, `merge`
`trigger_directories`	Only trigger when changes touch these directories
`branches`	Only trigger for MRs targeting these branches

bitbucket_pr

Triggers when pull requests are opened or merged in Bitbucket repositories.

Match clause fields:

Field	Description
`repos`	Required. The literal `all` or a list of Bitbucket repositories
`excluded_repos`	Repositories to exclude
`trigger_on`	Required. Events that fire: `opened`, `merge`
`trigger_directories`	Only trigger when changes touch these directories
`branches`	Only trigger for PRs targeting these branches

slack_listen

Passively monitors specified Slack channels for documentation-worthy conversations.

Match clause fields:

Field	Description
`channels`	Required. List of channel names to monitor (no `#` prefix)

Tip

Channel names are automatically updated when channels are renamed in Slack.

msteams_listen

Passively monitors specified Microsoft Teams channels.

Match clause fields:

Field	Description
`channel_ids`	Required. List of Teams channel conversation IDs to monitor

clickup

Triggers when ClickUp tasks reach specified statuses.

Match clause fields:

Field	Description
`statuses`	Required. List of task statuses that trigger documentation work

Built-in Triggers

Some triggers are always active when their integration is connected and don’t appear in the YAML:

slack_mention — @Promptless mentions in Slack channels
msteams_mention — @Promptless mentions in Microsoft Teams
github_mention — @Promptless mentions in GitHub issues and PR comments
web — Requests submitted through the web dashboard
api — Requests from the HTTP API

Built-in triggers can’t be disabled, but their keys are valid in policy rules.

Policies

Policies control publishing behavior and notifications. They consist of a default overlay and ordered rules that apply based on trigger or doc collection.

policies:
  default:
    notification:
      slack_channel: docs-notifications
    publishing:
      auto_create_pr: true
      auto_merge: false
      suppress_source_pr_comments: false

  rules:
    - if:
        trigger: github-commits
      then:
        publishing:
          auto_merge: true

    - if:
        doc_collection: acme/internal-docs
      then:
        notification:
          slack_channel: internal-docs-team

Policy Fields

notification

Field	Description
`slack_channel`	Channel name for notifications (no `#` prefix)

publishing

Field	Description
`auto_create_pr`	Automatically create PRs for suggestions
`auto_merge`	Automatically merge documentation PRs
`suppress_source_pr_comments`	Skip posting comments on source PRs

Rule Matching

Rules are evaluated in order. When multiple rules match, fields from later rules override earlier ones. The if clause supports:

trigger — Match a specific trigger key (including built-in triggers like slack_mention)
doc_collection — Match a specific doc collection by repository name

Both conditions must match if both are specified (AND logic).

Warning

Policies resolve at publish time, not when the trigger fires. If you update your configuration while a suggestion is being created, the new policy values apply when that suggestion is published.

Example Configuration

doc_collections:
  acme/documentation:
    docs_framework: docusaurus
    docs_root_url: https://docs.acme.com
    config_file_path: docusaurus.config.js
    filter:
      - docs/

context_sources:
  jira:
    source_type: jira
    project_keys:
      - DOCS
      - ENG
  linear:
    source_type: linear
    team_keys:
      - engineering

# Built-in triggers (api, github_mention, msteams_mention, slack_mention, web)
# are always on for connected integrations and are not configured here;
# their keys remain valid in policies rules.
triggers:
  main-repos:
    trigger_type: github_pr
    match:
      - repos:
          - acme/backend
          - acme/frontend
        trigger_on:
          - opened
          - first_approval
        trigger_directories:
          - src/

  support-channel:
    trigger_type: slack_listen
    match:
      - channels:
          - customer-support

policies:
  default:
    notification:
      slack_channel: docs-updates
    publishing:
      auto_create_pr: true
      auto_merge: false

  rules:
    - if:
        trigger: slack_mention
      then:
        publishing:
          suppress_source_pr_comments: true

Validation and Errors

The configuration editor validates your YAML before saving. Validation errors appear as inline markers at the relevant line, with details including:

Path — Which field has the error
Line — Line number in the YAML
Message — Description of what’s wrong

Common validation errors:

Unknown keys (typos or unsupported fields)
Invalid enum values (e.g., wrong trigger type)
Missing required fields (e.g., host for github_enterprise platform)
Duplicate repository keys in doc_collections

Tip

If you edit the configuration file directly via git push, invalid YAML keeps the last valid configuration active. The error is surfaced in the Configuration page editor.

Repository Renames

Promptless automatically updates your configuration when repositories or Slack channels are renamed:

GitHub repository renames: The doc_collections key and any references in trigger repos/excluded_repos are updated.
Slack channel renames: Channel names in slack_listen triggers and notification.slack_channel policies are updated.

These updates are committed directly to your Agent Knowledge Base.

Migration from Projects

Existing organizations are automatically migrated from the legacy Projects configuration to promptless.yaml. The migration preserves:

All trigger configurations and settings
Doc collection settings
Automatic PR creation and notification preferences
Context source scoping

After migration, the Projects page is replaced by the Configuration page. Your triggers and doc collections continue working without any action required.