GitHub (read-only) integration
Used for: Triggers and Context (any repository), and Publishing (public repositories)
Promptless offers two ways to install its GitHub App: the standard GitHub App, which has read and write access, and the read-only app. The read-only app exists for teams that cannot grant a third-party or AI app write access to their repositories.
When to use the read-only app
Section titled “When to use the read-only app”Some teams, especially open-source maintainer groups, can’t approve a third-party or AI application that has write access to their repositories. The read-only app lets those teams use Promptless without granting write access: Promptless receives webhooks and read access, and publishes documentation through a fork instead of writing to the repository directly. This fork-based publishing works only for public repositories.
The read-only app is also a good fit whenever you want to keep Promptless’s access scoped to reading — the public-repository story is not the only one. Any repository Promptless only needs to read, such as a source code repository connected for triggers or context, can be granted through the read-only app, including private, closed-source code repositories. The public-repository limitation applies only to fork-based publishing, not to reading: Promptless can read a private repo through the read-only app, but it can only publish documentation to a public one.
How it differs from the standard GitHub app
Section titled “How it differs from the standard GitHub app”For most teams, the standard GitHub App is the right choice. The read-only app changes how Promptless is granted access and how it publishes documentation.
| Dimension | Standard GitHub App | GitHub (read-only) app |
|---|---|---|
| Repository access | Read and write | Read-only, plus webhooks |
| How documentation PRs are published | Promptless creates a branch and opens a pull request directly on your repository | Promptless opens a pull request from its own fork into your repository’s upstream base branch |
| Repository support for publishing | Public and private repositories | Public repositories only |
How publishing works
Section titled “How publishing works”Because the read-only app has no write permission, Promptless cannot push branches or open pull requests directly on your repository. Instead, Promptless creates its own fork of the repository in a GitHub organization Promptless owns, makes its documentation branches on that fork, and opens a pull request from the fork into your repository’s upstream base branch. A shared Promptless service account holds the credential that performs every write in this flow. That includes creating the fork, pushing the documentation branch, opening the pull request, and posting the linking comment.
Promptless creates the fork itself as needed. Configuring a doc collection does not create the fork, so don’t expect to see a fork in Promptless’s organization immediately after setup.
Installation
Section titled “Installation”Install the read-only app from the integrations page, then grant it access to the repositories you want Promptless to work with. For open-source publishing, this includes the public repository whose docs you want to keep current.
Once connected, the read-only integration appears on the integrations page as its own GitHub (read-only) card. The Configure in GitHub button on that card opens the app’s installation page, where you can adjust which repositories Promptless can access. Repository access is always governed in GitHub’s own App settings.
platform is a field you set on each doc collection in promptless.yaml. Setting platform: github_oss selects the read-only publishing flow and pins that doc collection to the read-only integration. In the dashboard’s Form mode, Promptless prefills platform from the connected integration, so most readers never see it.
What you can do with the read-only app
Section titled “What you can do with the read-only app”Once connected, you can use the read-only app for:
- Triggers: Monitor pull requests and commits for documentation updates
- Context Sources: Search code repositories and issues for technical context
- Doc Collections: Publish documentation updates to public repositories through a pull request from a fork
Updating Contributor PRs (adding a docs commit to a contributor’s existing PR) is not compatible with the read-only app.
Example
Section titled “Example”A public open-source project whose maintainers will not grant write access to any external app installs the read-only app, connects its source and docs repositories, and configures a doc collection for its docs. When a contributor’s pull request merges, Promptless drafts the doc update, pushes the branch to its fork of the repository, and opens a pull request from that fork into the project’s upstream base branch; the service account posts the linking comment. Maintainers review and merge the documentation PR like any other community contribution without Promptless ever holding write access to the repository.
Frequently asked questions
Section titled “Frequently asked questions”Can I use the read-only app with a private repository?
Yes. The read-only app can read triggers and context from a private repo, but Promptless cannot publish documentation to one through the read-only app. Doc collections in private repositories must use the standard GitHub App.
Why not just use the standard GitHub App?
Some teams — especially open-source maintainer groups — cannot approve any application with write access to their repositories. The read-only app is the path for them: Promptless never takes write access and instead publishes from a fork.
Can I use the standard app and the read-only app in the same organization?
Yes. You can install the standard GitHub App on some repositories and the read-only app on others.