Registrando um aplicativo GitHub usando parâmetros de URL

Sobre parâmetros de URL para registro GitHub Apps

Você pode usar parâmetros de URL para pré-selecionar as configurações de um novo GitHub App registro e compartilhar um link personalizado com outras pessoas. O link levará as pessoas para uma GitHub App página de registro, em que as configurações do aplicativo serão preenchidas previamente de acordo com os parâmetros de URL incluídos na URL.

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

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

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

Para criar uma URL de configuração personalizada para uma GitHub App conta pessoal ou de 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.
• Para registrar um aplicativo em uma conta empresarial, adicione parâmetros de URL a: http(s)://HOSTNAME/enterprises/ENTERPRISE/settings/apps/new. Substitua ENTERPRISE pelo nome da empresa em que você 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

GitHub App parâmetros de configuração

Você pode usar os seguintes parâmetros de consulta para selecionar uma configuração específica para o GitHub App registro. 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. Seu aplicativo não pode ter o mesmo nome que um usuário existente GitHub , a menos que seja seu próprio nome de usuário ou 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 de 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 a qual redirecionar depois que alguém instalar o GitHub App, caso o aplicativo exija 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 true quando seu GitHub App estiver disponível para o público ou false quando estiver acessível apenas ao 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 as permissões read ou write para um recurso antes de poder selecionar o evento ao registrar um novo GitHub App. Para obter mais informações, consulte a seção GitHub Appeventos de webhook. 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 single_file permissão como read ou write, esse campo fornece o caminho para o único arquivo que você GitHub App gerenciará. 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 single_file permissão como read ou write, essa matriz pode armazenar os caminhos para até dez arquivos que você GitHub App gerenciará. 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.

GitHub App Permissões

Você pode usar parâmetros de consulta para selecionar as permissões para o GitHub App registro. 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 & gravação" na interface do usuário de contents, a cadeia de consulta incluirá contents=write. Para selecionar as permissões de "Somente leitura" na interface de usuário em blocking, a cadeia de consulta incluirá blocking=read. Para selecionar "Sem acesso" na interface do usuário para checks, sua string de consulta não incluiria a permissão checks.

Para obter mais informações sobre permissões e GitHub Apps, consulte Escolhendo permissões para um aplicativo GitHub. Para ver a lista de permissões disponíveis para uso e seus nomes parametrizados, confira Gerenciar seus tokens de acesso pessoal.

GitHub App eventos do webhook

Você pode usar parâmetros de consulta para habilitar o GitHub App webhook, designar uma URL de webhook e assinar o aplicativo para receber cargas de webhook para eventos específicos.

Para habilitar o GitHub App webhook, use webhook_active=true na cadeia de caracteres 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 GitHub App permissões necessárias para assinar cada evento, consulte Eventos e cargas de webhook.

Por exemplo, para assinar um GitHub App conteúdo de webhook para atividades relacionadas a comentários de confirmação, a cadeia de caracteres de consulta incluiria &webhook_active=true&webhook_url=https://example.com&events[]=commit_comment. Observe que o evento de webhook commit_comment exige que GitHub App tenha, no mínimo, acesso de leitura na permissão de repositório "Contents". 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, consulte GitHub as permissões do aplicativo.

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 seu webhook, o valor do segredo deve ser definido na interface GitHub pela pessoa que registra o aplicativo.

Para obter mais informações sobre webhooks e GitHub Apps, consulte Usando webhooks com aplicativos GitHub.