Organisations

Link a GitHub App installation

Links one installation to the organisation, proved by the grant from POST /github/authorize, and reads the first page of its repositories.

POST/orgs/{org}/github/installations

TL;DR

Question	Answer
What does it do?	Link a GitHub App installation.
What does it take?	A JSON body of type `GithubLinkBody`.
What does it return?	Status 200 with a body of type `GithubLink`.
What can go wrong?	`400` the body is not valid; `401` not signed in; `403` a member may not (orgs.forbidden), the plan has no GitHub App (plan.github_app_not_included), or the request came from an origin that may not make changes. Or the grant is not valid (github.grant_invalid), or does not name the installation (github.installation_not_yours); `404` no such organisation, or GitHub has no such installation of the App (github.installation_not_found); `409` another organisation has linked it (github.installation_linked); `429` too many requests, or GitHub asked to wait (github.rate_limited); `502` GitHub could not be reached (github.unavailable); `503` the GitHub App is not set up on this server (github.not_configured), or organisations are not. Every failure uses the one error envelope.

What it does

Links one installation to the organisation, proved by the grant from POST /github/authorize, and reads the first page of its repositories. One installation belongs to one organisation. The owner and an admin, on Pro and Enterprise.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Request body

The body has the type GithubLinkBody.

Field	Type	Required	Description
`grant`	`string`	yes	at least 1 character; at most 8192 characters.
`installationId`	`string`	yes	at most 20 characters; pattern `^[1-9][0-9]{0,19}$`.

Responses

Status	Meaning	Body
200	Linked already to this organisation; its repositories were read again.	`GithubLink`
201	Linked.	`GithubLink`
400	The body is not valid.	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	A member may not (orgs.forbidden), the plan has no GitHub App (plan.github_app_not_included), or the request came from an origin that may not make changes. Or the grant is not valid (github.grant_invalid), or does not name the installation (github.installation_not_yours).	`ErrorResponse`
404	No such organisation, or GitHub has no such installation of the App (github.installation_not_found).	`ErrorResponse`
409	Another organisation has linked it (github.installation_linked).	`ErrorResponse`
429	Too many requests, or GitHub asked to wait (github.rate_limited).	`ErrorResponse`
502	GitHub could not be reached (github.unavailable).	`ErrorResponse`
503	The GitHub App is not set up on this server (github.not_configured), or organisations are not.	`ErrorResponse`

Response body

A 200 answer has the type GithubLink.

Field	Type	Required	Description
`installation`	`GithubInstallation`	yes
`installation.id`	`string`	yes	GitHub's installation id.
`installation.account`	`object`	yes
`installation.account.login`	`string`	yes
`installation.account.id`	`string`	yes
`installation.account.type`	`"User" \| "Organization"`	yes
`installation.repositorySelection`	`"all" \| "selected"`	yes	Whether the App reaches every repository of the account or the ones chosen on GitHub.
`installation.suspended`	`boolean`	yes
`installation.linkedAt`	`integer`	yes	Milliseconds since the epoch.
`installation.linkedBy`	`object \| null`	yes
`installation.linkedBy.id`	`string`	yes
`installation.linkedBy.email`	`string`	yes
`installation.settingsUrl`	`string`	yes	The installation's settings page on GitHub, where it is narrowed, suspended or uninstalled.
`synced`	`integer`	yes
`nextPage`	`integer \| null`	yes	The next page of repositories to read with sync, or null when every one was read.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools