jprdonnelly/docs
1
0
Fork 0
mirror of synced 2026-01-03 06:04:16 -05:00
Code Issues Projects Releases Wiki Activity

Merge pull request #25193 from github/repo-sync

Browse Source 
repo sync
This commit is contained in:
Octomerger Bot
2023-04-24 14:02:30 -04:00
committed by GitHub
parent 21d0dbfbf9 1f46d5f0f3
commit 2a64f4fb85
44 changed files with 166 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/actions/creating-actions/about-custom-actions.md
View File

@@ -153,7 +153,7 @@ We recommend creating a README file to help people learn how to use your action.
## Comparing {% data variables.product.prodname_actions %} to {% data variables.product.prodname_github_apps %}
{% data variables.product.prodname_marketplace %} offers tools to improve your workflow. Understanding the differences and the benefits of each tool will allow you to select the best tool for your job. For more information about building apps, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)."
{% data variables.product.prodname_marketplace %} offers tools to improve your workflow. Understanding the differences and the benefits of each tool will allow you to select the best tool for your job. For more information about building apps, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-apps)."
### Strengths of GitHub Actions and GitHub Apps

8
content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md
View File

@@ -19,7 +19,7 @@ For example, if you want your app to change the `Status` field of an issue on a
To make an API request as an installation, you must first generate an installation access token. Then, you will send the installation access token in the `Authorization` header of your subsequent API requests. You can also use {% data variables.product.company_short %}'s Octokit SDKs, which can generate an installation access token for you.
If a REST API endpoint works with a {% data variables.product.prodname_github_app %} installation access token, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." Additionally, your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
If a REST API endpoint works with a {% data variables.product.prodname_github_app %} installation access token, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." Additionally, your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test you app to ensure that your app has the required permissions for the GraphQL queries and mutations that you want to make.
@@ -41,7 +41,7 @@ To authenticate as an installation with an installation access token, first use
To authenticate with an installation access token, include it in the `Authorization` header of an API request. The access token will work with both the GraphQL API and the REST API.
Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
In the following example, replace `INSTALLATION_ACCESS_TOKEN` with an installation access token:
@@ -91,7 +91,7 @@ You must install and import `octokit` in order to use the Octokit.js library. Th
1. Use an `octokit` method to make a request to the API.
Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
For example, to make a request to the GraphQL API:
@@ -117,7 +117,7 @@ The Octokit.js SDK also passes a pre-authenticated `octokit` instance to webhook
1. Get the ID of your app. You can find your app's ID on the settings page for your app. For user-owned apps, the settings page is `https://github.com/settings/apps/APP-SLUG`. For organization-owned apps, the settings page is `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`. Replace `APP-SLUG` with the slugified name of your app. Replace `ORGANIZATION` with the slugified name of your organization. For example, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
1. Generate a private key. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)".
1. Get the webhook secret that you specified in your app's settings. For more information about webhook secrets, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps#securing-your-webhooks-with-a-webhook-secret)."
1. Get the webhook secret that you specified in your app's settings. For more information about webhook secrets, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps#securing-your-webhooks-with-a-webhook-secret)."
1. Import `App` from `octokit`. Create a new instance of `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `WEBHOOK_SECRET` with the your app's webhook secret.
```javascript{:copy}

2
content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md
View File

@@ -19,7 +19,7 @@ A user access token is a type of OAuth token. Unlike a traditional OAuth token,
Similarly, a user access token can only access resources that both the user and app can access. For example, if an app is granted access to repository `A` and `B`, and the user can access repository `B` and `C`, the user access token can access repository `B` but not `A` or `C`. You can use the REST API to check which installations and which repositories within an installation a user access token can access. For more information, see `GET /user/installations` and `GET /user/installations/{installation_id}/repositories` in "[AUTOTITLE](/rest/apps/installations)."
When you make API requests with a user access token, the rate limits for user access tokens apply. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps)."
When you make API requests with a user access token, the rate limits for user access tokens apply. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps)."
By default, the user access token expires after 8 hours. You can use a refresh token to regenerate a user access token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)."

2
content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md
View File

@@ -31,7 +31,7 @@ If your refresh token expires before you use it, you can regenerate a user acces
## Configuring your app to use user access tokens that expire
When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." You can also configure this setting after your app has been created.
When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." You can also configure this setting after your app has been created.
{% data reusables.apps.settings-step %}
{% data reusables.user-settings.developer_settings %}

108
content/apps/creating-github-apps/guides/building-a-cli-with-a-github-app.md
View File

@@ -33,7 +33,7 @@ There are two ways to generate a user access token for a {% data variables.produ
## Prerequisites
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
Before following this tutorial, you must enable device flow for your app. For more information about enabling device flow for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
@@ -183,7 +183,7 @@ These steps lead you through building a CLI and using device flow to get a user
def help
puts "usage: app_cli <help>"
end
def main
case ARGV[0]
when "help"
@@ -238,7 +238,7 @@ The `login` command will run the device flow to get a user access token. For mor
uri = URI("{% data variables.product.oauth_host_code %}/login/device/code")
parameters = URI.encode_www_form("client_id" => CLIENT_ID)
headers = {"Accept" => "application/json"}
response = Net::HTTP.post(uri, parameters, headers)
parse_response(response)
end
@@ -264,11 +264,11 @@ The `login` command will run the device flow to get a user access token. For mor
```ruby{:copy}
def poll_for_token(device_code, interval)
loop do
response = request_token(device_code)
error, access_token = response.values_at("error", "access_token")
if error
case error
when "authorization_pending"
@@ -294,12 +294,12 @@ The `login` command will run the device flow to get a user access token. For mor
exit 1
end
end
File.write("./.token", access_token)
# Set the file permissions so that only the file owner can read or modify the file
FileUtils.chmod(0600, "./.token")
break
end
end
@@ -317,12 +317,12 @@ The `login` command will run the device flow to get a user access token. For mor
```ruby{:copy}
def login
verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")
puts "Please visit: #{verification_uri}"
puts "and enter code: #{user_code}"
poll_for_token(device_code, interval)
puts "Successfully authenticated!"
end
```
@@ -358,18 +358,18 @@ The `login` command will run the device flow to get a user access token. For mor
```ruby{:copy}
#!/usr/bin/env ruby
require "net/http"
require "json"
require "uri"
require "fileutils"
CLIENT_ID="YOUR_CLIENT_ID"
def help
puts "usage: app_cli <login | help>"
end
def main
case ARGV[0]
when "help"
@@ -382,7 +382,7 @@ The `login` command will run the device flow to get a user access token. For mor
puts "Unknown command #{ARGV[0]}"
end
end
def parse_response(response)
case response
when Net::HTTPOK, Net::HTTPCreated
@@ -393,16 +393,16 @@ The `login` command will run the device flow to get a user access token. For mor
exit 1
end
end
def request_device_code
uri = URI("{% data variables.product.oauth_host_code %}/login/device/code")
parameters = URI.encode_www_form("client_id" => CLIENT_ID)
headers = {"Accept" => "application/json"}
response = Net::HTTP.post(uri, parameters, headers)
parse_response(response)
end
def request_token(device_code)
uri = URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token")
parameters = URI.encode_www_form({
@@ -414,13 +414,13 @@ The `login` command will run the device flow to get a user access token. For mor
response = Net::HTTP.post(uri, parameters, headers)
parse_response(response)
end
def poll_for_token(device_code, interval)
loop do
response = request_token(device_code)
error, access_token = response.values_at("error", "access_token")
if error
case error
when "authorization_pending"
@@ -446,27 +446,27 @@ The `login` command will run the device flow to get a user access token. For mor
exit 1
end
end
File.write("./.token", access_token)
# Set the file permissions so that only the file owner can read or modify the file
FileUtils.chmod(0600, "./.token")
break
end
end
def login
verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")
puts "Please visit: #{verification_uri}"
puts "and enter code: #{user_code}"
poll_for_token(device_code, interval)
puts "Successfully authenticated!"
end
main
```
@@ -501,10 +501,10 @@ Now that your app can generate a user access token, you can make API requests on
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
body = {"access_token" => token}.to_json
headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}
http.send_request("GET", uri.path, body, headers)
end
parsed_response = parse_response(response)
puts "You are #{parsed_response["login"]}"
end
@@ -561,18 +561,18 @@ This is the full code example that was outlined in the previous section. Replace
```ruby{:copy}
#!/usr/bin/env ruby
require "net/http"
require "json"
require "uri"
require "fileutils"
CLIENT_ID="YOUR_CLIENT_ID"
def help
puts "usage: app_cli <login | whoami | help>"
end
def main
case ARGV[0]
when "help"
@@ -585,7 +585,7 @@ This is the full code example that was outlined in the previous section. Replace
puts "Unknown command #{ARGV[0]}"
end
end
def parse_response(response)
case response
when Net::HTTPOK, Net::HTTPCreated
@@ -599,16 +599,16 @@ This is the full code example that was outlined in the previous section. Replace
exit 1
end
end
def request_device_code
uri = URI("{% data variables.product.oauth_host_code %}/login/device/code")
parameters = URI.encode_www_form("client_id" => CLIENT_ID)
headers = {"Accept" => "application/json"}
response = Net::HTTP.post(uri, parameters, headers)
parse_response(response)
end
def request_token(device_code)
uri = URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token")
parameters = URI.encode_www_form({
@@ -620,13 +620,13 @@ This is the full code example that was outlined in the previous section. Replace
response = Net::HTTP.post(uri, parameters, headers)
parse_response(response)
end
def poll_for_token(device_code, interval)
loop do
response = request_token(device_code)
error, access_token = response.values_at("error", "access_token")
if error
case error
when "authorization_pending"
@@ -652,24 +652,24 @@ This is the full code example that was outlined in the previous section. Replace
exit 1
end
end
File.write("./.token", access_token)
# Set the file permissions so that only the file owner can read or modify the file
FileUtils.chmod(0600, "./.token")
break
end
end
def login
verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")
puts "Please visit: #{verification_uri}"
puts "and enter code: #{user_code}"
poll_for_token(device_code, interval)
puts "Successfully authenticated!"
end
@@ -686,14 +686,14 @@ This is the full code example that was outlined in the previous section. Replace
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
body = {"access_token" => token}.to_json
headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}
http.send_request("GET", uri.path, body, headers)
end
parsed_response = parse_response(response)
puts "You are #{parsed_response["login"]}"
end
main
```
@@ -741,7 +741,7 @@ This tutorial assumes that your app code is stored in a file named `app_cli.rb`.
### Adjust the code to meet your app's needs
This tutorial demonstrated how to write a CLI that uses the device flow to generate a user access token. You can expand this CLI to accept additional commands. For example, you can add a `create-issue` command that opens an issue. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps)."
This tutorial demonstrated how to write a CLI that uses the device flow to generate a user access token. You can expand this CLI to accept additional commands. For example, you can add a `create-issue` command that opens an issue. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
### Securely store tokens

46
content/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app.md
View File

@@ -27,9 +27,9 @@ There are two ways to generate a user access token for a {% data variables.produ
## Prerequisites
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
Before following this tutorial, you must set a callback URL for your app. This tutorial uses a local Sinatra server with the default URL of `http://localhost:4567`. For example, to work with the default URL for a local Sinatra application, your callback URL can be `http://localhost:4567/github/callback`. Once you are ready to deploy your app, you can change the callback URL to use your live server address. For more information about updating the callback URL for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)."
Before following this tutorial, you must set a callback URL for your app. This tutorial uses a local Sinatra server with the default URL of `http://localhost:4567`. For example, to work with the default URL for a local Sinatra application, your callback URL can be `http://localhost:4567/github/callback`. Once you are ready to deploy your app, you can change the callback URL to use your live server address. For more information about updating the callback URL for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)."
This tutorial assumes that you have a basic understanding of Ruby and of the Ruby template system, ERB. For more information, see [Ruby](https://www.ruby-lang.org) and [ERB](https://github.com/ruby/erb).
@@ -144,10 +144,10 @@ These steps lead you through writing code to generate a user access token. To sk
require "dotenv/load"
require "net/http"
require "json"
CLIENT_ID = ENV.fetch("CLIENT_ID")
CLIENT_SECRET = ENV.fetch("CLIENT_SECRET")
get "/" do
link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>'
erb link
@@ -183,10 +183,10 @@ These steps lead you through writing code to generate a user access token. To sk
require "dotenv/load"
require "net/http"
require "json"
CLIENT_ID = ENV.fetch("CLIENT_ID")
CLIENT_SECRET = ENV.fetch("CLIENT_SECRET")
def parse_response(response)
case response
when Net::HTTPOK
@@ -197,7 +197,7 @@ These steps lead you through writing code to generate a user access token. To sk
{}
end
end
def exchange_code(code)
params = {
"client_id" => CLIENT_ID,
@@ -209,23 +209,23 @@ These steps lead you through writing code to generate a user access token. To sk
URI.encode_www_form(params),
{"Accept" => "application/json"}
)
parse_response(result)
end
get "/" do
link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>'
erb link
end
get "CALLBACK_URL" do
code = params["code"]
token_data = exchange_code(code)
if token_data.key?("access_token")
token = token_data["access_token"]
render = "Successfully authorized! Got code #{code} and exchanged it for a user access token ending in #{token[-9..-1]}."
erb render
else
@@ -250,16 +250,16 @@ These steps lead you through writing code to generate a user access token. To sk
```ruby{:copy}
def user_info(token)
uri = URI("{% data variables.product.api_url_code %}/user")
result = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
body = {"access_token" => token}.to_json
auth = "Bearer #{token}"
headers = {"Accept" => "application/json", "Content-Type" => "application/json", "Authorization" => auth}
http.send_request("GET", uri.path, body, headers)
end
parse_response(result)
end
```
@@ -269,16 +269,16 @@ These steps lead you through writing code to generate a user access token. To sk
```ruby{:copy}
get "CALLBACK_URL" do
code = params["code"]
token_data = exchange_code(code)
if token_data.key?("access_token")
token = token_data["access_token"]
user_info = user_info(token)
handle = user_info["login"]
name = user_info["name"]
render = "Successfully authorized! Welcome, #{name} (#{handle})."
erb render
else
@@ -397,7 +397,7 @@ For example, you can store the secret in an environment variable on the server w
### Update the callback URL for deployment
This tutorial used a callback URL starting with `http://localhost:4567`. However, `http://localhost:4567` is only available locally to your computer when you start the Sinatra server. Before you deploy your app, you should update the callback URL to use the callback URL that you use in production. For more information about updating the callback URL for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)."
This tutorial used a callback URL starting with `http://localhost:4567`. However, `http://localhost:4567` is only available locally to your computer when you start the Sinatra server. Before you deploy your app, you should update the callback URL to use the callback URL that you use in production. For more information about updating the callback URL for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)."
### Handle multiple callback URLs
@@ -415,7 +415,7 @@ Unlike a traditional OAuth token, the user access token does not use scopes so y
### Adjust the code to meet your app's needs
This tutorial demonstrated how to display information about the authenticated user, but you can adjust this code to take other actions. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps)."
This tutorial demonstrated how to display information about the authenticated user, but you can adjust this code to take other actions. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
This tutorial stored all of the code into a single file, but you may want to move functions and components into separate files.

16
content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md
View File

@@ -20,13 +20,13 @@ This article provides guidelines for existing integrators who are considering mi
[GitHub Apps](/apps) are the officially recommended way to integrate with GitHub because they offer many advantages over a pure OAuth-based integration:
- [Fine-grained permissions](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#requesting-permission-levels-for-resources) target the specific information a GitHub App can access, allowing the app to be more widely used by people and organizations with security policies than OAuth Apps, which cannot be limited by permissions.
- [Short-lived tokens](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#token-based-identification) provide a more secure authentication method over OAuth tokens. An OAuth token does not expire until the person who authorized the OAuth App revokes the token. GitHub Apps use tokens that expire quickly, creating a much smaller window of time for compromised tokens to be in use.
- [Built-in, centralized webhooks](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#webhooks) receive events for all repositories and organizations the app can access. Conversely, OAuth Apps require configuring a webhook for each repository and organization accessible to the user.
- [Bot accounts](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts) don't consume a {% data variables.product.product_name %} seat and remain installed even when the person who initially installed the app leaves the organization.
- [Fine-grained permissions](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#requesting-permission-levels-for-resources) target the specific information a GitHub App can access, allowing the app to be more widely used by people and organizations with security policies than OAuth Apps, which cannot be limited by permissions.
- [Short-lived tokens](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#token-based-identification) provide a more secure authentication method over OAuth tokens. An OAuth token does not expire until the person who authorized the OAuth App revokes the token. GitHub Apps use tokens that expire quickly, creating a much smaller window of time for compromised tokens to be in use.
- [Built-in, centralized webhooks](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#webhooks) receive events for all repositories and organizations the app can access. Conversely, OAuth Apps require configuring a webhook for each repository and organization accessible to the user.
- [Bot accounts](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts) don't consume a {% data variables.product.product_name %} seat and remain installed even when the person who initially installed the app leaves the organization.
- Built-in support for OAuth is still available to GitHub Apps using [endpoints with a user access token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps).
- Dedicated [API rate limits](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps) for bot accounts scale with your integration.
- Repository owners can [install GitHub Apps](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#who-can-install-github-apps-and-authorize-oauth-apps) on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation.
- Dedicated [API rate limits](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps) for bot accounts scale with your integration.
- Repository owners can [install GitHub Apps](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#who-can-install-github-apps-and-authorize-oauth-apps) on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation.
- Open Source community support is available through [Octokit libraries](/rest/overview/libraries) and other frameworks such as [Probot](https://probot.github.io/).
- Integrators building GitHub Apps have opportunities to adopt earlier access to APIs.
@@ -53,11 +53,11 @@ We recommend reviewing the list of API endpoints you need as early as possible.
### Design to stay within API rate limits
GitHub Apps use [sliding rules for rate limits](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest/overview/resources-in-the-rest-api#conditional-requests) or consolidate requests by using the [GraphQL API](/graphql).
GitHub Apps use [sliding rules for rate limits](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest/overview/resources-in-the-rest-api#conditional-requests) or consolidate requests by using the [GraphQL API](/graphql).
### Register a new GitHub App
Once you've decided to make the switch to GitHub Apps, you'll need to [create a new GitHub App](/apps/creating-github-apps/creating-github-apps).
Once you've decided to make the switch to GitHub Apps, you'll need to [create a new GitHub App](/apps/creating-github-apps/setting-up-a-github-app).
### Determine the permissions your app requires

4
content/apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app.md
View File

@@ -38,7 +38,7 @@ Here are the steps you'll take to configure the template GitHub App:
You may find it helpful to have a basic understanding of the following:
* [GitHub Apps](/apps/creating-github-apps/creating-github-apps/about-apps)
* [GitHub Apps](/apps/creating-github-apps/setting-up-a-github-app/about-apps)
* [Webhooks](/webhooks-and-events/webhooks/about-webhooks)
* [The Ruby programming language](https://www.ruby-lang.org/en/)
* [REST APIs](/rest)
@@ -93,7 +93,7 @@ We recommend leaving this Terminal window open and keeping Smee connected while
If you don't yet have a GitHub account, now is a [great time to join](https://github.com/join). Don't forget to verify your email before continuing! To register a new app, visit the [app settings page](https://github.com/settings/apps) in your GitHub profile, and click **New GitHub App**.
You'll see a form where you can enter details about your app. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)" for general information about the fields on this page. For the purposes of this guide, you'll need to enter specific data in a few fields:
You'll see a form where you can enter details about your app. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" for general information about the fields on this page. For the purposes of this guide, you'll need to enter specific data in a few fields:
{% note %}

4
content/apps/creating-github-apps/guides/using-the-github-api-in-your-app.md
View File

@@ -32,7 +32,7 @@ Once you've worked through the steps, you'll be ready to develop other kinds of
You may find it helpful to have a basic understanding of the following:
* [GitHub Apps](/apps/creating-github-apps/creating-github-apps/about-apps)
* [GitHub Apps](/apps/creating-github-apps/setting-up-a-github-app/about-apps)
* [Webhooks](/webhooks-and-events/webhooks/about-webhooks)
* [The Ruby programming language](https://www.ruby-lang.org/en/)
* [REST APIs](/rest)
@@ -190,7 +190,7 @@ You won't see much in the Terminal, _but_ you should see that a bot user has add
{% note %}
**Note:** When GitHub Apps take actions via the API, such as adding labels, GitHub shows these actions as being performed by _bot_ accounts. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts)."
**Note:** When GitHub Apps take actions via the API, such as adding labels, GitHub shows these actions as being performed by _bot_ accounts. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts)."
{% endnote %}

2
content/apps/creating-github-apps/index.md
View File

@@ -9,7 +9,7 @@ versions:
topics:
- GitHub Apps
children:
- /creating-github-apps
- /setting-up-a-github-app
- /authenticating-with-a-github-app
- /guides
redirect_from:

5
content/apps/creating-github-apps/creating-github-apps/about-apps.md → content/apps/creating-github-apps/setting-up-a-github-app/about-apps.md
View File

@@ -8,6 +8,7 @@ redirect_from:
- /apps/about-apps
- /developers/apps/about-apps
- /developers/apps/getting-started-with-apps/about-apps
- /apps/creating-github-apps/creating-github-apps/about-apps
versions:
fpt: '*'
ghes: '*'
@@ -18,7 +19,7 @@ topics:
---
Apps on {% data variables.product.prodname_dotcom %} allow you to automate and improve your workflow. You can build apps to improve your workflow.{% ifversion fpt or ghec %} You can also share or sell apps in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). To learn how to list an app on {% data variables.product.prodname_marketplace %}, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace)."{% endif %}
{% data reusables.marketplace.github_apps_preferred %}, but GitHub supports both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %}. For information on choosing a type of app, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps)."
{% data reusables.marketplace.github_apps_preferred %}, but GitHub supports both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %}. For information on choosing a type of app, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)."
{% data reusables.apps.general-apps-restrictions %}
@@ -49,7 +50,7 @@ Keep these ideas in mind when creating {% data variables.product.prodname_github
* Don't build a {% data variables.product.prodname_github_app %} if you _only_ want to act as a GitHub user and do everything that user can do.{% ifversion fpt or ghec %}
* {% data reusables.apps.general-apps-restrictions %}{% endif %}
To begin developing {% data variables.product.prodname_github_apps %}, start with "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."{% ifversion fpt or ghec %} To learn how to use {% data variables.product.prodname_github_app %} Manifests, which allow people to create preconfigured {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest)."{% endif %}
To begin developing {% data variables.product.prodname_github_apps %}, start with "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."{% ifversion fpt or ghec %} To learn how to use {% data variables.product.prodname_github_app %} Manifests, which allow people to create preconfigured {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)."{% endif %}
## About {% data variables.product.prodname_oauth_apps %}

4
content/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url.md → content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md
View File

@@ -9,6 +9,8 @@ versions:
topics:
- GitHub Apps
shortTitle: Callback URL
redirect_from:
- /apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url
---
When you create a {% data variables.product.prodname_github_app %}, you can specify a callback URL. When you use the web application flow to generate a user access token in order to act on behalf of a user, users will be redirected to the callback URL after they authorize the app.
@@ -17,4 +19,4 @@ You can specify up to 10 callback URLs. If you specify multiple callback URLs, y
The callback URL is different from the setup URL. Users are redirected to the setup URL after they install an app. Users are redirected to the callback URL when they authorize an app via the web application flow.
For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about creating a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about creating a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."

3
content/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app.md → content/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app.md
View File

@@ -9,6 +9,7 @@ redirect_from:
- /developers/apps/setting-permissions-for-github-apps
- /developers/apps/building-github-apps/setting-permissions-for-github-apps
- /apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps
- /apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app
versions:
fpt: '*'
ghes: '*'
@@ -30,7 +31,7 @@ You can modify the permissions for your app at any time. When you modify the per
Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission.
For more information about specifying permissions during app creation, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)."
For more information about specifying permissions during app creation, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)."
## Choosing permissions for webhook access

1
content/apps/creating-github-apps/creating-github-apps/creating-a-custom-badge-for-your-github-app.md → content/apps/creating-github-apps/setting-up-a-github-app/creating-a-custom-badge-for-your-github-app.md
View File

@@ -5,6 +5,7 @@ redirect_from:
- /apps/building-github-apps/creating-custom-badges-for-github-apps
- /developers/apps/creating-a-custom-badge-for-your-github-app
- /developers/apps/building-github-apps/creating-a-custom-badge-for-your-github-app
- /apps/creating-github-apps/creating-github-apps/creating-a-custom-badge-for-your-github-app
versions:
fpt: '*'
ghes: '*'

3
content/apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest.md → content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest.md
View File

@@ -5,6 +5,7 @@ redirect_from:
- /apps/building-github-apps/creating-github-apps-from-a-manifest
- /developers/apps/creating-a-github-app-from-a-manifest
- /developers/apps/building-github-apps/creating-a-github-app-from-a-manifest
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest
versions:
fpt: '*'
ghes: '*'
@@ -30,7 +31,7 @@ Here are some scenarios where you might use GitHub App Manifests to create preco
## Implementing the GitHub App Manifest flow
The GitHub App Manifest flow uses a handshaking process similar to the [OAuth flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). The flow uses a manifest to [register a GitHub App](/apps/creating-github-apps/creating-github-apps/creating-a-github-app) and receives a temporary `code` used to retrieve the app's private key, webhook secret, and ID.
The GitHub App Manifest flow uses a handshaking process similar to the [OAuth flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). The flow uses a manifest to [register a GitHub App](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and receives a temporary `code` used to retrieve the app's private key, webhook secret, and ID.
{% note %}

9
content/apps/creating-github-apps/creating-github-apps/creating-a-github-app-using-url-parameters.md → content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md
View File

@@ -5,6 +5,7 @@ redirect_from:
- /apps/building-github-apps/creating-github-apps-using-url-parameters
- /developers/apps/creating-a-github-app-using-url-parameters
- /developers/apps/building-github-apps/creating-a-github-app-using-url-parameters
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app-using-url-parameters
versions:
fpt: '*'
ghes: '*'
@@ -20,7 +21,7 @@ You can use URL parameters to preselect the configuration settings of a new {% d
This approach is useful for integrators who want customers to set up an app on their personal account or organization with certain specifications, or for customers using {% data variables.product.prodname_ghe_server %} who aren't able to install apps from the {% data variables.product.prodname_marketplace %}.
Alternatively, you can create a {% data variables.product.prodname_github_app %} manifest. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest)."
Alternatively, you can create a {% data variables.product.prodname_github_app %} manifest. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)."
## Creating a custom configuration URL with query parameters
@@ -46,7 +47,7 @@ Parameter name | Type | Description
`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. Give your app a clear and succinct name. Your app cannot have the same name as an existing GitHub user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action.
`description` | `string` | A description of the {% data variables.product.prodname_github_app %}.
`url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage.
`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to generate a user access token. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)."
`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to generate a user access token. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)."
`request_oauth_on_install` | `boolean` | If your app authorizes users using the OAuth flow, you can set this option to `true` to allow people to authorize the app when they install it, saving a step. If you select this option, the `setup_url` becomes unavailable and users will be redirected to your `callback_url` after installing the app.
`setup_url` | `string` | The full URL to redirect to after someone installs the {% data variables.product.prodname_github_app %} if the app requires additional setup after installation.
`setup_on_update` | `boolean` | Set to `true` to redirect people to the setup URL when installations have been updated, for example, after repositories are added or removed.
@@ -64,7 +65,7 @@ You can use query parameters to select the permissions for the {% data variables
For example, to select "Read & write" permissions in the user interface for `contents`, your query string would include `contents=write`. To select "Read-only" permissions in the user interface for `blocking`, your query string would include `blocking=read`. To select "No access" in the user interface for `checks`, your query string would not include the `checks` permission.
For more information about permissions and {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps)."
For more information about permissions and {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
## {% data variables.product.prodname_github_app %} webhook events
@@ -76,4 +77,4 @@ For example, to subscribe a {% data variables.product.prodname_github_app %} to
You cannot use query parameters to set the value of a webhook secret. If an app requires a secret to secure its webhook, the value of the secret must be set in the {% data variables.product.company_short %} UI by the person creating the app.
For more information about webhooks and {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
For more information about webhooks and {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."

13
content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md → content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md
View File

@@ -7,6 +7,7 @@ redirect_from:
- /apps/building-github-apps/creating-a-github-app
- /developers/apps/creating-a-github-app
- /developers/apps/building-github-apps/creating-a-github-app
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app
versions:
fpt: '*'
ghes: '*'
@@ -40,7 +41,7 @@ You can create a {% data variables.product.prodname_github_app %} owned by your
If your app does not need to act on behalf of a user (does not need to generate a user access token), this field will be ignored. If your app uses device flow instead of web application flow to generate a user access token, this field will be ignored.
For more information about the callback URL, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)." For more information about generating a user access token to act on behalf of a user, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
For more information about the callback URL, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)." For more information about generating a user access token to act on behalf of a user, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
1. Optionally, to prevent user access tokens from expiring, deselect **Expire user authorization tokens**. {% data variables.product.company_short %} strongly recommends that you leave this option selected. For more information about refreshing expired tokens and the benefits of user access tokens that expire, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)." If your app does not need to generate a user access token, this field will be ignored.
1. Optionally, to prompt users to authorize your app when they install it, select **Request user authorization (OAuth) during installation**. If a user authorizes your app, your app can generate a user access token to make API requests on the user's behalf and attribute app activity to the user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
1. Optionally, if you want to use device flow to generate a user access token, select **Enable Device Flow**. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
@@ -48,13 +49,13 @@ You can create a {% data variables.product.prodname_github_app %} owned by your
If you selected **Request user authorization (OAuth) during installation** in an earlier step, you will not be able to enter a URL here. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup.
1. Optionally, if you want to redirect users to the setup URL after they update an installation, select **Redirect on update**. An update includes adding or removing a repository for an installation. If "Setup URL" is blank, this will be ignored.
1. Optionally, if you do not want your app to receive webhook events, deselect **Active**. For example, if your app will only be used for authentication or does not need to respond to webhooks, deselect this option. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
1. If you selected **Active** in the previous step, under "Webhook URL", enter the URL that {% data variables.product.company_short %} should send webhook events to. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
1. Optionally, if you selected **Active** in the previous step, under "Webhook secret", enter a secret token to secure your webhooks. {% data variables.product.company_short %} highly recommends that you set a webhook secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
1. Optionally, if you do not want your app to receive webhook events, deselect **Active**. For example, if your app will only be used for authentication or does not need to respond to webhooks, deselect this option. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."
1. If you selected **Active** in the previous step, under "Webhook URL", enter the URL that {% data variables.product.company_short %} should send webhook events to. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."
1. Optionally, if you selected **Active** in the previous step, under "Webhook secret", enter a secret token to secure your webhooks. {% data variables.product.company_short %} highly recommends that you set a webhook secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."
1. If you entered a webhook URL, under "SSL verification", select whether to enable SSL verification. {% data variables.product.company_short %} highly recommends that you enable SSL verification.
1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
1. If you selected **Active** in the earlier step to indicate that your app should receive webhook events, under "Subscribe to events", select the webhook events that you want your app to receive. The permissions that you selected in the previous step determine what webhook events are available. For more information about each webhook event, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)."
1. Under "Where can this GitHub App be installed?", select **Only on this account** or **Any account**. For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)."
1. Under "Where can this GitHub App be installed?", select **Only on this account** or **Any account**. For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private)."
1. Click **Create GitHub App**.
## Further reading

3
content/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps.md → content/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps.md
View File

@@ -7,6 +7,7 @@ redirect_from:
- /apps/differences-between-apps
- /developers/apps/differences-between-github-apps-and-oauth-apps
- /developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps
- /apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps
versions:
fpt: '*'
ghes: '*'
@@ -65,7 +66,7 @@ An _authorized_ OAuth App has access to all of the user's or organization owner'
| A GitHub App can request an installation access token by using a private key with a JSON web token format out-of-band. | An OAuth app can exchange a request token for an access token after a redirect via a web request. |
| An installation token identifies the app as the GitHub Apps bot, such as @jenkins-bot. | An access token identifies the app as the user who granted the token to the app, such as @octocat. |
| Installation access tokens expire after a predefined amount of time (currently 1 hour). | OAuth tokens remain active until they're revoked by the customer. |
| {% data variables.product.prodname_github_apps %} installed on organizations or repositories are subject to rate limits that scale with the number of installations. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps)." | OAuth tokens use the user's rate limit of {% ifversion fpt or ghec or ghes %}5,000{% elsif ghae %}15,000{% endif %} requests per hour. |
| {% data variables.product.prodname_github_apps %} installed on organizations or repositories are subject to rate limits that scale with the number of installations. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps)." | OAuth tokens use the user's rate limit of {% ifversion fpt or ghec or ghes %}5,000{% elsif ghae %}15,000{% endif %} requests per hour. |
| Rate limit increases can be granted both at the GitHub Apps level (affecting all installations) and at the individual installation level. | Rate limit increases are granted per OAuth App. Every token granted to that OAuth App gets the increased limit. |
| {% data variables.product.prodname_github_apps %} can authenticate on behalf of the user. The flow to authorize is the same as the {% data variables.product.prodname_oauth_app %} authorization flow. User access tokens can expire and be renewed with a refresh token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." | The OAuth flow used by {% data variables.product.prodname_oauth_apps %} authorizes an {% data variables.product.prodname_oauth_app %} on behalf of the user. This is the same flow used to generate a {% data variables.product.prodname_github_app %} user access token. |

3
content/apps/creating-github-apps/creating-github-apps/index.md → content/apps/creating-github-apps/setting-up-a-github-app/index.md
View File

@@ -1,5 +1,5 @@
---
title: 'Creating {% data variables.product.prodname_github_apps %}'
title: 'Setting up a {% data variables.product.prodname_github_app %}'
intro: 'Learn about building {% data variables.product.prodname_github_apps %}.'
versions:
fpt: '*'
@@ -8,6 +8,7 @@ versions:
ghec: '*'
redirect_from:
- /apps/building-github-apps
- /apps/creating-github-apps/creating-github-apps
topics:
- GitHub Apps
children:

1
content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md → content/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private.md
View File

@@ -9,6 +9,7 @@ redirect_from:
- /apps/managing-github-apps/making-a-github-app-public-or-private
- /developers/apps/making-a-github-app-public-or-private
- /developers/apps/managing-github-apps/making-a-github-app-public-or-private
- /apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private
versions:
fpt: '*'
ghes: '*'

1
content/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps.md → content/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps.md
View File

@@ -8,6 +8,7 @@ redirect_from:
- /apps/building-github-apps/understanding-rate-limits-for-github-apps
- /developers/apps/rate-limits-for-github-apps
- /developers/apps/building-github-apps/rate-limits-for-github-apps
- /apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps
versions:
fpt: '*'
ghes: '*'

12
content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md → content/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps.md
View File

@@ -9,6 +9,8 @@ versions:
ghec: '*'
topics:
- GitHub Apps
redirect_from:
- /apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps
---
## About webhooks and {% data variables.product.prodname_github_apps %}
@@ -17,9 +19,9 @@ Webhooks enable your {% data variables.product.prodname_github_app %} to receive
You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. For more information about the types of webhooks you can receive, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)."
To receive webhook events in your {% data variables.product.prodname_github_app %}, you must activate webhooks in the app settings and specify a webhook URL where {% data variables.product.prodname_dotcom %} will send the webhook payloads. For more information about creating and configuring a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
To receive webhook events in your {% data variables.product.prodname_github_app %}, you must activate webhooks in the app settings and specify a webhook URL where {% data variables.product.prodname_dotcom %} will send the webhook payloads. For more information about creating and configuring a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
If your app does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function in your app settings. You do not need to specify a webhook URL. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
If your app does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function in your app settings. You do not need to specify a webhook URL. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
For information about changing the webhooks that a {% data variables.product.prodname_github_app %} subscribes to, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
@@ -37,7 +39,7 @@ You can use Smee to create a unique domain where {% data variables.product.prodn
1. To use Smee to create a unique domain, go to https://smee.io and click **Start a new channel**.
1. On the Smee channel page, follow the instructions under "Use the CLI" to install and run the Smee client.
1. To connect your Smee webhook URL to your {% data variables.product.prodname_github_app %}, enter your unique Smee domain in the "Webhook URL" field of your app settings. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
1. To connect your Smee webhook URL to your {% data variables.product.prodname_github_app %}, enter your unique Smee domain in the "Webhook URL" field of your app settings. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
### Choosing a webhook URL for production
@@ -49,13 +51,13 @@ To handle a higher volume of webhook traffic for a large app in production, cons
Once you've configured your server to receive payloads, it will listen for any payload sent to the server. For security reasons, you should limit incoming requests to only those originating from {% data variables.product.prodname_dotcom %}. You can do that by creating a webhook secret for your app.
To create a webhook secret for your GitHub App, type a secret token in your app settings under "Webhook secret." You should choose a random string of text with high entropy. For more information about how to create a webhook secret in your app settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
To create a webhook secret for your GitHub App, type a secret token in your app settings under "Webhook secret." You should choose a random string of text with high entropy. For more information about how to create a webhook secret in your app settings, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
After creating a webhook secret for your app, you will need to configure your server to securely store and validate the webhook secret token. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks)."
## Subscribing to webhook events
You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. {% data reusables.apps.webhooks-and-apps %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. {% data reusables.apps.webhooks-and-apps %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
For example, if you would like your app to receive a webhook event payload whenever a new issue is opened in your repository, you would first need to give your app permission to access "Issues" under "Repository permissions." Then under "Subscribe to events" you can select "Issues."

10
content/apps/index.md
View File

@@ -3,16 +3,16 @@ title: GitHub Apps documentation
shortTitle: Apps
intro: 'Go deeper with {% data variables.product.prodname_dotcom %} by integrating with our APIs and webhooks, customizing your {% data variables.product.prodname_dotcom %} workflow, and building and sharing apps with the community.'
introLinks:
About apps: /apps/creating-github-apps/creating-github-apps/about-apps
About apps: /apps/creating-github-apps/setting-up-a-github-app/about-apps
layout: product-landing
featuredLinks:
startHere:
- /apps/creating-github-apps/creating-github-apps/about-apps
- /apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app
- /apps/creating-github-apps/setting-up-a-github-app/about-apps
- /apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps
- /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app
- /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
popular:
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app
- /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app
- /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
- /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace
guideCards:

6
content/apps/maintaining-github-apps/installing-github-apps.md
View File

@@ -21,7 +21,7 @@ topics:
## Installing your private GitHub App on your repository
Once you create a private GitHub App, you can install it on one of your org or user repositories. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private#private-installation-flow)."
Once you create a private GitHub App, you can install it on one of your org or user repositories. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private#private-installation-flow)."
1. From the [GitHub Apps settings page](https://github.com/settings/apps), select your app.
1. In the left sidebar, click **Install App**.
@@ -47,7 +47,7 @@ You can enable others to install your public app by providing the installation U
If you are migrating from an OAuth App to a GitHub App, you can use query parameters to preselect the repositories and account when installing the GitHub App. See "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)" to learn more.
These steps assume you have [built a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/creating-github-apps):
These steps assume you have [built a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/setting-up-a-github-app):
1. From the [GitHub Apps settings page](https://github.com/settings/apps), select the public app you want to configure for others to install.
2. In the "General" tab, under "Homepage URL," type the URL for your app's homepage and click **Save changes**.
@@ -56,7 +56,7 @@ These steps assume you have [built a {% data variables.product.prodname_github_a
## Authorizing users during installation
You can simplify the authorization process by completing it during app installation. To do this, select **Request user authorization (OAuth) during installation** when creating or modifying your app in GitHub. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)" to learn more.
You can simplify the authorization process by completing it during app installation. To do this, select **Request user authorization (OAuth) during installation** when creating or modifying your app in GitHub. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" to learn more.
Once someone has installed your app, you will need to get an access token for the user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
## Preserving an application state during installation

4
content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps.md
View File

@@ -18,7 +18,7 @@ If you follow these best practices it will help you to provide a secure user exp
## Authorization, authentication, and access control
We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps)" for more details.
We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)" for more details.
- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia.
- Apps should provide customers with a way to delete their account, without having to email or call a support person.
- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately.
@@ -26,7 +26,7 @@ We recommend creating a GitHub App rather than an OAuth App. {% data reusables.m
- Apps should not share service accounts such as email or database services to manage your SaaS service.
- All services used in your app should have unique login and password credentials.
- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties.
- Apps should not use {% data variables.product.pat_generic %}s to authenticate and should authenticate as an [OAuth App](/apps/creating-github-apps/creating-github-apps/about-apps#about-oauth-apps) or a [GitHub App](/apps/creating-github-apps/creating-github-apps/about-apps#about-github-apps):
- Apps should not use {% data variables.product.pat_generic %}s to authenticate and should authenticate as an [OAuth App](/apps/creating-github-apps/setting-up-a-github-app/about-apps#about-oauth-apps) or a [GitHub App](/apps/creating-github-apps/setting-up-a-github-app/about-apps#about-github-apps):
- OAuth Apps should authenticate using an [OAuth token](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
- GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app), [OAuth token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps), or [installation access token](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).

2
content/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace.md
View File

@@ -36,7 +36,7 @@ If you're interested in creating an app for {% data variables.product.prodname_m
### {% data variables.product.prodname_github_apps %} vs. {% data variables.product.prodname_oauth_apps %}
{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_apps %} in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)."
{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_apps %} in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)" and "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)."
## Publishing an app to {% data variables.product.prodname_marketplace %} overview

4
content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md
View File

@@ -123,7 +123,7 @@ $ git clone git@{% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.c
If your server needs to access repositories across one or more organizations, you can use a GitHub App to define the access you need, and then generate _tightly-scoped_, installation access tokens from that GitHub App. The installation access tokens can be scoped to single or multiple repositories, and can have fine-grained permissions. For example, you can generate a token with read-only access to a repository's contents.
Since GitHub Apps are a first class actor on {% data variables.product.product_name %}, the installation access tokens are decoupled from any GitHub user, which makes them comparable to "service tokens". Additionally, installation access tokens have dedicated rate limits that scale with the size of the organizations that they act upon. For more information, see [Rate limits for {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps).
Since GitHub Apps are a first class actor on {% data variables.product.product_name %}, the installation access tokens are decoupled from any GitHub user, which makes them comparable to "service tokens". Additionally, installation access tokens have dedicated rate limits that scale with the size of the organizations that they act upon. For more information, see [Rate limits for {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps).
### Pros of installation access tokens
@@ -141,7 +141,7 @@ Since GitHub Apps are a first class actor on {% data variables.product.product_
1. Determine if your GitHub App should be public or private. If your GitHub App will only act on repositories within your organization, you likely want it private.
1. Determine the permissions your GitHub App requires, such as read-only access to repository contents.
1. Create your GitHub App via your organization's settings page. For more information, see [Creating a GitHub App](/apps/creating-github-apps/creating-github-apps/creating-a-github-app).
1. Create your GitHub App via your organization's settings page. For more information, see [Creating a GitHub App](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app).
1. Note your GitHub App `id`.
1. Generate and download your GitHub App's private key, and store this safely. For more information, see [Generating a private key](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps).
1. Install your GitHub App on the repositories it needs to act upon, optionally you may install the GitHub App on all repositories in your organization.

2
content/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token.md
View File

@@ -30,7 +30,7 @@ shortTitle: 'Create a {% data variables.product.pat_generic %}'
{% data variables.product.pat_generic_caps %}s are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/authenticating-to-the-rest-api) or the [command line](#using-a-personal-access-token-on-the-command-line).
{% data variables.product.pat_generic_caps %}s are intended to access {% data variables.product.company_short %} resources on behalf of yourself. To access resources on behalf of an organization, or for long-lived integrations, you should use a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)."
{% data variables.product.pat_generic_caps %}s are intended to access {% data variables.product.company_short %} resources on behalf of yourself. To access resources on behalf of an organization, or for long-lived integrations, you should use a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-apps)."
{% ifversion pat-v2 %}

2
content/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security.md
View File

@@ -67,7 +67,7 @@ For other billing-related questions, contact {% data variables.contact.github_su
We record and display two numbers of {% ifversion ghas-billing-UI-update %}active {% endif %}committers for {% data variables.product.prodname_GH_advanced_security %} on {% data variables.location.product_location %}:
- **{% ifversion ghas-billing-UI-update %}Active committers{% else %}Committers{% endif %}** is the number of committers who contributed to at least one {% ifversion fpt or ghec %}private {% endif %}repository in an organization and who use a {% ifversion ghas-billing-UI-update %}license {% else %}seat {% endif %}in your enterprise. That is, they are also an organization member, an external collaborator, or have a pending invitation to join an organization in your enterprise, and they are not a {% data variables.product.prodname_github_app %} bot. For information about differences between bot and machine accounts, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts)."
- **{% ifversion ghas-billing-UI-update %}Active committers{% else %}Committers{% endif %}** is the number of committers who contributed to at least one {% ifversion fpt or ghec %}private {% endif %}repository in an organization and who use a {% ifversion ghas-billing-UI-update %}license {% else %}seat {% endif %}in your enterprise. That is, they are also an organization member, an external collaborator, or have a pending invitation to join an organization in your enterprise, and they are not a {% data variables.product.prodname_github_app %} bot. For information about differences between bot and machine accounts, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts)."
- **Unique to this repository/organization** is the number of {% ifversion ghas-billing-UI-update %}active {% endif %}committers who contributed only to this repository, or to repositories in this organization. This number shows how many {% ifversion ghas-billing-UI-update %}licenses {% else %}seats {% endif %}you can free up by deactivating {% data variables.product.prodname_GH_advanced_security %} for that repository or organization.
If there are no unique {% ifversion ghas-billing-UI-update %}active {% endif %}committers, all active committers also contribute to other repositories or organizations that use {% data variables.product.prodname_GH_advanced_security %}. Deactivating the feature for that repository or organization would not free any {% ifversion ghas-billing-UI-update %}licenses{% else %}seats{% endif %} for {% data variables.product.prodname_GH_advanced_security %}.

2
content/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning.md
View File

@@ -35,7 +35,7 @@ If you use a third-party static analysis tool that can produce results as Static
## Integrations with webhooks
You can use {% data variables.product.prodname_code_scanning %} webhooks to build or configure integrations, such as [{% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/creating-github-apps) or [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps), that subscribe to {% data variables.product.prodname_code_scanning %} events in your repository. For example, you could build an integration that creates an issue on {% data variables.product.product_name %} or sends you a Slack notification when a new {% data variables.product.prodname_code_scanning %} alert is added in your repository. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/creating-webhooks)" and "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert)."
You can use {% data variables.product.prodname_code_scanning %} webhooks to build or configure integrations, such as [{% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app) or [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps), that subscribe to {% data variables.product.prodname_code_scanning %} events in your repository. For example, you could build an integration that creates an issue on {% data variables.product.product_name %} or sends you a Slack notification when a new {% data variables.product.prodname_code_scanning %} alert is added in your repository. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/creating-webhooks)" and "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert)."
## Further reading

2
content/get-started/exploring-integrations/about-github-marketplace.md
View File

@@ -33,4 +33,4 @@ For more information on creating your own tool to list on {% data variables.prod
- "[AUTOTITLE](/apps/using-github-apps)"
- "[AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps)"
- "[AUTOTITLE](/support/learning-about-github-support/github-marketplace-support)"
- "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps)"
- "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)"

4
content/get-started/exploring-integrations/about-integrations.md
View File

@@ -19,8 +19,8 @@ Integrations can be {% data variables.product.prodname_github_apps %}, {% data v
{% data variables.product.prodname_github_apps %} offer granular permissions and request access to only what the app needs. {% data variables.product.prodname_github_apps %} also offer specific user-level permissions that each user must authorize individually when an app is installed or when the integrator changes the permissions requested by the app.
For more information, see:
- "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps)"
- "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)"
- "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps)"
- "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-apps)"
- "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)"
- "[AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps)"
- "[AUTOTITLE](/apps/using-github-apps/authorizing-github-apps)"

2
content/get-started/onboarding/getting-started-with-github-enterprise-server.md
View File

@@ -88,7 +88,7 @@ You can upgrade your {% data variables.product.product_name %} license to includ
You can customize and automate work in organizations in your enterprise with {% data variables.product.prodname_dotcom %} and {% data variables.product.prodname_oauth_apps %}, {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API, {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %} , and {% data variables.product.prodname_pages %}.
### 1. Building {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}
You can build integrations with the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API, such as {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, for use in organizations in your enterprise to complement and extend your workflows. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)."
You can build integrations with the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API, such as {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, for use in organizations in your enterprise to complement and extend your workflows. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-apps)."
### 2. Using the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API
{% data reusables.getting-started.api %}

2
content/graphql/guides/forming-calls-with-graphql.md
View File

@@ -31,7 +31,7 @@ If your token does not have the required scopes to access a resource, the API wi
### Authenticating with a {% data variables.product.prodname_github_app %}
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. In order to attribute activity to your app, you can make your app authenticate as an app installation. In order to attribute app activity to a user, you can make your app authenticate on behalf of a user. In both cases, you will generate a token that you can use to authenticate to the GraphQL API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. In order to attribute activity to your app, you can make your app authenticate as an app installation. In order to attribute app activity to a user, you can make your app authenticate on behalf of a user. In both cases, you will generate a token that you can use to authenticate to the GraphQL API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."
### Authenticating with a {% data variables.product.prodname_oauth_app %}

2
content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md
View File

@@ -35,7 +35,7 @@ You may also want to use the **actions/add-to-project** workflow, which is maint
### Example workflow authenticating with a {% data variables.product.prodname_github_app %}
1. Create a {% data variables.product.prodname_github_app %} or choose an existing {% data variables.product.prodname_github_app %} owned by your organization. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
1. Create a {% data variables.product.prodname_github_app %} or choose an existing {% data variables.product.prodname_github_app %} owned by your organization. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
2. Give your {% data variables.product.prodname_github_app %} read and write permissions to organization projects. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)."
{% note %}

2
content/rest/guides/getting-started-with-the-rest-api.md
View File

@@ -100,7 +100,7 @@ You can authenticate your request by adding a token.
If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. The REST API operations used in this article require `repo` scope for {% data variables.product.pat_v1_plural %}{% ifversion pat-v2 %} or, unless otherwise noted, read-only access to public repositories for {% data variables.product.pat_v2 %}s{% endif %}. Other operations may require different scopes{% ifversion pat-v2%} or permissions{% endif %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an operation is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require `issues` read and write permissions for {% data variables.product.prodname_github_apps %}. Other operations may require different permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)."
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an operation is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require `issues` read and write permissions for {% data variables.product.prodname_github_apps %}. Other operations may require different permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)."
If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."

2
content/rest/guides/scripting-with-the-rest-api-and-javascript.md
View File

@@ -54,7 +54,7 @@ const octokit = new Octokit({ {% ifversion ghes or ghae %}
### Authenticating with a {% data variables.product.prodname_github_app %}
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)," "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)," and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)."
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)," "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)," and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)."
Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation.

2
content/rest/overview/permissions-required-for-github-apps.md
View File

@@ -16,7 +16,7 @@ shortTitle: GitHub App permissions
## About {% data variables.product.prodname_github_app %} permissions
{% data variables.product.prodname_github_apps %} are created with a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps)."
{% data variables.product.prodname_github_apps %} are created with a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
## Actions

2
content/rest/overview/resources-in-the-rest-api.md
View File

@@ -339,7 +339,7 @@ For unauthenticated requests, the rate limit allows for up to 60 requests per ho
#### Rate limits for requests from {% data variables.product.prodname_github_apps %}
Requests from a {% data variables.product.prodname_github_app %} may either use a user access token or an installation access token. For more information about rate limits for {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps)."
Requests from a {% data variables.product.prodname_github_app %} may either use a user access token or an installation access token. For more information about rate limits for {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps)."
#### Rate limits for requests from {% data variables.product.prodname_actions %}

4
content/rest/rate-limit.md
View File

@@ -15,7 +15,7 @@ autogenerated: rest
## About rate limits
You can check your current rate limit status at any time. For more information about rate limit rules, see "[AUTOTITLE](/rest/overview/resources-in-the-rest-api#rate-limiting)."
You can check your current rate limit status at any time. For more information about rate limit rules, see "[AUTOTITLE](/rest/overview/resources-in-the-rest-api#rate-limiting)."
The REST API for searching items has a custom rate limit that is separate from the rate limit governing the other REST API endpoints. For more information, see "[AUTOTITLE](/rest/search)." The GraphQL API also has a custom rate limit that is separate from and calculated differently than rate limits in the REST API. For more information, see "[AUTOTITLE](/graphql/overview/resource-limitations#rate-limit)." For these reasons, the API response categorizes your rate limit. Under `resources`, you'll see objects relating to different categories:
@@ -25,7 +25,7 @@ The REST API for searching items has a custom rate limit that is separate from t
* The `graphql` object provides your rate limit status for the GraphQL API.
* The `integration_manifest` object provides your rate limit status for the `POST /app-manifests/{code}/conversions` operation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration)."
* The `integration_manifest` object provides your rate limit status for the `POST /app-manifests/{code}/conversions` operation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration)."
For more information on the headers and values in the rate limit response, see "[AUTOTITLE](/rest/overview/resources-in-the-rest-api#rate-limit-http-headers)."

2
content/webhooks-and-events/webhooks/about-webhooks.md
View File

@@ -16,7 +16,7 @@ topics:
{% data reusables.webhooks.webhooks-ipv6 %}
Webhooks allow you to build or set up integrations, such as [{% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/creating-github-apps) or [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps), which subscribe to certain events on GitHub.com. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. You're only limited by your imagination.
Webhooks allow you to build or set up integrations, such as [{% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app) or [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps), which subscribe to certain events on GitHub.com. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. You're only limited by your imagination.
Webhooks can be installed on{% ifversion ghes or ghae %} [{% data variables.product.prodname_enterprise %}](/rest/enterprise-admin#global-webhooks/),{% endif %} an [organization][org-hooks], a specific [repository][repo-hooks], or a {% data variables.product.prodname_github_app %}. Once installed, the webhook will be sent each time one or more subscribed events occurs.

4
content/webhooks-and-events/webhooks/replacing-github-services.md
View File

@@ -54,7 +54,7 @@ To replace GitHub Services with Webhooks:
- **GitHub Apps**: Update your app's permissions and subscribed events to configure your app to receive the relevant webhook events.
- **OAuth Apps**: Request either the `repo_hook` and/or `org_hook` scope(s) to manage the relevant events on behalf of users.
- **GitHub Service providers**: Request that users manually configure a webhook with the relevant events sent to you, or take this opportunity to build an app to manage this functionality. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps)."
- **GitHub Service providers**: Request that users manually configure a webhook with the relevant events sent to you, or take this opportunity to build an app to manage this functionality. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-apps)."
3. Move additional configuration from outside of GitHub. Some GitHub Services require additional, custom configuration on the configuration page within GitHub. If your service does this, you will need to move this functionality into your application or rely on GitHub or OAuth Apps where applicable.
@@ -72,4 +72,4 @@ Please [contact us](https://github.com/contact?form%5Bsubject%5D=GitHub+Services
As a high-level overview, the process of migration typically involves:
- Identifying how and where your product is using GitHub Services.
- Identifying the corresponding webhook events you need to configure in order to move to plain webhooks.
- Implementing the design using either [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps) or [{% data variables.product.prodname_github_apps %}. {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/creating-github-apps) are preferred. To learn more about why {% data variables.product.prodname_github_apps %} are preferred, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps#reasons-for-switching-to-github-apps)."
- Implementing the design using either [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps) or [{% data variables.product.prodname_github_apps %}. {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app) are preferred. To learn more about why {% data variables.product.prodname_github_apps %} are preferred, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps#reasons-for-switching-to-github-apps)."

2
content/webhooks-and-events/webhooks/webhook-events-and-payloads.md
View File

@@ -33,7 +33,7 @@ Key | Type | Description
{% data reusables.webhooks.sender_desc %} This property is included in every webhook payload.
{% data reusables.webhooks.repo_desc %} Webhook payloads contain the `repository` property when the event occurs from activity in a repository.
{% data reusables.webhooks.org_desc %}
{% data reusables.webhooks.app_desc %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps)."
{% data reusables.webhooks.app_desc %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app)."
The unique properties for a webhook event are the same properties you'll find in the `payload` property when using the [Events API](/rest/activity#events). One exception is the [`push` event](#push). The unique properties of the `push` event webhook payload and the `payload` property in the Events API differ. The webhook payload contains more detailed information.

2
tests/fixtures/developer-redirects.json vendored
View File

@@ -1,6 +1,6 @@
{
"/apps": "/en/apps",
"/apps/building-github-apps": "/en/apps/creating-github-apps/creating-github-apps",
"/apps/building-github-apps": "/en/apps/creating-github-apps/setting-up-a-github-app",
"/apps/building-oauth-apps": "/en/apps/oauth-apps/building-oauth-apps",
"/apps/managing-github-apps": "/en/apps/maintaining-github-apps",
"/apps/managing-oauth-apps": "/en/apps/oauth-apps/maintaining-oauth-apps",