Source control and access scope
Source control is where Promptless watches for changes and publishes documentation. One Git provider connection can do up to three jobs: activate triggers, supply code context, and open documentation pull requests. Each job needs a different level of access. This page explains what each provider connection does, the access it grants, and how to keep that access to the minimum Promptless needs.
Use cases
Section titled “Use cases”- Your security team asks what Promptless can read and write before you connect a repository. How each connection authenticates lists the access each provider grants.
- You maintain a public open-source repository and can’t grant write access. The GitHub (read-only) app publishes documentation pull requests from a fork.
- Your docs live in a monorepo next to your source code. Path scope keeps Promptless’s changes inside your documentation directories.
- Your GitLab group holds more than documentation projects. Scope the group access token to a group or subgroup that contains only your documentation projects. See GitLab.
What each provider connects
Section titled “What each provider connects”Each source-control connection does these jobs:
| Provider | Used for |
|---|---|
| GitHub | Triggers, context, and publishing |
| GitHub Enterprise | Triggers, context, and publishing (Server or Cloud) |
| GitLab | Triggers, context, and publishing |
Promptless publishes to both GitHub-based and GitLab-based doc collections. It opens pull requests on GitHub repositories and merge requests on GitLab projects. One GitLab connection can do all three jobs. For how publishing to a GitLab project works, see GitLab projects (docs as code).
Promptless also has a read-only GitHub app. It grants read access and webhooks only, and publishes to public repositories through a fork.
How each connection authenticates
Section titled “How each connection authenticates”Each provider uses its own authentication model, and each one limits Promptless to the repositories and actions you authorize.
GitHub
Section titled “GitHub”Promptless connects through its official GitHub App and authenticates with JWTs generated by the app installation. The app grants read and write access to the repositories you select, and either you or Promptless can revoke that access at any time. During installation, you choose which repositories to grant. These are typically your source code and, if your docs live in GitHub, your documentation repository.
To change that selection later, open the app’s installation settings. There you can switch between All repositories and Only select repositories, and add or remove individual repositories. See Manage repository access. When the doc collection repository picker can’t find a repository, it shows a Manage repository access link. The link opens the Integrations page, where you start that change.
Teams that can’t grant write access can install the GitHub (read-only) app instead.
GitHub Enterprise
Section titled “GitHub Enterprise”GitHub Enterprise Server and Cloud users configure a custom GitHub App with an explicit permission set. Promptless requires these repository permissions:
| Permission | Access | What Promptless uses it for |
|---|---|---|
| Pull requests | Read and write | Reads pull request content, opens documentation pull requests, and comments for feedback. |
| Contents | Read and write | Reads repository files, and creates and updates documentation files. |
| Commit statuses | Read-only | Reads the state of pull requests and commits. |
| Checks | Read-only | Detects and fixes failed CI checks on documentation pull requests. |
| Issues | Read-only | Reads repositories and pull requests during research, and receives pull request comments. |
| Webhooks | Read and write | Manages webhook configuration and receives repository events. |
GitLab
Section titled “GitLab”GitLab connects with a group access token that carries the api scope, which is read-write and grants access across the whole group. Publishing uses that same token. There’s no separate publishing credential.
There’s no read-only option, and connecting needs only the api scope. Promptless installs merge-request webhooks on projects where the token has the Maintainer role, so a trigger source project needs Maintainer. A docs destination needs at least the Developer role to push a branch and open a merge request. Promptless restricts those writes to the projects you configure as doc collections. This is an application-level restriction Promptless enforces, not a limit imposed by the token itself.
For a hard technical limit, scope the group access token to a group or subgroup that contains only your documentation projects.
Scope publishing access to your docs
Section titled “Scope publishing access to your docs”Publishing needs write access to the repository where your docs live. The Promptless GitHub App has write access to a GitHub documentation repository so it can open pull requests. The connected group access token lets Promptless push a branch and open a merge request on a GitLab documentation project. Path scope limits where those writes land.
Path scope controls which files Promptless can modify in a documentation repository. You set it with the directories you specify during doc collection setup:
- With no directories, Promptless can modify files anywhere in the repository.
- With directories, Promptless can modify only files that match one of those paths or sit inside them.
- An entry can be a directory or a single file.
docs/allows any file under that directory, andCHANGELOG.mdallows only that file.
If Promptless drafts a change outside the configured scope, it rejects the suggestion with an error that lists the out-of-scope files. Path scope matters most in a monorepo, where docs live alongside source code.
For the full doc collection setup, including path scope and platform support, see GitHub repos (docs as code) and GitLab projects (docs as code).
Keep access least-privilege
Section titled “Keep access least-privilege”Grant each connection only the access its jobs need:
- Select only the repositories Promptless needs. On GitHub, choose Only select repositories, and manage the list from your GitHub organization settings.
- Use read-only access where it’s enough. For a public open-source repository, the GitHub (read-only) app opens documentation pull requests from a fork. It never takes write access to your repository. For GitLab, narrow the group access token to a group or subgroup that contains only your documentation projects, as GitLab describes.
- Revoke access when you no longer need it. You or Promptless can revoke the GitHub App connection at any time. You can also rotate or remove the GitLab group access token in GitLab.
For how source-control access fits Promptless’s broader security posture, see Network architecture and Data handling and classification.