GitHub (read-only) integration
Overview
Section titled “Overview”Install the read-only Promptless GitHub App when your team can’t grant a third-party or AI app write access to its repositories. Open-source maintainer groups are the most common case. With the read-only app, Promptless receives webhooks and reads repositories, and it publishes documentation through a pull request from its own fork.
Reading works on any repository you grant, including private source code repositories you connect for triggers or context. Publishing through a fork works only for public repositories. For most teams, the standard GitHub App is the better fit. The two apps differ in these ways:
| Capability | Standard GitHub App | GitHub (read-only) app |
|---|---|---|
| Repository access | Read and write | Read-only, plus webhooks |
| Triggers and context | Public and private repositories | Public and private repositories |
| Publishing | A branch and pull request directly on your repository | A pull request from the Promptless fork into your upstream base branch |
| Repositories Promptless can publish to | Public and private | Public only |
| Updating contributor PRs | Supported | Not supported |
You can use both apps in the same GitHub organization, with the standard app on some repositories and the read-only app on others.
In this guide, you install the read-only app. Then you set up a public repository as a doc collection that Promptless publishes to through a fork.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization.
- An owner of the GitHub organization or account that holds the repositories. If you aren’t an owner, you can request approval during setup.
- For publishing, a public documentation repository.
Connect the read-only app
Section titled “Connect the read-only app”You need an admin role in your Promptless organization to connect an integration.
-
In the Promptless dashboard, open the Integrations page.
-
Select Connect GitHub (read-only).
-
In GitHub, grant the app access to the repositories you want Promptless to work with. For open-source publishing, include the public repository whose docs you want to keep current.
The integration appears on the Integrations page as its own GitHub (read-only) card. To change which repositories Promptless can access, select Configure in GitHub on that card. It opens the app’s installation page in GitHub.
Publish documentation through a fork
Section titled “Publish documentation through a fork”To publish to a repository connected through the read-only app, set it up as a doc collection. In the dashboard’s Form mode, Promptless fills in the doc collection’s platform field from the connected integration. In promptless.yaml, set platform: github_oss on the doc collection. This value selects the fork-based publishing flow and pins the doc collection to the read-only integration.
How publishing works
Section titled “How publishing works”The read-only app has no write permission, so Promptless can’t push branches or open pull requests on your repository. Instead, when it has a documentation update to publish:
- Promptless forks your repository into a GitHub organization that Promptless owns. It creates the fork the first time it publishes, so no fork appears right after you set up the doc collection.
- It pushes a documentation branch to the fork.
- It opens a pull request from the fork into your repository’s upstream base branch.
A shared Promptless service account performs every write in this flow. It creates the fork, pushes the branch, opens the pull request, and posts the linking comment. That account usually can’t add labels to pull requests in your repository. When GitHub denies the label request, the pull request still opens without the labels, and the labels stay on the suggestion in Promptless. If your review process depends on labels, a maintainer adds them in GitHub.
Example
Section titled “Example”A public open-source project’s maintainers won’t grant write access to any external app. They install the read-only app, connect the project’s source and docs repositories, and set up a doc collection for the docs repository. When a contributor’s pull request merges, Promptless drafts the documentation update and pushes the branch to its fork. It then opens a pull request into the project’s upstream base branch. Maintainers review and merge it like any other community contribution. Promptless never holds write access to the repository.
See also
Section titled “See also”- GitHub repos, to set up a GitHub repository as a doc collection
- Promptless ❤️ Open Source, to get started with Promptless on an open-source project
- Source control and access scope, to compare the access each Git provider connection grants