Sobre parâmetros de URL do GitHub App.
Você pode adicionar parâmetros de consulta a essas URLs para pré-selecionar a configuração de um GitHub App em uma conta pessoal ou de organização:
- Conta pessoal:
http(s)://HOSTNAME/settings/apps/new - Conta da organização:
http(s)://HOSTNAME/organizations/:org/settings/apps/new
A pessoa que está criando o aplicativo pode editar os valores pré-selecionados a partir da página de registro do GitHub App, antes de enviar o aplicativo. Se você não incluir os parâmetros obrigatórios na cadeia de consulta da URL, como name, a pessoa que criar o aplicativo precisará inserir um valor antes de enviar o aplicativo.
Para aplicativos que exigem que um segredo proteja seu webhook, o valor do segredo deve ser definido no formulário pela pessoa que criou o aplicativo, não pelo uso de parâmetros de consulta. Para obter mais informações, confira "Como proteger seus webhooks".
A URL a seguir cria um aplicativo público chamado octocat-github-app com uma descrição pré-configurada e uma URL de retorno de chamada. Essa URL também seleciona as permissões de leitura e gravação para checks, inscreve-se nos eventos de webhook check_run e check_suite e seleciona a opção para solicitar a autorização do usuário (OAuth) durante a instalação:
http(s)://HOSTNAME/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&events[]=check_run&events[]=check_suite
Lista completa de parâmetros de consulta, permissões e eventos disponíveis encontra-se nas seções abaixo.
Parâmetros de configuração do GitHub App
| Nome | Tipo | Descrição |
|---|---|---|
name | string | O nome do GitHub App. Dê um nome claro e sucinto ao seu aplicativo. Seu aplicativo não pode ter o mesmo nome de um usuário existente no GitHub, a menos que seja o seu próprio nome de usuário ou da sua organização. Uma versão movida do nome do seu aplicativo será exibida na interface do usuário quando sua integração realizar uma ação. |
description | string | Uma descrição do GitHub App. |
url | string | A URL completa da página inicial do site do seu GitHub App. |
callback_urls | array of strings | Uma URL completa para a qual redirecionar após alguém autorizar uma instalação. Você pode fornecer até 10 URLs de retorno de chamada. Essas URLs são usadas se o aplicativo precisar identificar e autorizar solicitações de usuário para servidor. Por exemplo, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. |
request_oauth_on_install | boolean | Se o seu aplicativo autorizar usuários a usar o fluxo do OAuth, defina essa opção como true para permitir que pessoas autorizem o aplicativo ao instalá-lo, poupando uma etapa. Se você selecionar essa opção, a setup_url não ficará disponível e os usuários serão redirecionados para a callback_url após a instalação do aplicativo. |
setup_url | string | A URL completa para redirecionamento após alguém instalar o GitHub App, se o aplicativo precisar de configuração adicional após a instalação. |
setup_on_update | boolean | Defina como true para redirecionar as pessoas para a URL de configuração quando as instalações forem atualizadas, por exemplo, depois que os repositórios forem adicionados ou removidos. |
public | boolean | Defina essa opção como true quando o GitHub App estiver disponível para o público ou como false quando ele só for acessível pelo proprietário do aplicativo. |
webhook_active | boolean | Defina-a como false para desabilitar o webhook. O webhook está habilitado por padrão. |
webhook_url | string | A URL completa para a qual você deseja enviar as cargas do evento de webhook. |
events | array of strings | Eventos de webhook. Alguns eventos de webhook exigem permissões de read ou de write em um recurso para que você selecione o evento ao registrar um novo GitHub App. Confira a seção "Eventos de webhook do GitHub App" para ver os eventos disponíveis e as permissões necessárias. Você pode selecionar vários eventos em uma string de consulta. Por exemplo, events[]=public&events[]=label. |
domain | string | A URL de uma referência de conteúdo. |
single_file_name | string | Esta é uma permissão de escopo limitado que permite que o aplicativo acesse um único arquivo em qualquer repositório. Quando você define a permissão single_file como read ou write, esse campo fornece o caminho para o único arquivo que será gerenciado pelo GitHub App. Caso você precise gerenciar vários arquivos, confira single_file_paths abaixo. |
single_file_paths | array of strings | Isso permite que o aplicativo acesse até dez arquivos especificados em um repositório. Quando você define a permissão single_file como read ou write, essa matriz pode armazenar os caminhos para até dez arquivos que serão gerenciados pelo GitHub App. Todos esses arquivos recebem a mesma permissão definida por single_file e não têm permissões individuais separadas. Quando dois ou mais arquivos são configurados, a API retorna multiple_single_files=true, caso contrário, retorna multiple_single_files=false. |
Permissões do GitHub App
Você pode selecionar permissões em uma string de consultas usando o nome da permissão na tabela a seguir como o nome do parâmetro de consulta e o tipo de permissão como valor da consulta. Por exemplo, para selecionar as permissões Read & write na interface do usuário de contents, a cadeia de consulta incluirá &contents=write. Para selecionar as permissões Read-only na interface do usuário de blocking, a cadeia de consulta incluirá &blocking=read. Para selecionar no-access na interface do usuário de checks, a cadeia de consulta não incluirá a permissão checks.
| Permissão | Descrição |
|---|---|
administration | Concede acesso a vários pontos finais para administração de organização e repositório. Pode ser: none, read ou write. |
checks | Permite o acesso � API de Verificações. Pode ser: none, read ou write. |
content_references | Permite o acesso ao ponto de extremidade "Criar um anexo de conteúdo". Pode ser: none, read ou write. |
contents | Concede acesso a vários pontos finais que permitem modificar o conteúdo do repositório. Pode ser: none, read ou write. |
deployments | Permite o acesso � API de Implantações. Pode ser: none, read ou write. |
emails | Permite o acesso � API de Emails. Pode ser: none, read ou write. |
followers | Permite o acesso � API de Seguidores. Pode ser: none, read ou write. |
gpg_keys | Permite o acesso � API de Chaves GPG. Pode ser: none, read ou write. |
issues | Permite o acesso � API de Problemas. Pode ser: none, read ou write. |
keys | Permite o acesso � API de Chaves Públicas. Pode ser: none, read ou write. |
members | Concede acesso para gerenciar os membros de uma organização. Pode ser: none, read ou write. |
organization_hooks | Permite o acesso � API de Webhooks da Organização. Pode ser: none, read ou write. |
organization_plan | Permite o acesso para obter informações sobre o plano de uma organização usando o ponto de extremidade "Obter uma organização". Pode ser: none ou read. |
organization_projects | Permite o acesso � API de Projetos. Pode ser: none, read, write ou admin. |
pages | Permite o acesso � API do Pages. Pode ser: none, read ou write. |
plan | Permite o acesso para obter informações sobre o plano do GitHub de um usuário usando o ponto de extremidade "Obter um usuário". Pode ser: none ou read. |
pull_requests | Concede acesso a vários pontos finais do pull request. Pode ser: none, read ou write. |
repository_hooks | Permite o acesso � API de Webhooks do Repositório. Pode ser: none, read ou write. |
repository_projects | Permite o acesso � API de Projetos. Pode ser: none, read, write ou admin. |
secret_scanning_alerts | Permite o acesso � API de verificação de segredos. Pode ser: none, read ou write. |
security_events | Permite o acesso � API de verificação de código. Pode ser: none, read ou write. |
single_file | Permite o acesso � API de Conteúdo. Pode ser: none, read ou write. |
starring | Permite o acesso � API de Marcação com Estrelas. Pode ser: none, read ou write. |
statuses | Permite o acesso � API de Status. Pode ser: none, read ou write. |
team_discussions | Permite o acesso � API de Discussões em Equipe e � API de Comentários de Discussão em Equipe. Pode ser none, read ou write. |
vulnerability_alerts | Permite acesso para receber Dependabot alerts em um repositório. Confira "Sobre os Dependabot alerts" para saber mais. Pode ser: none ou read. |
watching | Concede acesso � lista e alterações de repositórios que um usuário assinou. Pode ser: none, read ou write. |
Eventos webhook do GitHub App
| Nome do evento webhook | Permissão necessária | Descrição |
|---|---|---|
check_run | checks | Verifique se a atividade de execução ocorreu. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "execuções de verificação". |
check_suite | checks | Ocorreu uma atividade de conjuntos de verificações. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "pacotes de verificação". |
commit_comment | contents | Um comentário de commit foi criado. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "comentário sobre commits". |
content_reference | content_references | Uma nova referência de conteúdo é created. Uma nova referência de conteúdo é criada quando o texto ou comentário de um problema ou pull request inclui uma URL que corresponde a um domínio de referência de conteúdo configurado. Para obter mais informações, confira "Como usar anexos de conteúdo" para saber mais sobre referências de conteúdo e anexos. |
create | contents | Um branch ou tag do Git é criado. Para obter mais informações, confira a API REST do "Banco de Dados do Git". |
delete | contents | Um branch ou tag do Git é excluído. Para obter mais informações, confira a API REST do "Banco de Dados do Git". |
deployment | deployments | Uma implantação foi criada. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "implantação". |
deployment_status | deployments | Uma implantação foi criada. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "implantações". |
fork | contents | Um usuário bifurca um repositório. Para obter mais informações, confira a REST API de "forks". |
gollum | contents | Uma página wiki foi criada ou atualizada. Para obter mais informações, confira "Sobre os wikis". |
issues | issues | Atividade relacionada a um problema. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "problemas". |
issue_comment | issues | Atividade relacionada a um comentário sobre um problema ou sobre uma solicitação de pull. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "comentários sobre problemas". |
label | metadata | Atividade relacionada a um rótulo. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "rótulos". |
member | members | Atividade relacionada aos colaboradores do repositório. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "colaboradores". |
membership | members | Atividade relacionada � associação na equipe. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "membros da equipe". |
milestone | pull_request | Atividade relacionada aos marcos. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "marcos". |
organization | members | Atividade relacionada a uma organização e seus integrantes. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "organizações". |
page_build | pages | Representa uma tentativa de criação de um site do GitHub Pages, independentemente de êxito. Um push para um branch habilitado para o GitHub Pages (gh-pages para páginas de projeto, o branch padrão para páginas de usuário e de organização) dispara esse evento. |
project | repository_projects ou organization_projects | Atividade relacionada a project boards. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "projetos". |
project_card | repository_projects ou organization_projects | Atividade relacionada a cartões em um project board. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "quadros de projetos". |
project_column | repository_projects ou organization_projects | Atividade relacionada a colunas em um project board. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "colunas do projeto". |
public | metadata | Quando um repositório privado torna-se público. Sem dúvida: o melhor evento de GitHub Enterprise Server. |
pull_request | pull_requests | Atividade relacionada a pull requests. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "solicitações de pull". |
pull_request_review | pull_request | Atividade relacionada a revisões de pull request. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "revisões de solicitação de pull". |
pull_request_review_comment | pull_request | Atividade relacionada aos comentários de revisão do pull request no diff unificado do pull request. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "comentários de revisão de solicitações de pull". |
pull_request_review_thread | pull_request | Atividade relacionada a um thread de comentários em uma solicitação de pull que está sendo marcada como resolvida ou não resolvida. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. |
push | contents | Um ou mais commits são enviados para uma branch ou tag de um repositório. |
release | contents | Atividade relacionada a uma versão. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "versões". |
repository | metadata | Atividade relacionada a um repositório. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "repositórios". |
status | statuses | Quando o status de um commit do Git é alterado. Para obter mais informações, confira a REST API de "status". |
team | members | Atividade relacionada � equipe de uma organização. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "equipes". |
team_add | members | Quando um repositório é adicionado a uma equipe. |
watch | metadata | Quando alguém marca um repositório com uma estrela. O tipo de atividade é especificado na propriedade action do objeto de conteúdo. Para obter mais informações, confira a API REST de "marcação com estrelas". |