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
Section titled “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. Each tab shows how many items it holds and the fields for that section, so you can manage everything without editing YAML.
You can also ask Promptless to make these changes for you in Slack, Microsoft Teams, or on New Task. 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. Promptless commits the change to your Agent Knowledge Base right away. Policies save as a single section. 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) is not a field you set. It comes from the integration that reaches the repository. 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. It also 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 every rule points at something that exists.
Provider connection and trigger availability
Section titled “Provider connection and trigger availability”In Form mode, a trigger type whose provider isn’t connected is disabled, with a link to connect it on the Integrations page. Schedule triggers need no integration and are always available.
A saved trigger whose provider is disconnected shows as inactive: its match fields are locked, but you can still select Remove. It reactivates when you reconnect the provider.
Saving an added, renamed, or modified trigger while its provider is disconnected fails, and nothing is committed to your promptless.yaml. Reconnect the provider, then save again. See Connect a provider before you add its triggers.
Set notifications, escalations, and publishing in Form mode
Section titled “Set notifications, escalations, and publishing in Form mode”On the Policies tab, each policy has three groups: Notifications, Escalations, and Publishing. A policy is either the default policy or a rule.
| Group | Purpose |
|---|---|
| Notifications | Announces a new doc suggestion. |
| Escalations | Routes an item that needs a person, such as a question about a change or an integration Promptless cannot reach. |
| Publishing | Controls a doc update after it is ready. |
Notifications and Escalations each have two channel selects: Slack channel and Microsoft Teams channel. The four selects use only two labels, repeated across the two groups. The group heading above a select is the only thing that identifies it. Always check the heading before you choose a channel.
The Notifications selects write the singular notification key.
| Select | YAML field |
|---|---|
| Slack channel | notification.slack_channel |
| Microsoft Teams channel | notification.msteams_channel |
On a rule, each channel select maps to the tri-state resolution described in Policy fields.
| Action | Option on a rule | Option on the default policy |
|---|---|---|
| Inherit the channel | Inherit from default (omits the field) | Not available. The default policy has nothing to inherit. |
| Stop Slack notifications | Disabled — no Slack notifications | No Slack notifications |
| Stop Teams notifications | Disabled — no Teams notifications | No Teams notifications |
| Stop Slack escalations | Disabled — no Slack escalations | No Slack escalations |
| Stop Teams escalations | Disabled — no Teams escalations | No Teams escalations |
| Route to a channel | Pick the channel name. | Pick the channel name. |
The disable options are the Form-mode equivalent of null. Selecting one stops announcements or escalations on that platform.
On a rule that routes nothing for a group, the two selects are hidden and an Add notifications or Add escalations button appears instead. Click the button to show the two selects. Both default to Inherit from default.
- You pick from a list. You do not type a channel name.
- The Slack selects list the channels the Slack integration can see.
- The Teams selects list the channels Promptless has seen activity in.
- When no Teams channels are available, the Microsoft Teams channel select under Notifications lets you paste a channel’s conversation ID instead.
- The paste fallback can inherit or route to a channel. It cannot disable an inherited Teams channel. To disable one, switch to YAML mode and set
msteams_channel: null.
On the default policy, each Publishing flag is a switch. On a rule, each flag is a segmented control with Inherit, On, and Off. A rule can force a flag on or off against an inherited value. The switch and the segmented control write the same YAML keys:
| Control | YAML field (under publishing:) |
|---|---|
| Open a pull request automatically | auto_create_pr |
| Merge the pull request automatically | auto_merge |
| Skip the comment on the source PR | suppress_source_pr_comments |
Permissions and conflict detection
Section titled “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.
Initial configuration from onboarding
Section titled “Initial configuration from onboarding”When you finish setup, Promptless creates your promptless.yaml from 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 | None |
| GitLab | gitlab_mr (opened, merge) with repos: all | None |
| Jira / Confluence | None | Unscoped jira and/or confluence entries |
| Linear | None | Unscoped linear entry |
| Notion | None | Unscoped notion entry |
| Google Drive | None | Unscoped google_drive entry |
| Slite | None | Unscoped slite entry |
Onboarding adds pull request and merge request triggers only. To watch commits as well, see Add a commit trigger.
Onboarding also sets auto_create_pr: true in policies.default.publishing, so Promptless opens a documentation PR, or a merge request on GitLab, for each suggestion. To keep suggestions as drafts, turn off Open a pull request automatically on the default policy. See publishing.
The one exception is the suggestion Promptless drafts when you finish setup. It stays in the dashboard whatever auto_create_pr says. See Review your first suggestion.
Onboarding doesn’t overwrite a trigger type or context source that you configured yourself. The same applies when you connect Jira, Confluence, Linear, or Notion after onboarding. Promptless adds an unscoped context source for that tool only if you don’t have one.
To narrow these defaults, edit your configuration. For example, limit a trigger to specific repositories or a context source to specific projects.
Migration from projects
Section titled “Migration from projects”If your organization used the legacy Projects configuration, Promptless migrated it to promptless.yaml. The migration kept:
- Trigger configurations and settings
- Doc collection settings
- Automatic PR creation and notification preferences
- Context source scoping
The Configuration page replaces the Projects page. Migrated triggers and doc collections keep working with no action from you.
Add a commit trigger
Section titled “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 are examples. With a commit trigger, Promptless still documents those changes. See GitHub Commits for the full workflow.
File structure
Section titled “File structure”promptless.yaml has four top-level sections:
| Section | Defines | Details |
|---|---|---|
doc_collections | Documentation repositories where Promptless publishes updates | Doc collections |
context_sources | Limits on what Promptless reads from connected integrations | Context sources |
triggers | Events that start documentation work | Triggers |
policies | Where notifications and escalations go, how Promptless publishes, and when it archives | Policies |
Every section is optional. A key the schema doesn’t define, at any level of the file, fails validation.
Example configuration
Section titled “Example configuration”This file defines one doc collection, two scoped context sources, two triggers, and a default policy with one rule:
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: trueDoc collections
Section titled “Doc collections”A doc collection is a documentation repository where Promptless publishes updates. Its key is the repository path: owner/repo on GitHub, or the project’s full path on GitLab, including every namespace segment (for example, acme/platform/developer-docs). The key is also the collection’s name. An organization can have one doc collection per repository.
Each doc collection accepts these fields:
| Field | Description |
|---|---|
platform | Repository platform: github (default), github_oss, github_enterprise, or gitlab. |
host | Bare instance hostname, with no scheme or path. Required for github_enterprise. Optional for gitlab: omit it for gitlab.com, or set it for self-hosted GitLab. Not valid for github or github_oss. |
default_branch | Branch that documentation PRs target. Defaults to the repository’s default branch. |
docs_framework | Documentation framework, such as docusaurus, mkdocs, or starlight. |
docs_root_url | URL of the published documentation site. |
config_file_path | Path to the framework’s configuration file, such as docusaurus.config.js. |
vale_config_path | Path to a Vale configuration file. Promptless lints with it. |
doc_detective | Doc Detective settings. Including the key marks the collection as using Doc Detective, even before the repository has Doc Detective files. Set config_path only when your config file isn’t at the repository root. |
filter | Directory prefixes and file paths Promptless can modify. See Path scope (filter). |
doc_collections: acme/docs: docs_framework: docusaurus docs_root_url: https://docs.acme.com filter: - docs/ - guides/GitLab projects
Section titled “GitLab projects”A GitLab collection sets platform: gitlab and uses the project path as its key. Omit host for gitlab.com, or set it to your instance hostname for self-hosted GitLab. Promptless opens merge requests on GitLab 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: mkdocsPath scope (filter)
Section titled “Path scope (filter)”The filter field limits which files Promptless can modify:
filter entry | Files Promptless can modify |
|---|---|
| Empty or omitted | Any file in the repository |
Path ending in / | Any file in that directory tree |
| File path | Only that file |
doc_collections: acme/docs: filter: - docs/ # All files under docs/ - CHANGELOG.md # Only this specific fileContext sources
Section titled “Context sources”Promptless reads your connected integrations for context on documentation work. A context source entry limits what Promptless reads from one integration, such as which Jira projects or Notion databases it can query. Promptless reads the whole integration when it has no entry, or an entry with no scope fields. Add an entry only when you want to restrict scope.
Each entry needs a source_type, which sets the scope fields it accepts:
source_type | Scope fields | Restricts Promptless to |
|---|---|---|
jira | project_keys | These Jira project keys |
confluence | space_keys | These Confluence space keys |
linear | team_keys | These Linear team identifiers |
notion | database_ids, page_ids | These Notion databases or pages |
google_drive | drive_ids, folder_ids | These shared drives or folders |
slite | None | No restriction. Promptless reads the whole Slite workspace when connected. |
An entry’s key is a lowercase slug of letters, numbers, and hyphens, up to 64 characters, such as google-drive.
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: sliteTriggers
Section titled “Triggers”A trigger starts documentation work when an event matches it. Each trigger in the triggers section is one you configure. Built-in triggers, such as Slack mentions, are always on and don’t appear in the file.
Each trigger accepts these fields:
| Field | Required | Description |
|---|---|---|
trigger_type | Yes | The kind of event the trigger matches. See Trigger types. |
match | Yes | A list of one or more match clauses. The trigger activates when any clause matches, and every field set in that clause must match. |
instructions | For schedule only | Standing instructions Promptless receives on each run. Required for schedule and optional for jira_new_issue, jira_label_added, and jira_status_change. Other trigger types don’t accept it. |
A trigger’s key is a lowercase slug of letters, numbers, and hyphens, up to 64 characters. Policy rules refer to the trigger by this key.
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-questionsTrigger types
Section titled “Trigger types”Provider-backed triggers require their integration to be connected. See Provider connection and trigger availability.
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) |
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 |
slack_listen
Passively monitors specified Slack channels for documentation-worthy conversations. When you configure a public channel, Promptless joins it. Private channels and channels shared with another workspace through Slack Connect need you to add Promptless in Slack before it can monitor them.
Match clause fields:
| Field | Description |
|---|---|
channels | Required. List of channel names to monitor (no # prefix) |
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 |
launchdarkly_flag
Triggers when a matching feature flag changes in a connected LaunchDarkly account.
Match clause fields:
| Field | Description |
|---|---|
project_key | Restrict to these LaunchDarkly projects |
environment_key | Restrict to these environments |
flag_key | Restrict to these feature flags |
At least one of project_key, environment_key, or flag_key must be set in each clause. An empty field matches every value in that dimension. Requires LaunchDarkly to be connected (see Connect LaunchDarkly). The integration and this trigger are in beta. See LaunchDarkly triggers for the full match semantics and an example.
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) |
The optional instructions field, a sibling of match, gives Promptless standing instructions on each run. A blank value fails validation. Promptless comments on the ticket when the run produces a suggestion or hits a blocker you can act on. It posts nothing when there’s no documentation change. See Reply on the ticket.
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. 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
Section titled “Built-in triggers”These triggers are always active when their integration is connected and don’t appear in the YAML:
| Key | Activates on |
|---|---|
slack_mention | @Promptless mentions in Slack channels |
msteams_mention | @Promptless mentions in Microsoft Teams |
github_mention | @Promptless mentions in GitHub issues and PR comments |
gitlab_mention | @Promptless mentions in GitLab merge-request 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 turned off, but you can use their keys in policy rules.
Policies
Section titled “Policies”Policies set where Promptless sends notifications and escalations, how it publishes documentation updates, and when it archives stale suggestions. policies.default applies to every suggestion. Each entry in policies.rules applies only when its if block matches, and overrides the default field by field. See Rule matching.
policies.default and each rule’s then block accept these sections:
| Section | Controls | Fields |
|---|---|---|
notification | Slack and Teams channels that announce suggestions | notification |
escalation | Slack and Teams channels, and email addresses, that receive escalations | escalation |
publishing | Whether Promptless opens and merges documentation PRs, and what it posts on PRs | publishing |
archiving | Whether and when Promptless archives stale suggestions | archiving |
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-teamPolicy fields
Section titled “Policy fields”notification
Section titled “notification”| Field | Description |
|---|---|
slack_channel | Slack channel name for suggestion notifications, with no # prefix |
msteams_channel | Microsoft Teams channel conversation ID for suggestion notifications, such as 19:…@thread.tacv2 |
Set either field, both, or neither. Copy the Teams conversation ID from Teams. It’s the same value you paste into an msteams_listen trigger. Promptless can deliver to a Teams channel only after its bot has activity there.
Each channel field resolves by whether and how you set it. Slack and Teams resolve separately, so you can turn off one and keep the other inherited.
| Value | Result |
|---|---|
| Field omitted | Inherits the channel from policies.default or an earlier matching rule |
null | Turns off notifications on that platform for the scope, overriding any inherited channel |
| Channel name, or Teams conversation ID | Sends notifications to that channel |
policies: default: notification: slack_channel: docs-notifications
rules: - if: doc_collection: acme/internal-docs then: notification: slack_channel: null # silence Slack for this collectionescalation
Section titled “escalation”The escalation channel receives problem reports: configuration and operational problems that need a person. Announcements about created and updated suggestions go to the notification channels. Promptless sends two kinds of problem reports:
- A trigger problem is one Promptless hits while working on a trigger. For example, a test account is missing the feature flags Promptless needs to take a screenshot. Or a PR references a Jira issue that Promptless can’t read, because the Jira integration isn’t connected or the project isn’t accessible.
- A connection alert comes from the daily connection check, such as an integration that needs reconnecting.
See Escalation channel for the full behavior.
escalation accepts the same channel fields as notification, plus email:
| Field | Description |
|---|---|
slack_channel | Slack channel name for escalations, with no # prefix |
msteams_channel | Microsoft Teams channel conversation ID for escalations, such as 19:…@thread.tacv2 |
email | List of email addresses that receive escalations |
policies: default: escalation: slack_channel: ops-alerts msteams_channel: "19:4e5f6a7b@thread.tacv2" email: - oncall@acme.comSet any combination of the three fields. They resolve the same way as notification: omit a field to inherit it, and set slack_channel or msteams_channel to null, or email to [], to turn it off. msteams_channel needs the same prior bot activity as in notification.
Escalations reach the escalation channels even when suggestion notifications are off or no notification channel is set. A problem report goes to a platform’s notification channel only when it’s a trigger problem and the resolved escalation section omits that platform’s field. A null field sends it nowhere on that platform. Connection alerts go only to the escalation destinations in policies.default. See When problem reports go to the notification channel for an example.
Email is for escalations only, and suggestion notifications never arrive by email. notification has no email setting, so Promptless emails escalations only when you set escalation.email. Promptless emails only the addresses you list. Email escalation needs email delivery configured for your deployment. Promptless-hosted deployments have it on by default, and self-hosted deployments must configure it.
publishing
Section titled “publishing”| Field | Default | Description |
|---|---|---|
auto_create_pr | false | Open a documentation PR, or a merge request on GitLab, for each suggestion automatically |
auto_merge | false | Merge the documentation PRs that Promptless opens automatically |
suppress_source_pr_comments | false | Skip posting comments on source PRs |
suppress_pr_description_extras | false | Leave the generated extras out of documentation PR and merge request bodies |
On GitLab, auto_merge merges immediately and squashes. A merge request that can’t merge right away stays open for you to merge manually. See Automatic merge request creation.
The extras that suppress_pr_description_extras removes are the “Open in Promptless” link, the trigger events section, and the tip. With the setting on, the body contains only the suggestion’s own description, whether the dashboard default or the agent wrote it.
archiving
Section titled “archiving”Promptless archives stale suggestions automatically, so your dashboard stays focused on active work. The archiving section sets when:
| Field | Default | Description |
|---|---|---|
enabled | true | Whether automatic archiving runs for this scope |
stale_after_days | 30 | Days of inactivity before Promptless archives a suggestion. Must be a positive integer. |
Set enabled: false to keep a scope’s suggestions open indefinitely, for example when a team leaves a suggestion open until a linked ticket closes. Lower stale_after_days to archive sooner.
Promptless measures inactivity from a suggestion’s last activity: the most recent of when it was created, updated, had its diff refreshed, or was reopened. Promptless never archives a suggestion that someone viewed within the window.
policies: default: archiving: stale_after_days: 45
rules: - if: doc_collection: acme/docs then: archiving: enabled: false # keep this collection's suggestions indefinitelyRule matching
Section titled “Rule matching”Promptless starts from policies.default, then applies each matching rule in order. A later rule overrides the fields an earlier one set. Each rule’s if block takes one or both of these keys:
| Key | Matches when |
|---|---|
trigger | The event matched this trigger. Use a key from triggers or a built-in trigger key, such as slack_mention. |
doc_collection | The suggestion targets this doc collection. Use the collection’s key from doc_collections. |
When a rule sets both keys, both must match.
Validation and errors
Section titled “Validation and errors”The configuration editor validates your YAML before it saves. Each validation error appears as an inline marker with these details:
| Detail | Description |
|---|---|
| Path | The field that has the error |
| Line | The line number in the YAML, when the error belongs to one line |
| Message | What’s wrong |
These are the most common validation errors:
| Error | Fix |
|---|---|
| Unknown key, such as a typo or an unsupported field | Correct the spelling, or remove the key. |
Invalid value, such as an unknown trigger_type | Use one of the values this page lists for the field. |
Missing required field, such as host when platform is github_enterprise | Add the field. |
Duplicate repository key in doc_collections | Keep one entry per repository. |
Malformed doc_collections key | Use exactly owner/repo for GitHub, GitHub OSS, and GitHub Enterprise. Use the project’s full path, including nested namespaces, for GitLab. Remove any surrounding whitespace. |
| Trigger or context source key that isn’t a lowercase slug | Rename the key using lowercase letters, numbers, and hyphens, such as google-drive. |
| Policy rule that references an undefined trigger or doc collection | Correct the key, or define the trigger or doc collection it names. Built-in trigger keys are always defined. |
| Provider-backed trigger added, renamed, or modified while its provider is disconnected | Reconnect the provider, then save again. See Connect a provider before you add its triggers. |
Repository and channel renames
Section titled “Repository and channel renames”When you rename a GitHub repository or a Slack channel, Promptless updates your configuration to match. It commits the change to your Agent Knowledge Base:
| Renamed | What Promptless updates |
|---|---|
| GitHub repository | The doc_collections key, the repository in trigger repos and excluded_repos lists, and doc_collection in policy rules |
| Slack channel | The channel in slack_listen triggers, and slack_channel in notification and escalation policies |
A Slack channel rename leaves msteams_channel values unchanged.