Sobre as permissões de GitHub App
GitHub Apps não têm nenhuma permissão por padrão. Ao registrar o GitHub App, você pode selecionar as permissões específicas para o aplicativo. As permissões que você seleciona determinam o que o aplicativo pode fazer com as APIs do GitHub e a quais webhooks o aplicativo pode assinar. Você deve selecionar as permissões mínimas necessárias para o aplicativo.
Embora GitHub Apps não tenham nenhuma permissão por padrão, eles têm permissões implícitas para ler recursos públicos quando agem em nome de um usuário. Quando um usuário autoriza o aplicativo a agir em nome dele, o GitHub App pode usar o token de acesso do usuário resultante para fazer solicitações à API REST e à API do GraphQL para ler recursos públicos. Para saber mais sobre como agir em nome de um usuário, confira "Autenticação com um aplicativo GitHub em nome de um usuário".
As permissões de aplicativo são classificadas como permissões de repositório, organização ou conta. As permissões do repositório permitem que seu aplicativo acesse recursos relacionados a repositórios pertencentes à conta em que o aplicativo está instalado. As permissões da organização permitem que seu aplicativo acesse recursos relacionados à organização em que o aplicativo está instalado, se ele estiver instalado em uma conta da organização. As permissões de conta permitem que seu aplicativo acesse recursos relacionados a um usuário se o usuário também tiver autorizado seu aplicativo. Para obter mais informações sobre a autorização do usuário de aplicativos, confira "Autenticação com um aplicativo GitHub em nome de um usuário".
Quando um usuário instala um aplicativo em sua conta ou organização, ele vê e concede permissões de repositório e organização que o aplicativo solicitou. Ele também verá uma lista de permissões de conta que o aplicativo pode solicitar para usuários individuais. Quando um usuário autoriza um aplicativo para agir no nome dele, ele vê e concede as permissões de conta solicitadas pelo aplicativo.
O sucesso de uma solicitação de API com um token de acesso do usuário depende das permissões do usuário, bem como das permissões do aplicativo. Por exemplo, se o aplicativo recebeu permissão para gravar o conteúdo de um repositório, mas o usuário só pode ler o conteúdo, o token de acesso do usuário só pode ler o conteúdo. O sucesso de uma solicitação de API com um token de acesso de instalação depende apenas das permissões do aplicativo.
Você pode modificar as permissões para seu aplicativo a qualquer momento. Quando você modificar as permissões, o proprietário de cada conta em que o aplicativo foi instalado será solicitado a aprovar as novas permissões. Se o proprietário da conta não aprovar as novas permissões, sua instalação continuará usando as permissões antigas.
Alguns webhooks e acesso à API exigem permissões de "Administração". Se seu aplicativo exigir permissões de "Administração", explique esse requisito na página inicial do aplicativo. Isso ajudará os usuários a entender por que seu aplicativo precisa de uma permissão de alto nível.
Para obter mais informações sobre como especificar permissões durante o registro GitHub App, confira "Registrar um Aplicativo GitHub". Para saber mais sobre como modificar permissões, confira "Modificar um registro do Aplicativo GitHub".
Escolhendo permissões para acesso ao webhook
A documentação do webhook indica se cada webhook está disponível para GitHub Appss. Para cada webhook que você deseja assinar, confira a documentação do webhook para ver de quais permissões um GitHub App precisa para assinar esse webhook. Para obter mais informações, confira "Eventos e cargas de webhook".
Por exemplo, se você quiser que seu aplicativo assine eventos team, seu aplicativo deverá ter a permissão da organização "Membros".
Na página de registro do GitHub App, os eventos de webhook disponíveis serão alterados à medida que você alterar as permissões do aplicativo. Se você não selecionou permissões suficientes para seu GitHub App assinar um evento, o evento não aparecerá como uma opção na página de registro do aplicativo.
Escolhendo permissões para acesso à API REST
A documentação de referência da API REST para cada ponto de extremidade indica se o ponto de extremidade funciona com GitHub Apps, e indica quais permissões são necessárias para que o aplicativo use o ponto de extremidade. Alguns pontos de extremidade podem exigir várias permissões e alguns pontos de extremidade podem exigir uma de várias permissões. Para obter uma visão geral de quais pontos de extremidade da API REST um GitHub App pode ter acesso ao usar cada permissão, confira “Permissões necessárias para os aplicativos GitHub”.
Por exemplo, para usar o ponto de extremidade GET /orgs/{org}/dependabot/secrets, seu aplicativo deve ter pelo menos permissão de nível de leitura para a permissão "segredos do dependabot da organização".
Se o aplicativo fizer uma solicitação de API REST com permissões insuficientes, a API retornará uma resposta 403.
Para ajudar você a escolher as permissões corretas, você receberá o cabeçalho X-Accepted-GitHub-Permissions na resposta da API REST. O cabeçalho informará quais permissões são necessárias para acessar o ponto de extremidade. Para obter mais informações, confira "Solucionar problemas do API REST".
Escolhendo permissões para acesso à API GraphQL
Nas solicitações do GraphQL, você deve testar seu aplicativo para garantir que ele tenha as permissões necessárias para as consultas e mutações do GraphQL que você deseja fazer.
Se o aplicativo fizer uma consulta de API GraphQL ou mutação com permissões insuficientes, a API retornará uma resposta 401.
Escolhendo permissões para acesso ao Git
Se você quiser que o seu aplicativo use um token de acesso de instalação ou de usuário para se autenticar para o acesso Git baseado em HTTP, você deverá solicitar a permissão do repositório "Conteúdo". Se o seu aplicativo precisar acessar ou editar especificamente arquivos do Actions no diretório .github/workflows, solicite a permissão do repositório "Fluxos de Trabalho".
Em seguida, você poderá usar o token de acesso como a senha HTTP. Substitua TOKEN pelo token de acesso:
git clone https://x-access-token:TOKEN@github.com/owner/repo.git