GitHub integration
Overview
Section titled “Overview”Connect a GitHub organization to Promptless through the Promptless GitHub App. One connection covers triggers, context, and publishing for the repositories you grant the app:
| Capability | What Promptless does | Set it up |
|---|---|---|
| Triggers | Starts documentation work from pull requests, commits, and issues in monitored repositories. | Triggers |
| Context | Searches code and issues in granted repositories for technical context. | Context sources |
| Publishing | Opens pull requests with documentation updates in repositories you set up as doc collections. | GitHub repos |
The app follows the GitHub App specification and authenticates with JWTs generated by the app installation. It has read and write access to the repositories you select, and either you or Promptless can revoke that access at any time. If you can’t grant write access, use the GitHub (read-only) app. On GitHub Enterprise Server, use the GitHub Enterprise integration.
In this guide, you install the app on an organization and choose which repositories it can reach. If your organization has an IP allow list, you also let Promptless through it.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization.
- An owner of the GitHub organization to authorize the app. If you aren’t an owner, you can request approval during setup.
- If your organization enforces an IP allow list, an owner who can change its Authentication security settings.
Connect GitHub
Section titled “Connect GitHub”You need an admin role in your Promptless organization to start a GitHub connection. GitHub then asks you to authorize the Promptless GitHub App with your GitHub account. The connection completes only if that account administers the organization or account you connect. For a GitHub organization, that’s an organization owner. For a personal account, it’s the account owner.
On GitHub Enterprise Server, or on GitHub Enterprise Cloud when a policy blocks third-party apps, connect through a custom GitHub App. See GitHub Enterprise integration.
-
In the Promptless dashboard, open the Integrations page.
-
Select Connect GitHub.
-
In GitHub, select the organization to install Promptless into.
-
Select the repositories Promptless can access. These are typically your source code repositories and, if your docs live in GitHub, your documentation repository.
-
On the Integrations page, confirm that the organization appears on its own card.
The connection link stays valid for one hour. If it expires before you finish, start the connection again from the Integrations page.
Some GitHub organizations require an owner’s approval to install a third-party app. If yours does and you aren’t an owner, GitHub asks you to request approval. To connect in that case:
-
Complete GitHub’s approval request flow. The GitHub card on the Integrations page shows Waiting on an organization owner while the request is open.
-
Ask a GitHub organization owner to approve the Promptless GitHub App in the organization’s Third-party Access settings.
-
After the owner approves, confirm that the organization appears on its own card. Promptless connects the approved installation automatically. To check right away, select Check for approval on the card.
If GitHub can’t reuse the approved installation, uninstall the Promptless GitHub App in GitHub, and connect again.
If your GitHub organization enforces an IP allow list, GitHub blocks requests from Promptless until an owner allows them. See Organization IP allow lists.
Connect multiple GitHub organizations
Section titled “Connect multiple GitHub organizations”To add another organization, select Connect another GitHub Org on the Integrations page, and repeat the steps in Connect GitHub. Each organization gets its own card, with its repositories and its own Check access and Disconnect GitHub controls. When you create or edit a doc collection or trigger, repositories from every connected organization are available, listed as organization/repository.
Manage repository access
Section titled “Manage repository access”Change which repositories Promptless can reach whenever you add a source or docs repository, or want to remove one. GitHub controls this access in the app’s installation settings.
-
On the Integrations page, on the organization’s GitHub card, select Configure in GitHub. The app’s installation settings open in GitHub in a new tab.
-
Under Repository access, select All repositories or Only select repositories.
-
Optional. To add a repository, select it from the Select repositories list. To remove one, select × next to its name.
-
Select Save.
-
Back on the GitHub card in Promptless, select Check access.
The card lists the repositories the installation can reach, and they become available when you create or edit doc collections and triggers. GitHub can take a few minutes to report the change. If a repository is still missing, select Check access again.
You can also reach the same settings in GitHub, under your organization’s Settings > Third-party Access > GitHub Apps: find Promptless and select Configure. To remove the app entirely, select Uninstall at the bottom of that page.
Organization IP allow lists
Section titled “Organization IP allow lists”If your GitHub organization enforces an IP allow list, GitHub blocks requests from Promptless that don’t come from an allowed address. Promptless then can’t read pull requests or publish updates, and GitHub reports no error to you. A GitHub organization owner picks one of these options, both under Settings > Authentication security:
| Option | What to do | Maintenance |
|---|---|---|
| Let installed GitHub Apps bypass the list (recommended) | Select Enable IP allow list configuration for installed GitHub Apps. | None. GitHub adds the Promptless GitHub App’s addresses and keeps them current. |
| Add the Promptless egress IP address | Add 3.143.177.103, the NAT gateway address that Promptless requests come from. | This address can change, so you might need to update the entry later. |
These options apply to organizations on GitHub.com. For GitHub Enterprise, see Allow Promptless IP addresses for the full list of addresses.
Fix common GitHub connection problems
Section titled “Fix common GitHub connection problems”| Problem | Cause | Fix |
|---|---|---|
| The GitHub card says no repositories are accessible to the installation. | The app is installed but has no repository access yet. | Grant access as described in Manage repository access. |
| A repository you just granted doesn’t appear in Promptless. | GitHub can take a few minutes to report new access. | Select Check access on the GitHub card. |
| The doc collection picker shows “No connected repository matches that.” | The repository isn’t in a connected organization, or the app can’t reach it. | Select Manage repository access below the picker to open the Integrations page, then connect the organization or grant the repository. |
| The card shows Waiting on an organization owner. | Your organization requires an owner to approve third-party apps. | Ask an owner to approve the app. See Connect GitHub. |
| Promptless stopped reading pull requests or publishing, and your organization uses an IP allow list. | GitHub blocks requests from addresses that aren’t on the list. | Allow Promptless as described in Organization IP allow lists. |
See also
Section titled “See also”- GitHub PRs, to choose which pull requests start documentation work
- GitHub repos, to set up a GitHub repository as a doc collection
- Source control and access scope, to compare GitHub, GitHub Enterprise, and GitLab connections