Route changes across multiple repos
Overview
Section titled “Overview”When your organization runs many docs and code repositories, a few questions come up. Which code repositories feed which doc sites? How do you keep one team’s changes out of another team’s docs? How do you work across several GitHub organizations? You answer them with three kinds of configuration:
- Scope each trigger to the code changes that matter.
- Scope each doc collection to the files Promptless may change.
- Give Promptless the team preferences it can’t research on its own.
This guide shows how those pieces fit together across many repositories.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization, to edit the Configuration page and the Agent Knowledge Base.
- Each GitHub organization that holds your code or docs repositories, connected to Promptless. See Work across multiple GitHub organizations.
One repository per doc collection
Section titled “One repository per doc collection”Each doc collection is one documentation repository with its own settings. These include the docs framework, the default branch, and where the docs are published. They also include a path scope that limits which files Promptless can modify.
Promptless can publish to several doc collections from the same trigger events and context sources. When a change is relevant to more than one collection, Promptless suggests changes for each collection it applies to, so related docs stay in sync. Promptless picks those collections by relevance, and a trigger has no setting that binds it to a specific collection. To keep teams apart, combine these controls:
- Scope each team’s triggers to the repositories that team owns. See Scope which triggers activate.
- Limit each collection with Only watch these folders, its path scope, so Promptless modifies only that collection’s docs files.
- Name each collection in your Knowledge Base instructions to steer what Promptless writes there.
Scope which triggers activate
Section titled “Scope which triggers activate”A trigger’s filters set which code changes start documentation work. Set them up on the Triggers tab of the Configuration page. Choose the trigger’s repositories with Which repositories?, then narrow it under More filters (optional):
| Filter | What it does |
|---|---|
| Which repositories? | Watches All repositories, or only the Specific repos you pick. This is the main control over which repositories a trigger watches. |
| Skip these repositories | Leaves out the repositories you list. Use it when you watch All repositories but want to exclude a few. |
| Only repos owned by these accounts | Limits the trigger to repositories owned by these accounts, the owner segment of owner/repo. |
| Only repos tagged with these GitHub topics | Limits the trigger to repositories that carry these GitHub topics, so you opt repositories in by topic without listing each one. |
| Only when files in these folders change | Starts work only when a change touches these folders. Unrelated changes in the same repository start no documentation work. |
| Only pull requests targeting these branches | Starts work only for pull requests that target these branches. |
The filters a trigger offers depend on its type. See the configuration reference for every trigger and doc collection field.
Work across multiple GitHub organizations
Section titled “Work across multiple GitHub organizations”Connect every GitHub organization that holds your repositories to the same Promptless account. After you connect the first organization, select Connect another GitHub Org on the Integrations page to add the next. Each organization gets its own card, and repository pickers list repositories from every connected organization as organization/repository. For the steps, see Connect multiple GitHub organizations.
See which collection a suggestion targeted
Section titled “See which collection a suggestion targeted”When suggestions span several collections, set the suggestions list’s Group control to Doc collection to see each collection’s suggestions under its own header. To focus on one collection, pick it from the Collection filter. See Triage the review queue for the rest of the suggestions list.
Apply rules per collection
Section titled “Apply rules per collection”Publishing and notification behavior can differ by collection. To change it for one collection, add a policy rule that matches only that collection:
-
On the Policies tab of the Configuration page, select Add rule.
-
Under When this matches, set Doc collection to the collection.
-
Under Promptless does this, set the behavior that differs for that collection. For example, pick a different Slack channel for its notifications, or change Open a pull request automatically.
-
Select Save policies.
When more than one rule matches, a later rule overrides the fields that earlier rules set. See the configuration reference for the policy schema.
Set per-collection preferences in your Knowledge Base
Section titled “Set per-collection preferences in your Knowledge Base”A policy rule matches only on a trigger and a doc collection, and it sets only notification, escalation, publishing, and archiving fields. Put each team’s other conventions and exceptions in PROMPTLESS.md or other files in your Agent Knowledge Base. Promptless reads these files when it performs documentation tasks.
To edit PROMPTLESS.md:
-
In the dashboard, open Settings and select Agent Knowledge Base.
-
Open
PROMPTLESS.mdand make your changes in the editor. -
Select Save. The change commits directly to the Knowledge Base repository.
Only organization admins can edit Knowledge Base files, and other members have read-only access. If you’re not an admin, ask Promptless to make the change for you. Promptless edits PROMPTLESS.md and commits the change.
The Knowledge Base is shared across your whole organization, so name the doc collection in each instruction to scope it to that team’s docs. For example:
- “Customer-facing guides belong in
acme/docs. Keep internal runbooks inacme/internal-docs.” - “Treat
reference/inacme/docsas generated. Its source of truth lives elsewhere, so leave those pages alone.” - “Never revise a released changelog entry in
acme/docs. Add a new entry instead.” - “When
acme/api-docschanges, check the authentication overview inacme/docsfor staleness.”
See also
Section titled “See also”- Route changes to the right doc version, to route changes across version branches or version directories
- GitHub repos, for every doc collection setting, including path scope
- Configuration reference, for the full trigger, doc collection, and policy schema
- Route and assign suggestions to the right people, to send each suggestion to the right reviewer