> For the complete documentation index, see [llms.txt](https://cjay-1.gitbook.io/lifeboat-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cjay-1.gitbook.io/lifeboat-docs/developer-guide/github-adapter-setup.md).

# GitHub adapter setup

The adapter turns signed GitHub webhooks into evidence candidates.

## 1. Create a GitHub App

In the organization that owns the consenting repository, create a GitHub App.

* **Webhook URL:** your adapter's public HTTPS address plus `/webhook`.
* **Webhook secret:** a random string of at least 24 characters. Use the same value in `LIFEBOAT_GITHUB_WEBHOOK_SECRET`.
* **Permissions:** the minimum needed to receive events, which is read access to pull requests, issues, and repository metadata. Grant nothing that writes.
* **Subscribe to events:** Pull request, Release, Issues.

## 2. Install it and note the installation ID

Install the App on the repository. The installation ID appears in the install URL and in every webhook payload under `installation.id`.

## 3. Enroll the project

The steward calls `POST /v1/projects` with the same `installation_id`.

## 4. Map the repository and start the adapter

Set `LIFEBOAT_GITHUB_PROJECTS_JSON` to a value like this:

```json
{"example-org/example-lib": {"project_id": "proj_demo", "installation_id": 123456}}
```

Then set the other variables from [Configuration](/lifeboat-docs/developer-guide/configuration.md) and run:

```bash
cd lifeboat-github && go run ./cmd/lifeboat-github
```

## 5. Put TLS in front

GitHub only delivers to HTTPS. Terminate TLS with a reverse proxy and forward to `127.0.0.1:8081`. Do not expose the adapter or the API directly.

## Response codes

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `201`  | Evidence recorded                        |
| `200`  | Duplicate delivery acknowledged          |
| `204`  | Event type or action ignored             |
| `400`  | Bad delivery ID, body, or evidence URL   |
| `401`  | Missing or invalid signature             |
| `403`  | Repository or installation not enrolled  |
| `415`  | Content type is not JSON                 |
| `502`  | API unreachable or rejected the evidence |

## Known gap

The repository mapping is static and read once at startup, so adding a repository means restarting the adapter. An auditable enrollment flow and handling of App suspension are open issues.