About apps

You can build integrations with the GitHub APIs to add flexibility and reduce friction in your own workflow. You can also share integrations with others on GitHub Marketplace.

Apps on GitHub allow you to automate and improve your workflow. You can build apps to improve your workflow. You can also share or sell apps in GitHub Marketplace. To learn how to list an app on GitHub Marketplace, see "Getting started with 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, but GitHub supports both Aplicativos OAuth and Aplicativos do GitHub. For information on choosing a type of app, see "Differences between GitHub Apps and OAuth Apps."

Se você estiver usando seu aplicativo com o GitHub Actions e deseja modificar os arquivos de fluxo de trabalho, você deve 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, consulte "Understanding scopes for OAuth apps."

For a walkthrough of the process of building a aplicativo GitHub, see "Building Your First aplicativo GitHub."

About Aplicativos do GitHub

Aplicativos do GitHub are first-class actors within GitHub. A aplicativo GitHub acts on its own behalf, taking actions via the API directly using its own identity, which means you don't need to maintain a bot or service account as a separate user.

Aplicativos do GitHub can be installed directly on organizations and user accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions. When you set up your aplicativo GitHub, you can select the repositories you want it to access. For example, you can set up an app called MyGitHub that writes issues in the octocat repository and only the octocat repository. To install a aplicativo GitHub, you must be an organization owner or have admin permissions in a repository.

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 gerenciem os Aplicativos GitHub em uma organização, um proprietário pode conceder-lhes permissões de gerente de aplicativos do GitHub. Veja "GitHub App Managers" para saber como adicionar e remover gerentes do GitHub App em sua organização.

Aplicativos do GitHub are applications that need to be hosted somewhere. For step-by-step instructions that cover servers and hosting, see "Building Your First aplicativo GitHub."

To improve your workflow, you can create a aplicativo GitHub that contains multiple scripts or an entire application, and then connect that app to many other tools. For example, you can connect Aplicativos do GitHub to GitHub, Slack, other in-house apps you may have, email programs, or other APIs.

Keep these ideas in mind when creating Aplicativos do GitHub:

  • um usuário ou organização pode ter até 100 aplicativos no GitHub Apps.

  • A aplicativo GitHub should take actions independent of a user (unless the app is using a user-to-server token). Para manter tokens de acesso do usuário para servidor 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 mais informação, consulte "Refreshing user-to-server access tokens."

  • Make sure the aplicativo GitHub integrates with specific repositories.

  • The aplicativo GitHub should connect to a personal account or an organization.

  • Don't expect the aplicativo GitHub to know and do everything a user can.

  • Don't use a aplicativo GitHub if you just need a "Login with GitHub" service. But a aplicativo GitHub can use a user identification flow to log users in and do other things.

  • Don't build a aplicativo GitHub if you only want to act as a GitHub user and do everything that user can do.

  • Se você estiver usando seu aplicativo com o GitHub Actions e deseja modificar os arquivos de fluxo de trabalho, você deve 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, consulte "Understanding scopes for OAuth apps."

To begin developing Aplicativos do GitHub, start with "Creating a aplicativo GitHub." To learn how to use aplicativo GitHub Manifests, which allow people to create preconfigured Aplicativos do GitHub, see "Creating Aplicativos do GitHub from a manifest."

About Aplicativos OAuth

OAuth2 is a protocol that lets external applications request authorization to private details in a user's GitHub account without accessing their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data and can be revoked by users at any time.

Warning: Revogar todas as permissões de um aplicativo OAuth exclui quaisquer chaves SSH geradas pelo aplicativo em nome do usuário, incluindo deploy keys.

An aplicativo OAuth uses GitHub as an identity provider to authenticate as the user who grants access to the app. This means when a user grants an aplicativo OAuth access, they grant permissions to all repositories they have access to in their account, and also to any organizations they belong to that haven't blocked third-party access.

Building an aplicativo OAuth is a good option if you are creating more complex processes than a simple script can handle. Note that Aplicativos OAuth are applications that need to be hosted somewhere.

Keep these ideas in mind when creating Aplicativos OAuth:

  • um usuário ou organização pode ter até 100 aplicativos no GitHub Apps.
  • An aplicativo OAuth should always act as the authenticated GitHub user across all of GitHub (for example, when providing user notifications).
  • An aplicativo OAuth can be used as an identity provider by enabling a "Login with GitHub" for the authenticated user.
  • Don't build an aplicativo OAuth if you want your application to act on a single repository. With the repo OAuth scope, Aplicativos OAuth can act on all of the authenticated user's repositories.
  • Don't build an aplicativo OAuth to act as an application for your team or company. Aplicativos OAuth authenticate as a single user, so if one person creates an aplicativo OAuth for a company to use, and then they leave the company, no one else will have access to it.
  • se você estiver usando seu aplicativo OAuth com o GitHub Actions e quiser modificar os arquivos de fluxo de trabalho, seu token OAuth deve ter o escopo workflow e o usuário deve ter permissão de proprietário ou de escrita no repositório que contém o arquivo de fluxo de trabalho. Para obter mais informações, consulte "Understanding scopes for OAuth apps."

For more on Aplicativos OAuth, see "Creating an aplicativo OAuth" and "Registering your app."

Personal access tokens

A personal access token is a string of characters that functions similarly to an OAuth token in that you can specify its permissions via scopes. A personal access token is also similar to a password, but you can have many of them and you can revoke access to each one at any time.

As an example, you can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that creates an issue in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it.

Keep these ideas in mind when using personal access tokens:

  • Remember to use this token to represent yourself only.
  • You can perform one-off cURL requests.
  • You can run personal scripts.
  • Don't set up a script for your whole team or company to use.
  • Don't set up a shared user account to act as a bot user.
  • Do set an expiration for your personal access tokens, to help keep your information secure.

Determining which integration to build

Before you get started creating integrations, you need to determine the best way to access, authenticate, and interact with the GitHub APIs. The following image offers some questions to ask yourself when deciding whether to use personal access tokens, Aplicativos do GitHub, or Aplicativos OAuth for your integration.

Intro to apps question flow

Consider these questions about how your integration needs to behave and what it needs to access:

  • Will my integration act only as me, or will it act more like an application?
  • Do I want it to act independently of me as its own entity?
  • Will it access everything that I can access, or do I want to limit its access?
  • Is it simple or complex? For example, personal access tokens are good for simple scripts and cURLs, whereas an aplicativo OAuth can handle more complex scripting.

Requesting support

For questions, bug reports, and discussions about Aplicativos do GitHub, Aplicativos OAuth, and API development, explore the Fórum de Suporte e Desenvolvimento de API GitHub. O fórum é moderado e mantido por funcionários de GitHub, mas as dúvidas postadas no fórum não têm garantia de recebimento de resposta por parte dos funcionários de GitHub.

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

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

Esse documento ajudou você?

Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.