Sobre o aplicativo

Os aplicativos no GitHub permitem que você automatize e melhore seu fluxo de trabalho. Crie aplicativos para aprimorar seu fluxo de trabalho. Você também pode compartilhar ou vender aplicativos no GitHub Marketplace. Para saber como listar um aplicativo no GitHub Marketplace, confira "About GitHub Marketplace".

Aplicativos do GitHub são a forma oficialmente recomendada de se integrar ao GitHub, porque eles oferecem muito mais permissões granulares para acessar dados, mas o GitHub é compatível com OAuth Apps e GitHub Apps. Para obter informações sobre como escolher um tipo de aplicativo, confira "Diferenças entre Aplicativos do GitHub e Aplicativos OAuth".

Se você estiver usando seu aplicativo com o GitHub Actions e quiser modificar arquivos de fluxo de trabalho, precisará se autenticar em nome do usuário com um token OAuth que inclua o escopo workflow. O usuário deve ter permissão de administrador ou permissão de gravação no repositório que contém o arquivo do fluxo de trabalho. Para obter mais informações, confira "Scopes for OAuth Apps".

Para ver um passo a passo do processo de criação de um GitHub App, confira "Usar a API do GitHub no seu aplicativo".

Sobre os GitHub Apps

GitHub Apps são atores de primeira classe no GitHub. Um GitHub App age em seu próprio nome, tomando ações por meio da API diretamente usando sua própria identidade, o que significa que você não precisa manter um bot ou conta de serviço como um usuário separado.

O GitHub Apps pode ser instalado diretamente em organizações e contas pessoais e conceder acesso a repositórios específicos. Eles vêm com webhooks integrados e permissões específicas e restritas. Ao configurar o GitHub App, você pode selecionar os repositórios que deseja que ele acesse. Por exemplo, você pode configurar um aplicativo chamado MyGitHub que grava os problemas no repositório octocat e apenas no repositório octocat. Para instalar um GitHub App, você deve ser o proprietário de uma organização ou ter permissões de administrador em um repositório.

Por padrão, somente proprietários da organização podem gerenciar as configurações dos aplicativos GitHub em uma organização. Para permitir que usuários adicionais alterem as configurações de desenvolvedor dos aplicativos GitHub pertencentes à organização, um proprietário pode conceder a eles permissões de gerente do aplicativo GitHub. Os gerentes de aplicativos GitHub não podem gerenciar aplicativos de terceiros. Para saber como adicionar e remover gerentes de aplicativos GitHub em sua organização, confira "Gerentes de aplicativos GitHub".

GitHub Apps são aplicativos que devem ser hospedados em algum lugar. Para obter instruções passo a passo que abrangem servidores e hospedagem, confira "Usar a API do GitHub no seu aplicativo".

Para melhorar seu fluxo de trabalho, você pode criar um GitHub App que contém vários scripts ou um aplicativo inteiro e, em seguida, conectar esse aplicativo a muitas outras ferramentas. Por exemplo, você pode conectar GitHub Apps ao GitHub, Slack, ou a outros aplicativos que você pode ter, programas de e-mail ou outras APIs.

Tenha isso em mente ao criar GitHub Apps:

• Um usuário ou uma organização pode ser o proprietário de até 100 Aplicativos do GitHub.

• Um GitHub App deve executar ações independentemente de um usuário (a menos que o aplicativo esteja usando um token de acesso de usuário). Para manter tokens de acesso do usuário mais seguros, você pode usar tokens de acesso que expiram após 8 horas, e um token de atualização que pode ser trocado por um novo token de acesso. Para obter mais informações, confira "Atualizar tokens de acesso do usuário".

• Certifique-se de que o GitHub App integre repositórios específicos.

• O GitHub App deve conectar-se a uma conta pessoal ou organização.

• Não espere que o GitHub App saiba e faça tudo o que um usuário pode fazer.

• Não use GitHub App, se você precisa apenas de um serviço de "Login com GitHub". Mas um GitHub App pode gerar um token de acesso de usuário para fazer logon dos usuários e executar outras ações.

• Não crie um GitHub App se você quiser apenas atuar como um usuário do GitHub e fazer tudo o que o usuário pode fazer.

• Se você estiver usando seu aplicativo com o GitHub Actions e quiser modificar arquivos de fluxo de trabalho, precisará se autenticar em nome do usuário com um token OAuth que inclua o escopo workflow. O usuário deve ter permissão de administrador ou permissão de gravação no repositório que contém o arquivo do fluxo de trabalho. Para obter mais informações, confira "Scopes for OAuth Apps".

Para começar a desenvolver GitHub Apps, comece com "Criar um aplicativo GitHub". Para saber como usar os Manifestos do GitHub App, que permitem que as pessoas criem GitHub Apps pré-configurados, confira "Criar um aplicativo do GitHub a partir de um manifesto".

Sobre OAuth Apps

OAuth2 é um protocolo que permite que os aplicativos externos solicitem autorização para detalhes privados na conta GitHub de um usuário sem acessar sua senha. Isto é preferido em relação à autenticação básica, porque os tokens podem ser limitados a tipos específicos de dados e podem ser revogados pelos usuários a qualquer momento.

Um OAuth App usa GitHub como um provedor de identidade para efetuar a autenticação como o usuário que concede acesso ao aplicativo. Isso significa que, quando um usuário permite acesso ao OAuth App, ele concede permissões a todos os repositórios aos quais ele tem acesso na conta e a todas as organizações às quais ele pertence que não bloquearam o acesso de terceiros.

Construir um OAuth App é uma boa opção se você estiver criando processos mais complexos do que um simples script pode gerenciar. Note que OAuth Apps são aplicativos que precisam ser hospedados em algum lugar.

Tenha isso em mente ao criar OAuth Apps:

• Um usuário ou uma organização pode ser o proprietário de até 100 aplicativos OAuth.
• Um OAuth App deve sempre atuar como o usuário autenticado GitHub em todo o GitHub (por exemplo, ao fornecer notificações de usuário).
• Um OAuth App pode ser usado como um provedor de identidade, habilitando um "Login com GitHub" para o usuário autenticado.
• Não crie um OAuth App, se desejar que seu aplicativo atue em um único repositório. Com o escopo repo do OAuth, os OAuth Apps podem atuar em todos os repositórios do usuário autenticado.
• Não crie um OAuth App para atuar como um aplicativo para sua equipe ou empresa. OAuth Apps efetua a autenticação como um usuário único. Portanto se uma pessoa criar um OAuth App para uma empresa usar e, posteriormente, sair da empresa, ninguém mais terá acesso.
• Se você estiver usando seu Aplicativo OAuth com o GitHub Actions e quiser modificar arquivos de fluxo de trabalho, o token OAuth precisará ter o escopo workflow e o usuário precisará ter permissão de proprietário ou de gravação no repositório que contém o arquivo de fluxo de trabalho. Para obter mais informações, confira "Scopes for OAuth Apps".

Para obter mais informações sobre OAuth Apps, confira "Criar um aplicativo OAuth" e "Autenticação na API REST com um aplicativo OAuth".

Personal access tokens

Um personal access token é uma cadeia de caracteres que funciona de maneira semelhante a um token OAuth, no qual você pode especificar as permissões por meio de escopos. Um personal access token também é semelhante a uma senha, mas você pode ter várias delas e revogar o acesso a cada uma a qualquer momento.

Como exemplo, você pode habilitar um personal access token a ser gravado nos repositórios. Se você executar um comando curl ou escrever um script que crie um problema em seu repositório, deverá passar o personal access token para autenticar. Você pode armazenar o personal access token como uma variável de ambiente para evitar precisar digitá-lo a cada uso.

Considere o seguinte ao usar personal access tokens:

• Lembre-se de usar este token para representar apenas você.
• Você pode realizar solicitações curl pontuais.
• Você pode executar scripts pessoais.
• Não configure um script para toda a sua equipe ou empresa usá-lo.
• Não configure uma conta pessoal compartilhada para atuar como um usuário de bot.
• Conceda ao token os privilégios mínimos necessários.
• Defina uma expiração para os personal access tokens, para manter suas informações seguras.

Determinar qual integração criar

Antes de começar a criar integrações, você deverá determinar a melhor maneira de acessar autenticar e interagir com as APIs de GitHub.

Para decidir se vai usar personal access token, GitHub Apps ou OAuth Apps em sua integração, considere estas perguntas sobre como a integração precisa se comportar e o que ela precisa acessar:

• A minha integração funcionará apenas como eu ou será mais como um aplicativo?
• Quero que ela aja independentemente de mim com sua própria entidade?
• Ela irá acessar tudo o que eu puder acessar ou eu quero limitar seu acesso?
• É simples ou complexo? Por exemplo, personal access tokens são bons para scripts e comandos curl simples, já um OAuth App pode lidar com scripts mais complexos.

Se a integração funcionar somente como você, mas você quiser limitar o acesso, use um GitHub App ou um fine-grained personal access token.

Se a integração funcionar mais como um aplicativo, considere se quer que ela atue independentemente de você com uma entidade própria. Nesse caso, use um GitHub App.

Solicitar suporte

Em caso de dúvidas, relatórios de bug e discussões sobre o GitHub Apps, o OAuth Apps e o desenvolvimento de API, explore o Discussões sobre APIs e integrações na Comunidade do GitHub. As discussões são moderadas e mantidas pela equipe do GitHub, mas não é garantido que as perguntas publicadas no fórum recebam uma resposta da equipe do GitHub.

Considere a possibilidade de entrar em contato diretamente com o Suporte do GitHub usando o formulário de contato para:

• resposta garantida dos funcionários de GitHub Enterprise Cloud
• solicitações de suporte que envolvem dados confidenciais ou questões privadas
• solicitações de recursos
• feedback sobre produtos de GitHub Enterprise Cloud