> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/integrations/resource-integrations/github/requesting-access.md). # Requesting GitHub access How to request a just-in-time role on a GitHub repository, or a membership of a GitHub team, via P0 {% hint style="info" %} The GitHub integration is in beta. Functionality and configuration may change. {% endhint %} Request a just-in-time role on one GitHub repository, or a membership of one GitHub team, through P0. When your request is approved, P0 gives you that role as a direct collaborator on the repository, or adds you to the team. When access ends, P0 puts back the direct role or the team membership you had before, or removes the one P0 gave you if you had none. {% hint style="info" %} You must be a member of the GitHub organization, and your GitHub account needs a verified email address on one of the organization's verified domains that matches your P0 email. P0 finds your GitHub account by that address. {% endhint %} ## Requesting a repository role Request a role on one repository with: ```bash p0 request github role ``` | Argument | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | | `` | The repository, as `/`. If P0 is installed on only one GitHub organization, the repository's name is enough. | | `` | The role you need. See [#roles](#roles "mention"). | For example, to request Write on the `api` repository of `my-github-org`: ```bash p0 request github role my-github-org/api write --reason "Fix the release workflow" ``` To list the repositories you can request, run: ```bash p0 ls github role repository ``` You can request only the repositories that your organization's GitHub App is installed on, and you can hold one request per repository at a time. P0 refuses a new request for a repository while an earlier request of yours for it is approved or active, or while P0 couldn't finish removing the role it granted. If two of your requests for the same repository are pending, the second one approved fails. ## Requesting a team membership Request a membership of one team with: ```bash p0 request github team ``` | Argument | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | The team, as `/`, where `` is the team's slug from its URL on GitHub. If P0 is installed on only one GitHub organization, the slug is enough. | | `` | `member` or `maintainer`. | For example, to join the `sre` team of `my-github-org` as a member: ```bash p0 request github team my-github-org/sre member --reason "Join the on-call rotation" ``` To list the teams you can request, run: ```bash p0 ls github team team ``` You can request any team in the organization. A maintainer can also add and remove the team's members and change its settings. As with a repository, you can hold one request per team at a time. If you're already on the team with the role you request, or you're a maintainer and request `member`, you don't need to request it. ## Requesting force-merge access {% hint style="info" %} Force-merge access is in beta. Functionality and configuration may change. {% endhint %} Request force-merge access to one protected branch with: ```bash p0 request github force-merge // ``` Name the branch with its organization and repository, even if P0 is installed on only one GitHub organization. For example, to merge into `main` on the `api` repository of `my-github-org` without its required reviews: ```bash p0 request github force-merge my-github-org/api/main --reason "Ship the hotfix" ``` In Slack, the same command works as a slash command. In the request form, select **GitHub**, then **Force merge**, and choose the **Branch**. The form lists the protected branches of every repository the GitHub App is installed on, as `//`. It lists only branches with a protection rule for their exact name. For the grant's duration, you can merge pull requests into the branch without its required reviews. Required status checks and other rules still apply, and so does any ruleset on the repository or the organization. When access ends, P0 takes you off the list of people who can bypass the branch's reviews, unless you were on it before the grant. The branch needs a protection rule for its exact name, with required reviews. See [GitHub](/integrations/resource-integrations/github.md#force-merge-access). ## Requesting from Slack or the P0 app In Slack, the same commands work as slash commands, such as `/p0 request github role `. To fill in a form instead, type `/p0 request` in Slack, or click **Request Access** on the **Access Management** page of the P0 app, then select **GitHub**. For a repository, choose **Repository role**, then the **Repository** and the **Role**. For a team, choose **Team membership**, then the **Team** and the **Role**. For every way to request access, see [Requesting access](/access-management/access-management/just-in-time-access/requesting-access.md). ## Roles You can request any of GitHub's built-in repository roles: | Role | Request it as | In access policies | | ----------------------------------- | ----------------- | ------------------ | | Read | `read` or `pull` | `pull` | | Triage | `triage` | `triage` | | Triage Plus, where GitHub offers it | `triage_plus` | `triage_plus` | | Write | `write` or `push` | `push` | | Maintain | `maintain` | `maintain` | | Admin | `admin` | `admin` | On GitHub Enterprise Cloud, you can also request your organization's [custom repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles), by name. Role names aren't case-sensitive when you request them. Access policies match a custom role by its name as GitHub shows it. See [GitHub](/integrations/resource-integrations/github.md#access-policies). To list the roles you can request, including custom roles, run: ```bash p0 ls github role role ``` If P0 is installed on more than one GitHub organization, add a repository, as in `--repository my-github-org/api`, so that P0 lists that organization's roles. The list includes Triage Plus for every organization, so request it only if your organization has it. Custom roles show only when the organization is on GitHub Enterprise Cloud and the GitHub App can read them. You can't get a role below the organization's base permission, because GitHub won't assign one. A request for one fails when P0 grants it, after approval. When GitHub shows P0 the base permission, the error names it, so you know what to request instead. ## When your access ends ### A repository role When your access expires, or you or an approver end it early, P0 puts your direct role on the repository back the way it was before the grant: * If you had a direct role before, P0 puts it back. * If you had none, P0 removes your direct role. P0 does this even if someone changed your direct role in GitHub during the grant, and overwrites their change. P0 changes only your direct role. Access you have through a team, or through the organization's base permission, stays as it is. P0 removes your direct role instead of putting your previous one back in two cases: if the organization's base permission is higher than your previous role when access ends, or if you left the organization. When P0 removes your direct role, GitHub [removes you as a collaborator](https://docs.github.com/en/rest/collaborators/collaborators#remove-a-repository-collaborator) on the repository, and also: * removes you from any fork of the repository that you had access to through it, * deletes your own fork, if the repository is private, * denies your open pull requests from a fork, if you still have read access to the repository, and * unassigns you from the repository's issues. Push any work you want to keep before your access ends. ### A team membership When your access expires, or you or an approver end it early, P0 puts your own membership of the team back the way it was before the grant: * If you were on the team before, P0 puts back your role on it, `member` or `maintainer`. * If you weren't, P0 takes you off the team. P0 does this even if someone changed your membership in GitHub during the grant, and overwrites their change. Membership of a child team, which GitHub also counts as membership of its parent, isn't counted or changed. If the team was deleted during the grant, there's nothing to remove, and the request ends without an error. If you were a maintainer during the grant, changes you made to the team stay after your access ends: members you added, maintainers you promoted, and teams you nested under it. ## If removing access fails This section is for admins. You need owner rights on the GitHub organization, and permission to revoke the request in P0. If P0 can't change a role or a team membership when access ends, the request shows as **Errored**, with the reason in its **Error** field. For most errors, fix the cause as in [GitHub](/integrations/resource-integrations/github.md#error-messages), then click **Retry revoke**. Two cases need more: the repository left the GitHub App's repository selection, or GitHub hides the person's account. ### The repository left the app's selection If someone removes the repository from the GitHub App's repository selection during the grant, P0 can't reach the repository to change the role, and the request shows as **Errored**. Open the request from [Access Management](/access-management/access-management.md) in the P0 app. Its **Error** field says: ``` api isn't in the GitHub App's repository selection, so P0 couldn't change jdoe's role. Add the repo back to the app and retry, or change the role in GitHub. ``` Add the repository back to the app's selection, then click **Retry revoke** on the request's page. P0 then finishes the revoke. If you'd rather keep the repository out of the selection, change the person's role in GitHub by hand to the request's **Prior role**, or remove their direct role if the request has none. **Prior role** shows a built-in role by its name in access policies, such as `push` for Write. See [#roles](#roles "mention"). The request stays **Errored** until the repository is back in the selection. Then click **Retry revoke**. P0 sets the person's role to the **Prior role**, or removes their direct role, whatever their role is by then. ### GitHub hides the person's account If GitHub hides the person's account when access ends, as it does for an account flagged as spam, P0 can't find the account. P0 takes the access as already gone and ends the request without an error. The account can keep the role P0 gave it. Check the repository's collaborators in GitHub, and remove the account if it's listed. ## Troubleshooting | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Couldn't match your email to a member of . Ask your GitHub admin to verify your email domain for the org.` | Join the organization if you aren't a member. Then add the email you sign in to P0 with to your GitHub account, and verify it. If its domain isn't one of the organization's verified domains, an owner of the organization verifies the domain. | | ` isn't in the GitHub App's repository selection. Ask your GitHub admin to add it to the app.` | An owner of the organization adds the repository to the GitHub App's installation. | | ` isn't a repository role in . Request one of the roles P0 lists for the repository.` | Request one of the roles in [#roles](#roles "mention"), or one of your organization's custom roles by its name. If a custom role is missing, an admin checks that the GitHub App has the **Custom repository roles** permission, as in [GitHub](/integrations/resource-integrations/github.md#step-2-create-the-github-app). | | `P0 is installed on more than one GitHub organization. Name the repository with its organization, such as my-org/my-repo.` | Name the repository as `/`. | | ` isn't a GitHub repository name. Name the repository with its organization, such as my-org/my-repo.` | Check the repository's spelling, and name it as `/`. | | `P0 is installed on more than one GitHub organization. Name the team with its organization, such as my-org/my-team.` | Name the team as `/`. | | ` isn't a GitHub team slug. Name the team with its organization, such as my-org/my-team.` | Use the team's slug, from its URL on GitHub, and name it as `/`. | | ` isn't a team in . Request one of the teams P0 lists for .` | Check the team's slug. To list the teams you can request, run `p0 ls github team team`. | | ` isn't a team role. Request member or maintainer.` | Request `member` or `maintainer`. | | `Name the branch with its organization and repository, such as my-org/my-repo/main.` | Name the branch as `//`. | | `P0 is installed on more than one GitHub organization. Name the branch with its organization and repository, such as my-org/my-repo/main.` | Name the branch as `//`. | | `The team with id doesn't exist in any more. Request access to a team that does.` | The team was deleted after you requested it. Request another team. | | `P0 is not installed for 'organization' use 'repository-access' on ''. Please ask your P0 admin to install this integration component before continuing.` | Check the organization's spelling. If it's right, an admin installs GitHub for that organization. | | `GitHub couldn't find . Check that it still exists, and that the GitHub App is still installed on .` | Check that the repository or team still exists. If it does, an owner of the organization checks that the GitHub App is still installed and, for a repository, that the repository is in its selection. | | `This principal already has this access` | You already have the role you requested, as a direct collaborator on the repository, or the team role you requested, or you're already on the branch's list of people who can bypass its reviews. You don't need to request it. | | `P0 already manages your access to . Revoke your previous request and try again.` | You already have a request for this repository, team or branch. Relinquish it, or wait for it to end, then request again. | | `P0 couldn't finish removing your previous access to . Ask an admin to fix it in GitHub and finish the revoke in P0, then request again.` | An admin finishes the earlier revoke, as in [#if-removing-access-fails](#if-removing-access-fails "mention"). Then request again. | | `Your GitHub login changed from to after you requested access. Request access again.` | Make a new request. | | `GitHub user doesn't exist any more, so P0 can't give them a role in . Request access again with their current GitHub account.`, or the same message with `a team membership` or `force-merge access` in place of `a role` | GitHub no longer shows the account P0 found for your request. It was deleted, or GitHub is hiding it, as it does for an account flagged as spam. Make a new request. P0 looks up your GitHub account by your email again. | | `GitHub has no account named . Request access again.` | GitHub no longer has the account that P0 matched to your email when it approved the request. Make a new request. | | ` isn't a member of , so P0 can't give them a role on . Add them to the org first.`, or ` isn't a member of , so P0 can't add them to . Add them to the org first.`, or ` isn't a member of , so P0 can't let them bypass reviews on 's branch. Add them to the org first.` | You aren't a member of the organization, or you left it after you requested access. An owner of the organization adds you, then you request again. | | `GitHub refused to change who is on (). If the team is synced with an identity provider group, change its members in the identity provider.` | GitHub doesn't let P0 change the members of a team that's synced with an identity provider group. Ask your identity provider admin for access to the group instead. | | `'s base permission is , which is higher than . Request or higher.` | Request the role the message names, or a higher one. | | `'s base permission is higher than . Request a role at or above the org's base permission.` | Request a higher role. An owner of the organization can tell you its base permission. | | `github is temporarily unavailable; please try again later` | GitHub is limiting requests from the GitHub App, or the connector couldn't reach GitHub. Try again in a few minutes. | | `The GitHub App for is missing . Grant it in the app's settings and accept the update on the installation.` | Your organization's GitHub App doesn't have the permission this kind of access needs. Ask your GitHub admin whether P0 should offer it. If so, they add the permission, as in [GitHub](/integrations/resource-integrations/github.md#leave-out-what-you-dont-need). | | `P0 couldn't reach the GitHub connector. Ask your P0 admin to check its deployment.` | An admin checks that the connector is deployed, and that P0 can invoke it. | | `P0 couldn't read the GitHub App's private key. Ask your P0 admin to check the GitHub install.` | An admin validates the install again, which names the problem with the private key's secret, and fixes it as in [GitHub](/integrations/resource-integrations/github.md#when-p0-validates-the-install). | | `The private key for GitHub App isn't a valid PEM private key. Store the .pem file GitHub generated for the app.` | An admin stores the app's `.pem` file in the secret again, as in [GitHub](/integrations/resource-integrations/github.md#step-3-save-the-private-key). |