First steps

These steps are the same on each deployment: the Helm chart on Kubernetes, or the deprecated Docker Compose install 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.

GitHub login needs a plain OAuth App. This is not the GitHub App for data access: see GitHub integration. Without a login provider, the instance boots but shows no sign-in button.

1. Open 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 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
   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.

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. 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.

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

For GitLab workspaces, use Integrations. For GitHub:

Login alone syncs nothing. Data flow requires two things. Both have procedures in GitHub integration:

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 describes the settings of each. On Kubernetes, 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 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
Slack	Hephaestus in Slack DMs, channel ingestion	Slack app setup
Outline	Wiki as a content source for reviews	Outline integration
AI practice review	Automated PR feedback from the coding agent	Practice review
Email	Optional invitations, summaries, weekly digest notes, and connection alerts. Configure SPRING_MAIL_* and HEPHAESTUS_EMAIL_FROM	Email setup
An AI provider	The model everything AI runs on — required by the row above	Connect an AI Provider

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 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 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.

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). 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.

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 describes.