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 page opens in Form mode, a structured editor that groups your configuration into four tabs—Doc collections, Triggers, Context sources, and Policies—so you can manage everything without hand-editing YAML. Each tab shows how many items it holds and surfaces the fields for that section directly.

You can also ask Promptless to make these changes for you in Slack or Microsoft Teams. See Ask Promptless to update your configuration.

Form mode saves one item at a time. When you add or change a doc collection, trigger, or context source, you save that item on its own, and Promptless commits the change to your Agent Knowledge Base right away. Policies save as a single section. There’s no separate review-and-commit step—each save is its own commit.

When you need precise control over the file format, switch to YAML mode using the toggle at the top of the page. YAML mode is the raw editor with syntax highlighting, schema-driven completions, and inline validation. Use it when you want to copy configurations between environments or edit the file directly.

In Form mode, Promptless fills in fields from your connected integrations. The doc collection platform (GitHub, GitHub OSS, GitHub Enterprise, or GitLab) comes from the integration that reaches the repository rather than a field you set, and the repo, Slack channel, and Jira, Confluence, Linear, and Notion pickers autocomplete from what each integration can see.

Form mode also keeps references consistent for you. Renaming a doc collection updates every trigger and policy rule that points at it in the same save, and warns you if the new name is already taken. Deleting a doc collection or trigger that a policy rule depends on removes those rules too, so you never end up with a rule pointing at something that no longer exists.

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.

Note

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) 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
Google Drive	—	Unscoped google_drive entry
Slite	—	Unscoped slite entry

Onboarding seeds pull request triggers only; commit triggers are opt-in and stay off until you add a github_commit trigger yourself. 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.

Connecting Jira, Confluence, Linear, or Notion after onboarding works the same way: Promptless adds a broad, unscoped context source for that tool if you don’t already have one. Existing entries and any scoping you’ve set are left untouched.

Add a commit trigger

A commit trigger (github_commit) activates when commits are pushed to a branch you monitor, rather than when a pull request opens or merges. Without a branches filter, it watches only the repository’s default branch. Add one when you want Promptless to react to commits directly:

triggers:
  default-branch-commits:
    trigger_type: github_commit
    match:
      - repos:
          - acme/backend
        branches:
          - main          # omit to match only the default branch
        trigger_directories:
          - src/

In a typical pull request workflow, this overlaps with your PR triggers: merging a pull request also pushes a merge commit to the default branch, so the commit trigger activates alongside the github_pr merge event. A commit trigger earns its place when changes reach a branch without a pull request—hotfixes or commits pushed straight to the default branch, for example—so Promptless still documents those changes. See GitHub Commits for the full workflow.

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. GitHub collections are keyed by owner/repo; GitLab collections are keyed by the project’s full path, including every namespace segment (for example, acme/platform/developer-docs).

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, github_enterprise, or gitlab
host	Bare instance hostname (no scheme, no path). Required for github_enterprise; optional for gitlab (blank means gitlab.com, a hostname means self-hosted GitLab); invalid for every other platform
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.

A GitLab-backed collection sets platform: gitlab and is keyed by its project path. Leave host off for gitlab.com; set it to your instance hostname for self-hosted GitLab. Promptless opens merge requests on these projects the same way it opens pull requests on GitHub.

doc_collections:
  acme/docs:                 # gitlab.com project
    platform: gitlab
    docs_framework: docusaurus
  acme/handbook:             # self-hosted GitLab project
    platform: gitlab
    host: gitlab.acme.com
    docs_framework: mkdocs

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.

Note

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
  google_drive:
    source_type: google_drive
    drive_ids:
      - 0AExampleDriveIdUk9PVA
    folder_ids:
      - 1BExampleFolderIdXyZ
  slite:
    source_type: slite

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
google_drive	drive_ids, folder_ids	Restrict to specific shared drives or folders (omit both for full access)
slite	—	No scope fields—the whole Slite workspace is available when connected

Triggers

Triggers define events that automatically initiate documentation work. Unlike built-in triggers, these require explicit configuration. Each trigger has a trigger_type and a match list—the trigger activates 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; it can also re-review an open PR on each new push.

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. opened, first_approval, merge, or updated
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)

Caution

A match clause that lists updated in trigger_on must name an explicit repos list; it cannot use repos: all. Other clauses in the same trigger are unaffected.

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 activate the trigger: 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 activate the trigger: 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

jira_new_issue

Triggers when an issue is created in a matching project.

Match clause fields:

Field	Description
project_key	Required. Non-empty list of Jira project keys (for example DOCS)

An optional top-level instructions field (a sibling of match) gives the trigger standing instructions passed to Promptless on each run; a present-but-blank value is rejected. Like the built-in jira_mention, Promptless comments on the ticket and owes an answer there, tracked for follow-up.

jira_label_added

Triggers when a label is added to an issue.

Match clause fields:

Field	Description
new_label	Required. Labels whose addition activates the trigger; matches when any listed label is added
project_key	Optional. Restrict to these project keys

A label whose first token is promptless is reserved for the built-in jira_mention path and never matches new_label; name the label something else.

Takes the same optional instructions field and has the same on-ticket behavior as jira_new_issue.

jira_status_change

Triggers when an issue moves into a new status.

Match clause fields:

Field	Description
new_status	Status names the issue moved into
is_done	Only true is accepted; matches any status in Jira’s done category, stable across projects and renames
project_key	Optional. Restrict to these project keys

At least one of new_status, is_done, or project_key must be set in each clause.

Takes the same optional instructions field and has the same on-ticket behavior as jira_new_issue.

A Jira trigger activates once per crossing and does not re-fire on later deliveries about an issue that still matches. Creating an issue crosses every edge at once, so a new issue that matches two Jira triggers dispatches once, tagged with both keys; and an issue moving between two done statuses activates an is_done: true trigger again. See How a configured trigger activates for the full explanation.

schedule

Triggers when a scheduled time comes due and dispatches your standing instructions each time.

Match clause fields:

Field	Description
cron	Required. Five-field cron expression (minute, hour, day of month, month, day of week). Runs at most once an hour.
timezone	Optional. IANA timezone name; defaults to UTC. Keeps its wall-clock time across daylight-saving changes.

Unlike other trigger types, a schedule trigger also takes a top-level instructions field (required, non-empty) as a sibling of match—because no inbound event describes the work, the instructions are the whole job. Each match clause is a {cron, timezone} pair, and multiple clauses run the same instructions on multiple cadences.

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
• jira_mention — Assigning a Jira issue to the Promptless account, @mentioning it in a comment, or adding a promptless-prefixed label
• 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
      msteams_channel: "19:0a1b2c3d@thread.tacv2"
    escalation:
      slack_channel: docs-escalations
      msteams_channel: "19:4e5f6a7b@thread.tacv2"
      email:
        - docs-team@example.com
    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	Slack channel name for notifications (no # prefix), or null to disable an inherited Slack channel
msteams_channel	Microsoft Teams channel conversation ID (e.g. 19:…@thread.tacv2) for notifications, or null to disable an inherited Teams channel

slack_channel and msteams_channel are independent—set either, both, or neither. The Teams conversation ID is the same value you paste into an msteams_listen trigger; copy it from Teams. A Teams channel must have prior Promptless bot activity before notifications can be delivered there.

• Omitting the field inherits the channel from policies.default or an earlier rule.
• Setting it to null disables the channel for that scope, overriding any inherited channel so no notification is sent.
• Setting it to a channel name (or Teams conversation ID) routes notifications there.

Because resolution depends on field presence, an omitted field and an explicit null are not the same: null means disable, absent means inherit. The two channels resolve independently, so you can disable one while leaving the other inherited.

policies:
  default:
    notification:
      slack_channel: docs-notifications

  rules:
    - if:
        doc_collection: acme/internal-docs
      then:
        notification:
          slack_channel: null   # silence Slack for this collection

escalation

The escalation channel is where Promptless routes operational alerts—such as proactive notifications when a connected integration develops a problem—rather than suggestion announcements. This is completely different from notifications about suggestions being created, updated, closed, or merged. For example, a test account is missing the feature flags to screenshot a screen, or a PR references a Jira issue that Promptless can’t read—either the Jira integration isn’t connected, or it’s connected but the project isn’t accessible. See Escalation channel for the full behavior. It’s a sibling of notification and, unlike notification, also accepts email.

policies:
  default:
    escalation:
      slack_channel: ops-alerts
      msteams_channel: "19:0a1b2c3d@thread.tacv2"
      email:
        - oncall@acme.com

Field	Description
slack_channel	Slack channel name for escalation alerts (no # prefix), or null to disable an inherited Slack channel
msteams_channel	Microsoft Teams channel conversation ID (e.g. 19:…@thread.tacv2), or null to disable an inherited Teams channel
email	List of email addresses for escalation alerts (escalation only; not used for suggestion notifications), or [] to disable an inherited list

Set any combination of the three; the same presence semantics as notification apply (omit to inherit; null for slack_channel/msteams_channel or [] for email to disable), and msteams_channel carries the same Teams-activity prerequisite as notification. Escalations reach the escalation channel(s) even when suggestion notifications are off or no notification channel is set. When a platform’s escalation channel is unset, Promptless raises escalations through your suggestion-notification routing on that platform.

escalation.email routes escalations to a list of email addresses. Email is escalation-only. Suggestion notifications never arrive by email. Promptless emails only the addresses you list. Email escalation requires email delivery to be configured for your deployment. It’s on by default on Promptless-hosted deployments. Self-hosted deployments must configure it.

publishing

Field	Description
auto_create_pr	Automatically open documentation PRs for suggestions, or merge requests on GitLab. Gates only automatic PR creation—see the note below
auto_merge	Automatically merge auto-created documentation PRs. On GitLab the merge is immediate and squashes, and a merge request that can’t merge right away stays open for you to merge manually (full detail)
suppress_source_pr_comments	Skip posting comments on source PRs

Note

auto_create_pr gates only automatic PR creation. When it’s off, Promptless leaves suggestions as drafts and doesn’t open a documentation PR on its own—but you can still open one on demand by asking the agent directly, clicking the Create PR button in Slack, or creating it from the dashboard. auto_merge applies only to PRs that Promptless creates automatically.

archiving

Promptless automatically archives suggestions that have gone stale, so your dashboard stays focused on active work. The archiving block controls this behavior.

Field	Description
enabled	Whether automatic archiving runs for this scope. Defaults to true.
stale_after_days	Days of inactivity before a suggestion is archived. Defaults to 30; must be a positive integer.

Unlike publishing, archiving is opt-out: it runs with a 30-day window unless you disable or adjust it. Set enabled: false to keep a scope’s suggestions open indefinitely—useful when a team leaves a suggestion open until a linked ticket closes—or lower stale_after_days to archive sooner. Staleness is measured from a suggestion’s last activity rather than its creation date, taking the most recent of when it was created, updated, had its diff refreshed, or was reopened. A suggestion viewed within the window is always spared.

policies:
  default:
    archiving:
      stale_after_days: 45

  rules:
    - if:
        doc_collection: acme/docs
      then:
        archiving:
          enabled: false   # keep this collection's suggestions indefinitely

Note

Archiving resolves per doc collection, so a rule can disable it or change the window for one collection while the default covers the rest. Because archiving runs on a schedule rather than in response to a trigger, only policies.default and rules scoped by doc_collection apply to it—a rule scoped by trigger never affects archiving.

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

Caution

Policies resolve at publish time, not when the trigger activates. 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, jira_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
• Malformed doc_collections keys (a GitHub, GitHub OSS, or GitHub Enterprise key must be exactly owner/repo, with no extra path segments; a GitLab key is the project’s full path, so nested namespace segments are valid; no key may carry surrounding whitespace)

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 the slack_channel of notification and escalation policies are updated. Teams conversation IDs are not Slack channel names and are left unchanged.

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.