Requesting GitHub repository access

How to request a just-in-time role on a GitHub repository via P0

The GitHub Repositories integration is in beta. Functionality and configuration may change.

Request a just-in-time role on one GitHub repository through P0. When your request is approved, P0 gives you that role as a direct collaborator on the repository. When access ends, P0 puts back the direct role you had before, or removes your direct role if you had none.

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.

Requesting from the P0 CLI

p0 request github-repositories role <repository> <role>

Argument	Description
<repository>	The repository, as <org>/<repo>. If P0 is installed on only one GitHub organization, the repository's name is enough.
<role>	The role you need. See Roles.

For example, to request Write on the api repository of my-github-org:

p0 request github-repositories role my-github-org/api write --reason "Fix the release workflow"

To list the repositories you can request, run:

p0 ls github-repositories 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 from Slack or the P0 app

In Slack, the same command works as a slash command: /p0 request github-repositories role <repository> <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 Repositories and choose the Repository and the Role.

For every way to request access, see Requesting access.

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, 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 Access policies.

To list the roles you can request, including custom roles, run:

p0 ls github-repositories 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

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 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.

If removing a role 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 when access ends, the request shows as Errored, with the reason in its Error field. For most errors, fix the cause as in 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 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. 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 <org>. 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.
<repo> 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.
<role> isn't a repository role in <org>.	Request one of the roles, 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 Create the GitHub App.
P0 is installed on more than one GitHub organization, so name the repository as <org>/<repo>.	Name the repository as <org>/<repo>.
<repo> isn't a GitHub repository name. Name the repository as <org>/<repo>.	Check the repository's spelling, and name it as <org>/<repo>.
P0 is not installed for 'organization' use 'repository-access' on '<org>'. 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 Repositories for that organization.
GitHub couldn't find <subject>. Check that it still exists, and that the GitHub App is still installed on <org>.	Check that the repository still exists. If it does, an owner of the organization checks that the GitHub App is still installed and 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. You don't need to request it.
P0 already manages your access to <repo>. Revoke your previous request and try again.	You already have a request for this repository. Relinquish it, or wait for it to end, then request again.
P0 couldn't finish removing your previous access to <repo>. 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 a role fails. Then request again.
Your GitHub login changed from <old> to <new> after you requested access. Request access again.	Make a new request.
GitHub user <login> doesn't exist any more, so P0 can't give them a role in <org>. Request access again with their current GitHub account.	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 <login>.	GitHub no longer has the account that P0 matched to your email when it approved the request. Make a new request.
<login> isn't a member of <org>, so P0 can't give them a role on <repo>. 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.
<org>'s base permission is <base>, which is higher than <role>. Request <base> or higher.	Request the role the message names, or a higher one.
<org>'s base permission is higher than <role>. 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-repositories 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.
P0 couldn't reach the GitHub Repositories 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 Repositories install.	An admin validates the install again, which names the problem with the private key's secret, and fixes it as in When P0 validates the install.
The private key for GitHub App <app-id> 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 Save the private key.