# Registrando um aplicativo GitHub usando parâmetros de URL Você pode usar parâmetros de consulta de URL para ajudar outras pessoas a configurar rapidamente um novo GitHub App com uma configuração específica pré-selecionada. ## 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](/pt/enterprise-server@3.22/apps/sharing-github-apps/registering-a-github-app-from-a-manifest). ## 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: ```text 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](/pt/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url). | | `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](/pt/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/about-the-setup-url). | | `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](#github-app-webhook-events). 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](/pt/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app). Para ver a lista de permissões disponíveis para uso e seus nomes parametrizados, confira [Gerenciar seus tokens de acesso pessoal](/pt/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#account-permissions). ## 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](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads). 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](#github-app-permissions). 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](/pt/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps).