docs/content/developers/apps/creating-a-github-app-using-url-parameters.md

title	intro	redirect_from	versions
Creating a GitHub App using URL parameters	You can preselect the settings of a new {% data variables.product.prodname_github_app %} using URL [query parameters](https://en.wikipedia.org/wiki/Query_string) to quickly set up the new {% data variables.product.prodname_github_app %}'s configuration.	[/apps/building-github-apps/creating-github-apps-using-url-parameters]	[{free-pro-team *} {enterprise-server *} {github-ae *}]

About {% data variables.product.prodname_github_app %} URL parameters

You can add query parameters to these URLs to preselect the configuration of a {% data variables.product.prodname_github_app %} on a personal or organization account:

• User account: {% data variables.product.oauth_host_code %}/settings/apps/new
• Organization account: {% data variables.product.oauth_host_code %}/:org/settings/apps/new

The person creating the app can edit the preselected values from the {% data variables.product.prodname_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:

{% data variables.product.oauth_host_code %}/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.

{% data variables.product.prodname_github_app %} configuration parameters

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_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 {% 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.
public	boolean	Set to true when your {% data variables.product.prodname_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 {% data variables.product.prodname_github_app %}. See the "{% data variables.product.prodname_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	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 {% data variables.product.prodname_github_app %} will manage. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} If you need to manage multiple files, see single_file_paths below. {% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}
single_file_paths	array of strings	This allows the app to access up ten specified files in a repository. When you set the single_file permission to read or write, this array can store the paths for up to ten files that your {% data variables.product.prodname_github_app %} will manage. These files all receive the same permission set by single_file, and do not have separate individual permissions. When two or more files are configured, the API returns multiple_single_files=true, otherwise it returns multiple_single_files=false.{% endif %}

{% data variables.product.prodname_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.{% if currentVersion == "free-pro-team@latest" %}
blocking	Grants access to the Blocking Users API. Can be one of: none, read, or write.{% endif %}
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.{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
emails	Grants access to the Emails API. Can be one of: none, read, or write.{% endif %}
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.{% if currentVersion == "free-pro-team@latest" %}
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 {% data variables.product.prodname_github_app %}.
organization_administration	Grants access to "Update an organization" endpoint and the Organization Interaction Restrictions API. Can be one of: none, read, or write.{% endif %}
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.{% if currentVersion == "free-pro-team@latest" %}
organization_user_blocking	Grants access to the Blocking Organization Users API. Can be one of: none, read, or write.{% endif %}
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 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.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
secret_scanning_alerts	Grants access to the Secret scanning API. Can be one of: none, read, or write.{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
security_events	Grants access to the Code scanning API. Can be one of: none, read, or write.{% endif %}
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.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@1.19" %}
vulnerability_alerts	Grants access to receive security alerts for vulnerable dependencies in a repository. See "About security alerts for vulnerable dependencies" to learn more. Can be one of: none or read.{% endif %}
watching	Grants access to list and change repositories a user is subscribed to. Can be one of: none, read, or write.

{% data variables.product.prodname_github_app %} webhook events

Webhook event name	Required permission	Description
check_run	checks	{% data reusables.webhooks.check_run_short_desc %}
check_suite	checks	{% data reusables.webhooks.check_suite_short_desc %}
commit_comment	contents	{% data reusables.webhooks.commit_comment_short_desc %}
content_reference	content_references	{% data reusables.webhooks.content_reference_short_desc %}
create	contents	{% data reusables.webhooks.create_short_desc %}
delete	contents	{% data reusables.webhooks.delete_short_desc %}
deployment	deployments	{% data reusables.webhooks.deployment_short_desc %}
deployment_status	deployments	{% data reusables.webhooks.deployment_status_short_desc %}
fork	contents	{% data reusables.webhooks.fork_short_desc %}
gollum	contents	{% data reusables.webhooks.gollum_short_desc %}
issues	issues	{% data reusables.webhooks.issues_short_desc %}
issue_comment	issues	{% data reusables.webhooks.issue_comment_short_desc %}
label	metadata	{% data reusables.webhooks.label_short_desc %}
member	members	{% data reusables.webhooks.member_short_desc %}
membership	members	{% data reusables.webhooks.membership_short_desc %}
milestone	pull_request	{% data reusables.webhooks.milestone_short_desc %}{% if currentVersion == "free-pro-team@latest" %}
org_block	organization_administration	{% data reusables.webhooks.org_block_short_desc %}{% endif %}
organization	members	{% data reusables.webhooks.organization_short_desc %}
page_build	pages	{% data reusables.webhooks.page_build_short_desc %}
project	repository_projects or organization_projects	{% data reusables.webhooks.project_short_desc %}
project_card	repository_projects or organization_projects	{% data reusables.webhooks.project_card_short_desc %}
project_column	repository_projects or organization_projects	{% data reusables.webhooks.project_column_short_desc %}
public	metadata	{% data reusables.webhooks.public_short_desc %}
pull_request	pull_requests	{% data reusables.webhooks.pull_request_short_desc %}
pull_request_review	pull_request	{% data reusables.webhooks.pull_request_review_short_desc %}
pull_request_review_comment	pull_request	{% data reusables.webhooks.pull_request_review_comment_short_desc %}
push	contents	{% data reusables.webhooks.push_short_desc %}
release	contents	{% data reusables.webhooks.release_short_desc %}
repository	metadata	{% data reusables.webhooks.repository_short_desc %}{% if currentVersion == "free-pro-team@latest"%}
repository_dispatch	contents	Allows integrators using GitHub Actions to trigger custom events.{% endif %}
status	statuses	{% data reusables.webhooks.status_short_desc %}
team	members	{% data reusables.webhooks.team_short_desc %}
team_add	members	{% data reusables.webhooks.team_add_short_desc %}
watch	metadata	{% data reusables.webhooks.watch_short_desc %}