# GitHub and repositories

An organization connects GitHub App installations so its members can run on their repositories and discover Workbench packages in them. How runs use GitHub is on [Repositories and pull requests](/docs/cloud/repositories).

Connecting an installation is an interactive browser flow done from the dashboard's sources page. Its routes are session only:

| Method | Path                                       | Auth                               | Purpose                                                                                                                                                                                                                                                                           |
| ------ | ------------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/authorizations`                       | Session: manager                   | Start a GitHub authorization. Body `{ "organization_id", "installation_id"?, "return_to"?: "sources" or "onboarding" }`. Returns `{ "authorization_url", "install_url" }`.                                                                                                        |
| PATCH  | `/v1/authorizations/:id`                   | Session: the authorization's owner | Continue with a newly installed `installation_id`. Same response.                                                                                                                                                                                                                 |
| POST   | `/v1/installations/candidates`             | Session: the authorization's owner | List what GitHub's OAuth `code` reaches. Links nothing.                                                                                                                                                                                                                           |
| POST   | `/v1/installations`                        | Session: the authorization's owner | Link exactly the chosen installations. Body `{ "state", "selection", "installation_ids" }`.                                                                                                                                                                                       |
| GET    | `/v1/installations?organization_id=<uuid>` | Session: member                    | Connected installations and, for managers, reusable ones.                                                                                                                                                                                                                         |
| POST   | `/v1/installations/discoveries`            | Session: manager                   | List the installations the user can reach from their saved GitHub authorization, without a new GitHub prompt. Body `{ "organization_id", "return_to" }`. Returns `{ "status": "connected", "state", "listing" }`, or `{ "status": "disconnected" }` or `{ "status": "expired" }`. |
| DELETE | `/v1/installations/:id`                    | Session: manager                   | Unlink an installation. Returns `{ "deleted": true }`.                                                                                                                                                                                                                            |

Each candidate has a `status`: `linkable` (no organization links it), `linked` (this one already does), `reusable` (another organization you belong to links it), or `unavailable`, with a `reason`. Being able to see an installation is not enough to link it: on a personal account it must be yours, and on a GitHub organization you must be an active admin. A `selection` token is valid for 10 minutes, and linking ends the authorization.

The installation object has `id`, `organization_id`, `installation_id`, `account_id`, `account_login`, `account_type` (`Organization` or `User`), `settings_url`, `created_at`, and `updated_at`.

## Repositories

Repositories synced from the organization's installations.

### The repository object

| Field                                             | Meaning                                |
| ------------------------------------------------- | -------------------------------------- |
| `id`, `organization_id`, `github_installation_id` | UUIDs.                                 |
| `github_id`                                       | GitHub's repository ID.                |
| `owner`, `name`, `url`                            |                                        |
| `default_branch`                                  |                                        |
| `visibility`                                      | `public` or `private`.                 |
| `status`                                          | `active`, `unavailable`, or `removed`. |
| `last_commit`, `last_synced_at`                   | Or null.                               |
| `created_at`, `updated_at`                        |                                        |

### List repositories

`GET /v1/repositories?organization_id=<uuid>`

Key `catalog:read`, or session: member. Response `200` `{ "repositories": [ ... ] }`.

### Refresh repositories

`POST /v1/syncs` with `{ "organization_id": "uuid" }`

Key `packages:write`, or session: member. Reads repositories from every installation again. Response `201` `{ "repositories": [ ... ] }`.

## Discover packages

`POST /v1/discoveries` with `{ "repository_id": "uuid" }`

Key `packages:write`, or session: member. Finds `.workbenches/*` packages in a repository at its current commit, through GitHub's API. Nothing is cloned.

Response `201`:

```json
{
    "repository_id": "uuid",
    "source_commit": "4f2c...",
    "workbenches": [
        {
            "source_path": ".workbenches/core/workbench.yml",
            "slug": "core",
            "valid": true,
            "errors": [],
            "manifest": {
                "spec": 1,
                "version": "0.1.0",
                "name": "core",
                "...": "..."
            }
        }
    ]
}
```

Submit discovered packages for review with the GitHub form of `POST /v1/submissions`; see [Workbenches and registry](/docs/api/workbenches#submit-for-review).