Skip to content

For the complete documentation index, see llms.txt.

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.

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

Each source-control connection does these jobs:

ProviderUsed for
GitHubTriggers, context, and publishing
GitHub EnterpriseTriggers, context, and publishing (Server or Cloud)
GitLabTriggers, 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.

Each provider uses its own authentication model, and each one limits Promptless to the repositories and actions you authorize.

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 Server and Cloud users configure a custom GitHub App with an explicit permission set. Promptless requires these repository permissions:

PermissionAccessWhat Promptless uses it for
Pull requestsRead and writeReads pull request content, opens documentation pull requests, and comments for feedback.
ContentsRead and writeReads repository files, and creates and updates documentation files.
Commit statusesRead-onlyReads the state of pull requests and commits.
ChecksRead-onlyDetects and fixes failed CI checks on documentation pull requests.
IssuesRead-onlyReads repositories and pull requests during research, and receives pull request comments.
WebhooksRead and writeManages webhook configuration and receives repository events.

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.

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, and CHANGELOG.md allows 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).

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.