# First steps

These steps are the same on each deployment: the Helm chart on [Kubernetes](/admin/kubernetes.md), or the deprecated [Docker Compose install](/admin/install.md) of the 0.x releases. Steps 1 and 2 set values before the first start, so the install pages link to them. Steps 3 to 7 follow the first start.

## 1. Configure a login provider

One enabled GitHub or GitLab login provider is enough. Slack and Outline are for account linking, not sign-in. The steps below configure GitHub. For GitLab, use the [GitLab rollout bundle](/admin/production-setup.md#gitlab-rollout-bundle).

GitHub login needs a plain **OAuth App**. This is *not* the GitHub App for data access: see [GitHub integration](/admin/github-integration.md). Without a login provider, the instance boots but shows **no sign-in button**.

1. Open [github.com/settings/developers](https://github.com/settings/developers), or your organization's equivalent settings.

2. Select **New OAuth App**.

3. Set **Homepage URL** to `https://<your hostname>`.

4. Set **Authorization callback URL** to `https://<your hostname>/api/login/oauth2/code/github`. The string must include `/api` and have no trailing slash.

5. If the GitHub settings page offers an image upload, use [`external-app-icon-1024.png`](/assets/files/external-app-icon-1024-539c74c977c34877ef79fc784a21e5e1.png) as the application logo.

6. Create a client secret.

7. Store the client ID and the client secret:

   | Deployment     | Client ID                                    | Client secret                                                                        |
   | -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ |
   | Kubernetes     | `config.github.oauthClientId` in `site.yaml` | `GITHUB_OAUTH_CLIENT_SECRET` in the [Secret](/admin/kubernetes.md#create-the-secret) |
   | Docker Compose | `GH_OAUTH_CLIENT_ID` in `.env`               | `GH_OAUTH_CLIENT_SECRET` in `.env`                                                   |

## 2. Name the first admin

The admin UI requires admin access. The **first instance admin must therefore come from operator config**, not the UI.

1. Before the first start, set the first admin. On Kubernetes, set `config.auth.bootstrapAdmins` in `site.yaml`. On Docker Compose, set it in `.env`:

   ```
   HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS=github:@your-github-username
   ```

   The format is comma-separated `<provider>:@<username>` or `<provider>:<numeric-id>`. Promotion occurs **on sign-in**. It is idempotent and never demotes.

2. On public github.com, prefer the numeric ID (`github:1234567`, from `https://api.github.com/users/<login>`). Others can reclaim abandoned handles.

3. If you omitted the value, add it. Then run the install command again: `helm upgrade --install` on Kubernetes, or `docker compose up -d` on Docker Compose.

For the break-glass bootstrap token, see [Instance admin](/admin/instance-admin.md#bootstrap-and-recovery).

## 3. Sign in

After the first start:

1. Open `https://<your hostname>`. The login page should offer **Continue with GitHub**.

2. Sign in as the bootstrap admin. You should see instance-admin navigation.

3. Open **Instance administration → Overview**.

4. Read **Configuration readiness**.

   Each item under **Action required** needs a change and links to its section in [Configuration readiness](/admin/configuration-readiness.md). **Not configured** lists optional settings you have not set, such as email. The page never shows a setting's value.

5. Leave optional settings until you want them.

6. Create your first workspace.

7. Connect it to GitHub.

## 4. Connect repository data

A new instance starts in **Silent mode**. Sync and reviews can run, but outbound feedback is blocked. Turning silent mode off does not replay feedback withheld while it was on. See [Instance admin](/admin/instance-admin.md#silent-mode).

1. Check the deployment and integrations.
2. Open **Instance admin → Instance settings**.
3. Turn silent mode off.

For GitLab workspaces, use [Integrations](/admin/integrations.md#gitlab). For GitHub:

Login alone syncs nothing. Data flow requires two things. Both have procedures in [GitHub integration](/admin/github-integration.md):

1. **Repository access** — use a **PAT** in the workspace UI for the simplest setup. A **GitHub App** is necessary to post AI-review feedback to GitHub and offers better rate limits.
2. **Webhooks** — Hephaestus does **not** auto-register GitHub webhooks (unlike GitLab). Configure the webhook on your GitHub App **or** create an org/repo webhook manually, pointing at `https://<your hostname>/webhooks/github` with your `WEBHOOK_SECRET`. Without it the instance only sees changes on the hourly sync poll, and nothing warns you.

## 5. Optional integrations

All optional integrations are off by default. [Integration settings](/admin/production-setup.md) describes the settings of each. On Kubernetes, [Integration values](/admin/kubernetes.md#integration-values) names the chart values and the Secret keys of each.

1. Enable the desired integrations.
2. Run the install command again: the `helm upgrade --install` command of [Install](/admin/kubernetes.md#install) step 6 on Kubernetes, or `docker compose --env-file .env --env-file release-lock.env up -d` on Docker Compose.

| Add-on             | What it gives you                                                                                                                  | Where                                                                 |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| GitLab             | GitLab login, workspaces, and sync (webhooks auto-register here)                                                                   | [GitLab bundle](/admin/production-setup.md#gitlab-rollout-bundle)     |
| Slack              | Hephaestus in Slack DMs, channel ingestion                                                                                         | [Slack app setup](/admin/production-setup.md#slack-app-configuration) |
| Outline            | Wiki as a content source for reviews                                                                                               | [Outline integration](/admin/production-setup.md#outline-integration) |
| AI practice review | Automated PR feedback from the coding agent                                                                                        | [Practice review](/admin/practice-review.md#first-successful-review)  |
| Email              | Optional invitations, summaries, weekly digest notes, and connection alerts. Configure `SPRING_MAIL_*` and `HEPHAESTUS_EMAIL_FROM` | [Email setup](/admin/production-setup.md#email)                       |
| An AI provider     | The model everything AI runs on — required by the row above                                                                        | [Connect an AI Provider](/admin/ai-providers.md)                      |

AI practice review requires a running worker and a model that the workspace can run on. On Kubernetes, the `small.yaml` profile enables the worker. On Docker Compose, set `AGENT_ENABLED` and `GIT_CHECKOUT_ENABLED` together on each role that submits or claims work.

The job queue runs on PostgreSQL, so practice review needs no NATS setup.

[Connect an AI Provider](/admin/ai-providers.md) explains model setup. It covers provider connection registration, tests, model prices, model shares, and an assignment to the **practice reviews** purpose. No reviews run until setup is complete.

If the worker runs but no model is assigned, reviews do not run. Hephaestus records each review opportunity with the reason **No AI model is assigned to practice review.** The reason is visible under **Practices → Practice reviews → Work**. A workspace without an assigned model is a normal state.

### Chrome extension

The optional [Chrome extension](/admin/browser-extension.md) shows practice reviews on GitHub or GitLab work pages. The guide explains how to allow sign-in and distribute the extension to users.

## 6. Legal pages (public instances)

CAUTION: Public instances need legal pages

`/imprint` and `/privacy` serve a red "not configured" fallback until you provide your own. For operators in Germany that is a § 5 DDG / Art. 13 GDPR obligation **before** opening the instance to users. See [Legal Pages](/admin/legal-pages.md).

## 7. First practice review

Before this procedure, GitHub must be connected (step 4). A model must also be assigned to practice reviews ([Connect an AI Provider](/admin/ai-providers.md)). The procedure runs one review and lets you read its feedback before anyone else can:

1. Open **Practices → Review settings → How much**.

2. Set the **Workspace default** to **Approve first**. Each piece of feedback waits for your approval.

3. Follow [First successful review](/admin/practice-review.md#first-successful-review).

4. When the review finishes, open **Practices → Practice reviews**. Its feedback is listed under **Needs you**, awaiting approval. Nothing reaches the pull or merge request before you approve it.

5. Open the feedback.

6. Read it.

7. Read the problems behind it.

8. Approve or reject the feedback.

9. Once the feedback reads as you want, widen coverage or increase feedback mode as [Practice review](/admin/practice-review.md) describes.