Source control and access scope

Source control is where Promptless watches for changes and publishes documentation. A single Git provider connection can do up to three jobs, each of which needs a different level of access: activating triggers, supplying code context, and opening documentation pull requests. This page covers what each provider connection does, the access it grants, and how to keep that access scoped to the minimum Promptless needs.

What each provider connects

Not every provider does every job. The table below shows what each source-control connection is used for today, drawn from each integration’s setup guide.

Provider	Used for
GitHub	Triggers, context, and publishing
GitHub Enterprise	Triggers, context, and publishing (Server or Cloud)
GitLab	Triggers, context, and publishing
Bitbucket	Triggers

GitHub-based and GitLab-based collections both receive documentation changes: Promptless opens pull requests on GitHub repositories and merge requests on GitLab projects. GitLab also serves as a trigger and context source, so one GitLab connection can do all three jobs. Bitbucket connects as a trigger source only — Promptless monitors its pull requests but does not publish documentation to them. For how publishing to a GitLab project works, see GitLab projects (docs as code).

Promptless also has a read-only GitHub app that grants read access and webhooks only and publishes to public repositories through a fork.

How each connection authenticates

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

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

To adjust access later, open your GitHub organization settings, go to Third-party Access → GitHub Apps, find Promptless, and click Configure. There you can switch between All repositories and Only select repositories and add or remove individual repositories. The doc collection setup screen also links to these settings through the Manage repository access button. Teams that cannot grant write access can install the GitHub (read-only) app instead, which grants read access and webhooks only and publishes to public repositories through a fork.

GitHub Enterprise

GitHub Enterprise Server and Cloud users configure a custom GitHub App with an explicit permission set. Promptless requires these repository permissions:

• Pull requests — read and write, to read pull request content, create documentation pull requests, and comment for feedback.
• Contents — read and write, to read repository files and create or update documentation files.
• Commit statuses — read only, to understand the state of pull requests and commits.
• Webhooks — read and write, to manage webhook configuration and receive repository events.

Note

If your GitHub Enterprise instance sits behind a firewall or uses IP restrictions, you must allow Promptless’s IP addresses so webhook delivery and API calls reach it. The full list and the primary egress IP are in the GitHub Enterprise setup guide. IP allow lists aren’t exclusive to GitHub Enterprise—standard GitHub.com organizations can enforce them too. If your organization blocks Promptless, see Organization IP allow lists.

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.

Connecting a GitLab group always writes with the token because it creates the merge-request webhooks and sets the bot avatar, so there’s no read-only option: a trigger or context source needs the api scope with the Maintainer role (webhook management is Maintainer-gated), and a docs destination needs the api scope with 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, but 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.

Bitbucket

Bitbucket connects with a username and an app password scoped to a single workspace. When you create the app password, grant Repositories: Read, Pull requests: Read and Write, and Webhooks: Read and Write. Because the app password is workspace-scoped, Promptless reaches only the repositories and actions you explicitly authorize.

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, and the connected group access token lets Promptless push a branch and open a merge request on a GitLab documentation project. Use path scope to limit where those writes land.

Path scope controls which files Promptless can modify in a documentation repository. Specify directories during doc collection setup, and Promptless enforces those boundaries: with no directories set, it can modify files anywhere in the repo, but with directories set, it can modify only files that match one of those paths or nest inside them. Path scope accepts both directories and individual files, so an entry like docs/ allows any file under that directory, while CHANGELOG.md allows only that one file. If Promptless drafts a change outside the configured scope, it rejects the suggestion and returns an error listing the out-of-scope files, which is useful for monorepos 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

Promptless follows the principle of least privilege, granting only the access each job needs. Its connections give you several ways to enforce that:

• Select only the repositories Promptless needs. On GitHub, choose Only select repositories rather than All repositories, and manage the list from your GitHub organization settings.
• Prefer read-only access where you don’t publish. For a public open-source repository, the GitHub (read-only) app opens documentation pull requests from a fork instead of taking write access to your repo. For GitLab, narrow the group access token to a group or subgroup that contains only your documentation projects, as described in GitLab above.
• Revoke access at any time. You or Promptless can revoke the GitHub App connection, and you can rotate or remove provider tokens (GitLab group access token, Bitbucket app password) on the provider side.

For how source-control access fits Promptless’s broader security posture, see Network architecture and Data handling and classification.