About GitHub App URL parameters
You can add query parameters to these URLs to preselect the configuration of a GitHub App on a personal or organization account:
- Personal account:
http(s)://HOSTNAME/settings/apps/new - Organization account:
http(s)://HOSTNAME/organizations/:org/settings/apps/new
The person creating the app can edit the preselected values from the GitHub App registration page, before submitting the app. If you do not include required parameters in the URL query string, like name, the person creating the app will need to input a value before submitting the app.
For apps that require a secret to secure their webhook, the secret's value must be set in the form by the person creating the app, not by using query parameters. For more information, see "Sichern deiner Webhooks."
The following URL creates a new public app called octocat-github-app with a preconfigured description and callback URL. This URL also selects read and write permissions for checks, subscribes to the check_run and check_suite webhook events, and selects the option to request user authorization (OAuth) during installation:
http(s)://HOSTNAME/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&events[]=check_run&events[]=check_suite
The complete list of available query parameters, permissions, and events is listed in the sections below.
GitHub App configuration parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the 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 GitHub App. |
url | string | The full URL of your 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 "Wenn du eine GitHub App erstellst, kannst du eine Rückruf-URL angeben.." |
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 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. |
public | boolean | Set to true when your GitHub App is available to the public or false when it is only accessible to the owner of the app. |
webhook_active | boolean | Set to false to disable webhook. Webhook is enabled by default. |
webhook_url | string | The full URL that you would like to send webhook event payloads to. |
webhook_secret | string | You can specify a secret to secure your webhooks. See "Sichern deiner Webhooks" for more details. |
events | array of strings | Webhook events. Some webhook events require read or write permissions for a resource before you can select the event when registering a new GitHub App. See the "GitHub App webhook events" section for available events and their required permissions. You can select multiple events in a query string. For example, events[]=public&events[]=label. |
single_file_name | string | This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the single_file permission to read or write, this field provides the path to the single file your GitHub App will manage. |
GitHub App permissions
You can select permissions in a query string using the permission name in the following table as the query parameter name and the permission type as the query value. 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.
| Permission | Description |
|---|---|
administration | Grants access to various endpoints for organization and repository administration. Can be one of: none, read, or write. |
checks | Grants access to the Checks API. Can be one of: none, read, or write. |
contents | Grants access to various endpoints that allow you to modify repository contents. Can be one of: none, read, or write. |
deployments | Grants access to the Deployments API. Can be one of: none, read, or write. |
followers | Grants access to the Followers API. Can be one of: none, read, or write. |
gpg_keys | Grants access to the GPG Keys API. Can be one of: none, read, or write. |
issues | Grants access to the Issues API. Can be one of: none, read, or write. |
keys | Grants access to the Public Keys API. Can be one of: none, read, or write. |
members | Grants access to manage an organization's members. Can be one of: none, read, or write. |
organization_hooks | Grants access to the Organization Webhooks API. Can be one of: none, read, or write. |
organization_plan | Grants access to get information about an organization's plan using the "Organisationen" endpoint. Can be one of: none or read. |
organization_projects | Grants access to the Projects API. Can be one of: none, read, write, or admin. |
pages | Grants access to the Pages API. Can be one of: none, read, or write. |
plan | Grants access to get information about a user's GitHub plan using the "Benutzer" endpoint. Can be one of: none or read. |
pull_requests | Grants access to various pull request endpoints. Can be one of: none, read, or write. |
repository_hooks | Grants access to the Repository Webhooks API. Can be one of: none, read, or write. |
repository_projects | Grants access to the Projects API. Can be one of: none, read, write, or admin. |
single_file | Grants access to the Contents API. Can be one of: none, read, or write. |
starring | Grants access to the Starring API. Can be one of: none, read, or write. |
statuses | Grants access to the Statuses API. Can be one of: none, read, or write. |
team_discussions | Grants access to the Team Discussions API and the Team Discussion Comments API. Can be one of: none, read, or write. |
vulnerability_alerts | Grants access to receive Dependabot alerts in a repository. See "Informationen zu Dependabot-Warnungen" to learn more. Can be one of: none, read, or write. |
watching | Grants access to list and change repositories a user is subscribed to. Can be one of: none, read, or write. |
GitHub App webhook events
| Webhook event name | Required permission | Description |
|---|---|---|
check_run | checks | Die Ausführungsaktivität wurde überprüft. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Überprüfungsausführungen. |
check_suite | checks | Prüfsuitenaktivität ist aufgetreten. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Prüfsuiten. |
commit_comment | contents | Ein Commitkommentar wird erstellt. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der Commitkommentar-REST-API. |
create | contents | Ein Git-Branch oder -Tag wird erstellt. Weitere Informationen findest du im Artikel unter Git-Datenbank zur REST-API. |
delete | contents | Ein Git-Branch oder -Tag wird gelöscht. Weitere Informationen findest du im Artikel unter Git-Datenbank zur REST-API. |
deployment | deployments | Eine Bereitstellung wird erstellt. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Bereitstellungen. |
deployment_status | deployments | Eine Bereitstellung wird erstellt. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Bereitstellungen. |
fork | contents | Ein Benutzer forkt ein Repository. Weitere Informationen findest du im Artikel unter Repositorys zur REST-API. |
gollum | contents | Eine Wiki-Seite wird erstellt oder aktualisiert. Weitere Informationen findest du unter Informationen zu Wikis. |
issues | issues | Aktivität im Zusammenhang mit einem Issue. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Issues. |
issue_comment | issues | Aktivitäten im Zusammenhang mit einem Issue oder einem Pull Request-Kommentar. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Issuekommentare. |
label | metadata | Aktivitäten im Zusammenhang mit einer Bezeichnung. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Bezeichnungen. |
member | members | Aktivitäten im Zusammenhang mit Repositorymitarbeitern. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Mitarbeiter. |
membership | members | Aktivitäten im Zusammenhang mit der Teammitgliedschaft. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Teammitglieder. |
milestone | pull_request | Aktivitäten im Zusammenhang mit Meilensteinen. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Meilensteine. |
organization | members | Aktivitäten im Zusammenhang mit einer Organisation und ihren Mitgliedern. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Organisationen. |
page_build | pages | Stellt einen versuchten Build einer GitHub Pages-Website dar, unabhängig davon, ob er erfolgreich war. Ein Push an einen GitHub Pages-fähigen Branch (gh-pages für Projektseiten, den Standardbranch für Benutzer- und Organisationsseiten) löst dieses Ereignis aus. |
project | repository_projects or organization_projects | Projektboards bezogene Aktivität. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Projekte. |
project_card | repository_projects or organization_projects | Kartenbezogene Aktivitäten in einem Projektboard. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Projektkarten. |
project_column | repository_projects or organization_projects | Spaltenbezogene Aktivitäten in einem Projektboard. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Projektspalten. |
public | metadata | Wenn ein privates Repository öffentlich gemacht wird. Ohne Zweifel das beste GitHub AE-Ereignis. |
pull_request | pull_requests | Aktivitäten im Zusammenhang mit Pull Requests. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Pull Requests. |
pull_request_review | pull_request | Aktivitäten im Zusammenhang mit Pull Request-Überprüfungen. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der Pull Request-Überprüfungen-REST-API. |
pull_request_review_comment | pull_request | Aktivitäten im Zusammenhang mit Pull Request-Reviewkommentaren im Unified Diff des Pull Request. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Pull Request-Reviewkommentare. |
pull_request_review_thread | pull_request | Aktivität im Zusammenhang mit einem Kommentarthread zu einem Pull Request, der als aufgelöst oder nicht gelöst markiert wurde Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. |
push | contents | Ein oder mehrere Commits werden in einen Repositorybranch oder ein Tag gepusht. |
release | contents | Aktivität im Zusammenhang mit einem Release. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Releases. |
repository | metadata | Aktivitäten im Zusammenhang mit einem Repository. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Repositorys. |
status | statuses | Wenn sich der Status eines Git-Commits ändert. Weitere Informationen findest du im Artikel unter Commits zur REST-API. |
team | members | Aktivitäten im Zusammenhang mit dem Team einer Organisation. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Teams. |
team_add | members | Wenn ein Repository einem Team hinzugefügt wird. |
watch | metadata | Wenn jemand ein Repository mit einem Stern versieht. Der Aktivitätstyp wird in der action-Eigenschaft des Nutzdatenobjekts angegeben. Weitere Informationen findest du in der REST-API für Sterne. |