About apps

You can build integrations with the GitHub Enterprise Server APIs to add flexibility and reduce friction in your own workflow.

Apps on GitHub allow you to automate and improve your workflow. You can build apps to improve your workflow.

GitHub 应用程序是官方推荐的与 GitHub 集成的方式,因为它们提供更精细的数据访问权限, but GitHub supports both OAuth 应用程序 and GitHub 应用程序. For information on choosing a type of app, see "Differences between GitHub Apps and OAuth Apps."

For a walkthrough of the process of building a GitHub 应用程序, see "Building Your First GitHub 应用程序."

About GitHub 应用程序

GitHub 应用程序 are first-class actors within GitHub. A 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.

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 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 GitHub 应用程序, you must be an organization owner or have admin permissions in a repository.

默认情况下,只有组织所有者才可管理组织中 GitHub 的设置。 要允许其他用户管理组织中的 GitHub 应用程序,所有者可以向他们授予 GitHub 应用程序管理员权限。 请参阅“GitHub 应用程序”,了解如何在组织中添加和删除 GitHub 应用程序管理员。

GitHub 应用程序 are applications that need to be hosted somewhere. For step-by-step instructions that cover servers and hosting, see "Building Your First GitHub 应用程序."

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

Keep these ideas in mind when creating GitHub 应用程序:

  • A GitHub 应用程序 should take actions independent of a user (unless the app is using a user-to-server token). 为使用户到服务器的访问令牌更安全,您可以使用将在 8 小时后过期的访问令牌,以及可交换新访问令牌的刷新令牌。 更多信息请参阅“刷新用户到服务器访问令牌”。

  • Make sure the GitHub 应用程序 integrates with specific repositories.

  • The GitHub 应用程序 should connect to a personal account or an organization.

  • Don't expect the GitHub 应用程序 to know and do everything a user can.

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

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

To begin developing GitHub 应用程序, start with "Creating a GitHub 应用程序."

About 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.

警告: 从 OAuth 应用程序 撤销所有权限将会删除应用程序代表用户生成的 SSH 密钥,包括部署密钥

An 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 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 OAuth 应用程序 is a good option if you are creating more complex processes than a simple script can handle. Note that OAuth 应用程序 are applications that need to be hosted somewhere.

Keep these ideas in mind when creating OAuth 应用程序:

  • An OAuth 应用程序 should always act as the authenticated GitHub user across all of GitHub (for example, when providing user notifications).
  • An OAuth 应用程序 can be used as an identity provider by enabling a "Login with GitHub" for the authenticated user.
  • Don't build an OAuth 应用程序 if you want your application to act on a single repository. With the repo OAuth scope, OAuth 应用程序 can act on all of the authenticated user's repositories.
  • Don't build an OAuth 应用程序 to act as an application for your team or company. OAuth 应用程序 authenticate as a single user, so if one person creates an OAuth 应用程序 for a company to use, and then they leave the company, no one else will have access to it.

For more on OAuth 应用程序, see "Creating an 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.

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 Enterprise Server APIs. The following image offers some questions to ask yourself when deciding whether to use personal access tokens, GitHub 应用程序, or 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 OAuth 应用程序 can handle more complex scripting.

Requesting support

有关 GitHub 应用程序、OAuth 应用程序 和 API 开发的问题、漏洞报告和讨论,请访问 GitHub API 开发和支持论坛。 该论坛由 GitHub 工作人员管理和维护,但不能保证发布到论坛的问题都会得到 GitHub 工作人员的回复。

对于以下问题,请考虑使用联系表直接联系 GitHub Support

  • 要保证得到 GitHub Enterprise Server 工作人员的回应
  • 涉及敏感数据或私人问题的支持请求
  • 功能请求
  • 关于 GitHub Enterprise Server 产品的反馈

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。