# Client API: GitHub

> Connect the Coritan GitHub App so deployments build from private repositories on every push: start an installation, record it, list the installations and the repositories each reaches, and remove one.

Source: https://www.coritan.com/docs/api/reference/client/github/

Connect the Coritan GitHub App so deployments build from private repositories on every push: start an installation, record it, list the installations and the repositories each reaches, and remove one. Paths are under `/api/v1/git/github`.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/git/github/install`](#op-get-api-v1-git-github-install) | Start a GitHub App install |
| GET | [`/api/v1/git/github/installations`](#op-get-api-v1-git-github-installations) | List installations |
| POST | [`/api/v1/git/github/installations`](#op-post-api-v1-git-github-installations) | Record a GitHub installation |
| DELETE | [`/api/v1/git/github/installations/{installation_ref}`](#op-delete-api-v1-git-github-installations-installation-ref) | Forget a GitHub installation |
| GET | [`/api/v1/git/github/installations/{installation_ref}/repositories`](#op-get-api-v1-git-github-installations-installation-ref-repositories) | List an installation's repositories |

### Start a GitHub App install {#op-get-api-v1-git-github-install}

`GET /api/v1/git/github/install`

Where to send the browser to install the GitHub App for the account
(or organization). ``url`` works for ``expires_in`` seconds; GitHub
then comes back to ``return_to``, a path on this storefront.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `return_to` | query | string or null | no | A dashboard path to come back to, such as /dashboard/deployments; left out or not a path, /dashboard/order/app-deployment |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List installations {#op-get-api-v1-git-github-installations}

`GET /api/v1/git/github/installations`

The owner's GitHub App installations by account, each with how many
deployments clone through it, and the App itself.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Record a GitHub installation {#op-post-api-v1-git-github-installations}

`POST /api/v1/git/github/installations`

Record the installation the callback's ``ticket`` names: 201 when it
is new, 200 when it refreshed one the owner already had. A ticket
another account or member started answers 403, a used one 409, and an
installation another owner holds 409 ``installation_taken``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `ticket` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Forget a GitHub installation {#op-delete-api-v1-git-github-installations-installation-ref}

`DELETE /api/v1/git/github/installations/{installation_ref}`

Forget an installation. The deployments that cloned through it
(``detached``) keep their repository address and build as a pasted
repository would. The App stays installed on GitHub until its account
uninstalls it there (``manage_url``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `installation_ref` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List an installation's repositories {#op-get-api-v1-git-github-installations-installation-ref-repositories}

`GET /api/v1/git/github/installations/{installation_ref}/repositories`

One page of the repositories the installation reaches, for the
repository picker. A suspended installation answers 409.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `installation_ref` | path | integer | yes |  |
| `page` | query | integer | no | The page, from 1, in the order GitHub lists them Default: `1`. |
| `per_page` | query | integer | no | Repositories on a page Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |