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: firing 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 and context
Bitbucket	Triggers

Only GitHub-based collections receive documentation pull requests. GitLab and Bitbucket connect as trigger sources (and, for GitLab, context sources): Promptless monitors their pull and merge requests but does not publish documentation to them.

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.

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-listing applies to GitHub Enterprise, not to GitHub.com.

GitLab

GitLab connects with a group access token that carries the api scope. Group access tokens have read-write api scope by default, but Promptless performs only read operations with the token — viewing merge requests, reading repository files, and fetching project metadata. Promptless never pushes code, creates merge requests, or modifies your GitLab projects through this token.

Tip

If your organization requires stricter access controls, provision the token with the read_api scope instead of api. That limits the token to read-only operations at the GitLab API level, adding a layer of security beyond Promptless’s own behavioral restrictions.

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

When you connect GitHub for publishing, the Promptless GitHub App has write access to your documentation repository so it can open pull requests with suggested changes. 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).

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. On GitLab, a read_api token keeps the connection read-only. For a public open-source repository, the read-only GitHub app opens documentation pull requests from a fork instead of taking write access to your repo.
• 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.