Time suggestions to your release cycle
Overview
Section titled “Overview”A documentation suggestion is most useful when it arrives as the change becomes real for your users. Drafted too early, it documents work your reviewers haven’t finished. Drafted too late, the docs trail the release. Align two things with your release cycle:
- When Promptless drafts. The trigger event decides this. It can be a pull request opening or merging, a commit landing, a feature flag changing, or a call from your pipeline.
- When a suggestion publishes. The publishing policy decides whether a suggestion waits for review or merges on its own.
Both use the trigger and policy settings you already have on the Configuration page.
Match the trigger event to your release stage
Section titled “Match the trigger event to your release stage”-
On the Triggers tab of the Configuration page, expand your GitHub pull requests trigger.
-
Under When should Promptless run?, select one or more moments in a pull request’s life:
Option Activates when Choose it when When it’s opened A pull request opens You want documentation drafted alongside the code, so reviewers evaluate both together. When it’s first approved A pull request gets its first approval You want Promptless to analyze the change after a reviewer has vetted it. When it’s merged A pull request merges You want documentation only for changes that have made it into the code base. -
Select Save changes.
A new GitHub pull request trigger starts with When it’s opened and When it’s merged selected. If suggestions keep arriving before a change has settled, move to a later stage. Select both an early and a late option when you want early feedback and a refresh after merge. See Choose trigger modes for the full behavior of each mode, and the Configuration Reference for the underlying trigger_on field.
To keep suggestions current while a source pull request changes, add updated to the trigger’s trigger_on list in YAML. This mode is available only in YAML. Promptless then re-reviews the open pull request each time someone pushes new commits to it. It runs far more often than the options in the table. Scope it to specific repositories and trigger_directories. See Re-review open PRs on every push.
Document only what has shipped
Section titled “Document only what has shipped”To document changes once they land, add a commit trigger, which activates when commits reach a monitored branch.
-
On the Triggers tab, add a GitHub commit trigger.
-
Point it at the branch you want to watch.
-
Save your changes.
Pair the commit trigger with your PR trigger to get both timings. Promptless comments on pull requests while they’re open, then refreshes the suggestion with the final content once the change merges to your default branch.
A commit trigger on its own, without a PR trigger, is the quietest option. Promptless runs only after changes reach the monitored branch.
Control when a suggestion publishes
Section titled “Control when a suggestion publishes”Trigger timing decides when Promptless drafts. Publishing policies decide when a suggestion publishes. By default, a suggestion waits for someone to review and publish it. The defaults on the Policies tab of the Configuration page apply to every suggestion. A rule overrides them for a specific trigger or doc collection.
Some changes can publish without review, such as internal documentation or changelog updates you want live as soon as the change lands. For those, add a rule scoped to a trigger you trust:
-
On the Policies tab, add a rule.
-
Under When this matches, set Trigger to the trigger you trust.
-
Under Promptless does this, turn on Open a pull request automatically.
-
Turn on Merge the pull request automatically.
-
Save your changes.
With both on, Promptless merges each docs PR from that trigger as soon as it creates it. Auto-merge requires automatic PR creation. Suggestions from every other trigger still wait for review. For every policy field and its default, see the Configuration Reference.
Documentation PRs open as drafts until the source PR merges
Section titled “Documentation PRs open as drafts until the source PR merges”A docs PR (a merge request on GitLab) that links to source pull requests opens as a draft until the code it documents ships. It becomes ready for review once every linked source pull request has merged or closed and at least one of them merged. Promptless checks the draft docs PR again each time a linked source pull request merges or closes. This works the same way on GitHub, GitHub Enterprise, and GitLab.
If every linked source pull request closes without merging, the docs PR stays a draft, because the change it documents didn’t ship. When the code lands in a different pull request, such as a replacement for the closed one, mark the docs PR ready for review yourself. Otherwise, close it.
A suggestion with no linked source pull request opens ready for review immediately. That includes suggestions from Slack, Jira, MCP, or the API.
Trigger from a feature-flag rollout
Section titled “Trigger from a feature-flag rollout”When a feature ships behind a flag, its pull request can merge weeks before users see the change. Pull request and commit timing then drafts the docs long before they’re relevant. A LaunchDarkly flag trigger starts documentation work when the flag changes, which is when flagged features reach users.
The trigger requires the LaunchDarkly integration, which is in beta. To connect it, follow Connect LaunchDarkly.
Trigger from a deploy or release pipeline
Section titled “Trigger from a deploy or release pipeline”If your release happens in a CI/CD pipeline, use the API trigger to request documentation work over HTTP. Add a step after the release completes that calls Promptless and passes release context. The docs then update on the same event that ships the product:
curl -X POST "https://api.gopromptless.ai/triggers" \ -H "Authorization: Bearer sk-pl-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Document the rate limiting feature released in v2.5.", "context": { "release": "v2.5.0" } }'The context object is optional metadata that appears in the trigger’s history. See API triggers for the full request format.
See also
Section titled “See also”- GitHub PRs, for every PR trigger mode and filter
- GitHub commits, to document changes once they land on a branch
- Filter noise and tune relevance, to cut low-value suggestions
- Configuration Reference, for every trigger and policy field