Registrar um aplicativo GitHub usando parâmetros de URL

Sobre os parâmetros de URL para registro de GitHub Apps

Use parâmetros de URL para selecionar previamente as configurações de um novo registro de GitHub App e compartilhar um link personalizado com outras pessoas. O link levará as pessoas para uma página de registro de GitHub App, na qual as configurações de aplicativo serão preenchidas previamente de acordo com os parâmetros de URL incluídos na URL.

Essa abordagem é útil para os integradores que desejam que os clientes configurem um aplicativo na conta pessoal ou na organização com determinadas especificações ou para os clientes que usam o GitHub Enterprise Server que não podem instalar aplicativos do GitHub Marketplace.

Como alternativa, você pode criar um manifesto do GitHub App. Para saber mais, confira Registrar um Aplicativo GitHub a partir do manifesto.

Como criar uma URL de configuração personalizada com parâmetros de consulta

Para criar uma URL de configuração personalizada para um GitHub App em uma conta pessoal ou da organização, adicione parâmetros de consulta após as URLs base a seguir.

• Para registrar um aplicativo em uma conta pessoal, adicione parâmetros de URL a: http(s)://HOSTNAME/settings/apps/new
• Para registrar um aplicativo em uma conta da organização, adicione parâmetros de URL a: http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new. Substitua ORGANIZATION pelo nome da organização em que deseja que o cliente registre o aplicativo.

Na página de registro do aplicativo, a pessoa que registra o aplicativo pode editar os valores selecionados previamente antes de enviar o aplicativo. Se você não incluir os parâmetros para valores obrigatórios (como name) na cadeia de consulta da URL, a pessoa que registra o aplicativo precisará inserir um valor antes de registrá-lo.

Por exemplo, a URL a seguir registra um aplicativo público chamado octocat-github-app em uma conta pessoal. Usando parâmetros de consulta, a URL configura previamente uma descrição e uma URL de retorno de chamada. Ela também seleciona as permissões de leitura e gravação para checks, ativa webhooks usando o parâmetro webhook_active, assina os 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&webhook_active=true&events[]=check_run&events[]=check_suite

Parâmetros de configuração do GitHub App

Use os parâmetros de consulta a seguir para selecionar uma configuração específica para o registro GitHub App. Por exemplo, para dar ao aplicativo o nome "octocat-github-app", a cadeia de consulta incluirá name=octocat-github-app.

Nome do parâmetro	Tipo	Descrição
name	string	O nome do GitHub App. Dê um nome claro e sucinto ao seu aplicativo. O aplicativo não pode ter o mesmo nome de um usuário existente do GitHub, a menos que seja o seu próprio nome de usuário ou da 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 serão usadas se o aplicativo precisar gerar um token de acesso do usuário. Por exemplo, callback_urls[]=https://example.com&callback_urls[]=https://example-2.com. Para saber mais, confira Sobre a URL de retorno de chamada de autorização do usuário.
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. Para saber mais, confira Sobre a URL de 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. Esse parâmetro não se aplica aos aplicativos pertencentes a empresas.
webhook_active	boolean	Defina-o como true para habilitar o webhook. O webhook é desabilitado 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. Para obter mais informações, confira a seção Eventos de webhook do GitHub App. Você pode selecionar vários eventos em uma string de consulta. Por exemplo, events[]=public&events[]=label.
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. Se precisar gerenciar vários arquivos, consulte 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

Use parâmetros de consulta para selecionar as permissões para o registro GitHub App. Para o parâmetro de consulta de URL, use o nome da permissão como o nome do parâmetro de consulta e defina o valor da consulta como um dos valores possíveis para esse conjunto de permissões.

Por exemplo, para selecionar permissões "Leitura e gravação" na interface do usuário de contents, a cadeia de consulta incluirá contents=write. Para selecionar permissões "Somente leitura" na interface do usuário de blocking, a cadeia de consulta incluirá blocking=read. Para selecionar "Nenhum acesso" na interface do usuário de checks, a cadeia de consulta não incluirá a permissão checks.

Para obter mais informações sobre as permissões e os GitHub Apps, confira Escolhendo permissões para um Aplicativo GitHub.

Eventos webhook do GitHub App

Use parâmetros de consulta para habilitar o webhook do GitHub App, designar uma URL de webhook e assinar o aplicativo para receber conteúdos de webhook para eventos específicos.

Para habilitar o webhook do GitHub App, use webhook_active=true na cadeia de consulta. Para designar uma URL completa para a qual deseja enviar cargas de evento do webhook, use webhook_url na cadeia de consulta. Para assinar o aplicativo em eventos de conteúdo de webhook específicos, use events[] como o nome do parâmetro de consulta e defina o valor da consulta como o nome do evento de webhook. Para obter mais informações sobre os possíveis eventos de webhook e as permissões do GitHub App necessárias para assinar cada evento, confira Eventos e cargas de webhook.

Por exemplo, para assinar um GitHub App a fim de receber conteúdo do webhook para atividades relacionadas a comentários de commit, a cadeia de consulta incluirá &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Observe que o evento de webhook commit_comment exige que o GitHub App tenha, no mínimo, acesso de nível de leitura para a permissão do repositório "Conteúdo". Portanto, a cadeia de consulta também deve incluir um parâmetro para definir a permissão contents como read ou write. Para obter mais informações, confira Permissões de aplicativo do GitHub.

Não é possível usar parâmetros de consulta para definir o valor de um segredo de webhook. Se um aplicativo exigir um segredo para proteger o webhook, o valor do segredo precisará ser definido na interface do usuário do GitHub pela pessoa que está registrando o aplicativo.

Para obter mais informações sobre os webhooks e os GitHub Apps, confira Usar webhooks com aplicativos GitHub.