Creating GitHub Apps using URL parameters
You can preselect the settings of a new GitHub App using URL query parameters to quickly set up the new GitHub App's configuration.
- About GitHub App URL parameters
- GitHub App configuration parameters
- GitHub App permissions
- GitHub App webhook events
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:
-
User account:
https://github.com/settings/apps/new
-
Organization account:
https://github.com/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.
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:
https://github.com/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_url=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_url |
string |
The full URL to redirect to after someone authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests. |
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_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 "Securing your 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 . |
domain |
string |
The URL of a content reference. |
single_file_name |
string |
When you grant read or write access to the single_file permission, 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 . |
blocking |
Grants access to the Blocking Users API. Can be one of: none , read , or write . |
checks |
Grants access to the Checks API. Can be one of: none , read , or write . |
content_references |
Grants access to the "Create a content attachment" endpoint. 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 . |
emails |
Grants access to the Emails 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 . |
metadata |
Grants access to read-only endpoints that do not leak sensitive data. Can be read or none . Defaults to read when you set any permission, or defaults to none when you don't specify any permissions for the GitHub App. |
organization_administration |
Grants access to "Edit an organization" endpoint and the Organization Interaction Restrictions API. 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 "Get an organization" 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 . |
organization_user_blocking |
Grants access to the Blocking Organization Users API. Can be one of: none , read , or write . |
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 "Get a single user" 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 security alerts for vulnerable dependencies in a repository. See "About security alerts for vulnerable dependencies" in the GitHub Help documentation to learn more. Can be one of: none or read . |
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 |
Triggered when a check run is created , rerequested , completed , or has a requested_action . |
check_suite |
checks |
Triggered when a check suite is completed , requested , or rerequested . |
commit_comment |
contents |
Triggered when a commit comment is created. |
content_reference |
content_references |
Triggered when the body or comment of an issue or pull request includes a URL that matches a configured content reference domain. Only GitHub Apps can receive this event. |
create |
contents |
Represents a created branch or tag. |
delete |
contents |
Represents a deleted branch or tag. |
deployment |
deployments |
Represents a deployment. |
deployment_status |
deployments |
Represents a deployment status. |
fork |
contents |
Triggered when a user forks a repository. |
gollum |
contents |
Triggered when a Wiki page is created or updated. |
issues |
issues |
Triggered when an issue is opened , edited , deleted , pinned , unpinned , closed , reopened , assigned , unassigned , labeled , unlabeled , locked , unlocked , transferred , milestoned , or demilestoned . |
issue_comment |
issues |
Triggered when an issue comment is created , edited , or deleted . |
label |
metadata |
Triggered when a repository's label is created , edited , or deleted . |
member |
members |
Triggered when a user accepts an invitation or is removed as a collaborator to a repository, or has their permissions changed. |
membership |
members |
Triggered when a user is added or removed from a team. |
milestone |
pull_request |
Triggered when a milestone is created , closed , opened , edited , or deleted . |
org_block |
organization_administration |
Triggered when an organization blocks or unblocks a user. |
organization |
members |
Triggered when an organization is deleted and renamed, and when a user is added, removed, or invited to an organization. |
page_build |
pages |
Triggered on push to a GitHub Pages enabled branch (gh-pages for project pages, master for user and organization pages). |
project |
repository_projects or organization_projects
|
Triggered when a project is created , updated , closed , reopened , or deleted . |
project_card |
repository_projects or organization_projects
|
Triggered when a project card is created , edited , moved , converted to an issue, or deleted . |
project_column |
repository_projects or organization_projects
|
Triggered when a project column is created , updated , moved , or deleted . |
public |
metadata |
Triggered when a private repository is made public. |
pull_request |
pull_requests |
Triggered when a pull request is assigned , unassigned , labeled , unlabeled , opened , edited , closed , reopened , synchronize , ready_for_review , locked , unlocked or when a pull request review is requested or removed. |
pull_request_review |
pull_request |
Triggered when a pull request review is submitted into a non-pending state, the body is edited , or the review is dismissed . |
pull_request_review_comment |
pull_request |
Triggered when a comment on a pull request's unified diff is created , edited , or deleted (in the Files Changed tab). |
push |
contents |
Triggered on a push to a repository branch. Branch pushes and repository tag pushes also trigger webhook push events. |
release |
contents |
Triggered when a release is published , unpublished , created , edited , deleted , or prereleased . |
repository |
metadata |
Triggered when a repository is created , archived , unarchived , renamed , edited , transferred , made public, or made private. Organization hooks are also triggered when a repository is deleted . |
repository_dispatch |
contents |
Allows integrators using GitHub Actions to trigger custom events. |
security_advisory |
Does not apply. | Triggered when a new security advisory is published, updated, or withdrawn. |
status |
statuses |
Triggered when the status of a Git commit changes. |
team |
members |
Triggered when an organization's team is created , deleted , edited , added_to_repository , or removed_from_repository . |
team_add |
members |
Triggered when a repository is added to a team. |
watch |
metadata |
Triggered when someone stars a repository. |