# First steps At the end of this tutorial, your instance has a first admin, a workspace with GitHub data, and a first practice review that you approved. Do stages 1 and 2 before you install: the install pages tell you when. After the install, all three install paths continue at stage 3. ## Before you start * The host name of the instance. * A GitHub organization in which you can create and install apps. * An account at an AI provider, with an API key. * For stage 3 and later, an installed instance: [on one host](/next/admin/k3s.md), [on a Kubernetes cluster](/next/admin/kubernetes.md), or [on a managed cluster](/next/admin/managed-cluster.md). This tutorial uses GitHub for sign-in and for repository data. ## 1. Configure a login provider GitHub sign-in needs a plain **OAuth App**. This is *not* the GitHub App for data access, which stage 4 creates. Without a login provider, the instance starts but shows **no sign-in button**. 1. Open [github.com/settings/developers](https://github.com/settings/developers), or the same settings of your organization. 2. Select **New OAuth App**. 3. Set **Homepage URL** to `https://`. 4. Set **Authorization callback URL** to `https:///api/login/oauth2/code/github`. The URL must include `/api` and have no trailing slash. 5. If the GitHub settings page offers an image upload, use [`external-app-icon-1024.png`](/next/assets/files/external-app-icon-1024-539c74c977c34877ef79fc784a21e5e1.png) as the application logo. 6. Create a client secret. 7. Give the client ID and the client secret to the install: * On one host, the installer asks for both. * On a Kubernetes cluster, set the client ID as `config.github.oauthClientId` in `site.yaml`. Put the client secret in the [Secret](/next/admin/kubernetes.md#create-the-secret) as `GITHUB_OAUTH_CLIENT_SECRET`. ## 2. Name the first admin The admin UI requires admin access, so the **first instance admin comes from the install values**, not from the UI. 1. On one host, give the installer your GitHub login when it asks. It writes your numeric GitHub user ID into the admin list. 2. On a Kubernetes cluster, set `config.auth.bootstrapAdmins: ["github:1234567"]` in `site.yaml` before the first start. Use your numeric GitHub user ID, from `https://api.github.com/users/`. On public github.com, another person can take an abandoned login, but never a numeric ID. Add one item for each admin, as `:` or `:@`. Hephaestus makes each listed person an instance admin when they sign in. It never removes the admin role from a person. To add an admin later, change `config.auth.bootstrapAdmins` in `site.yaml`. Then run the installer again on one host, or `helm upgrade --install` with your values on a cluster. For the break-glass bootstrap token, see [Instance administration](/next/admin/instance-admin.md#bootstrap-and-recovery). ## 3. Sign in 1. Open `https://`. The login page shows **Continue with GitHub**. 2. Sign in as the bootstrap admin. You see the instance-admin navigation. ## 4. Connect repository data Sign-in alone syncs nothing. A **GitHub App** reads the repositories, receives their webhooks, and posts feedback with its own identity. 1. Read the webhook secret of the instance from the release Secret. On one host, run `export KUBECONFIG=~/hephaestus/kubeconfig` first: ``` kubectl --namespace hephaestus get secret hephaestus-app -o jsonpath='{.data.WEBHOOK_SECRET}' | base64 -d ``` 2. Create the GitHub App, as [GitHub App mode](/next/admin/github-integration.md#github-app-mode) describes. Its webhook URL is `https:///webhooks/github`, and its webhook secret is the value from step 1. 3. Install the App on your organization, and set its chart values and Secret keys, as [Install and configure](/next/admin/github-integration.md#install-and-configure) describes. 4. Open **Instance administration → GitHub installations**. 5. Select **Adopt** for the installation. Hephaestus creates the workspace with you as its owner and starts the first sync. ## 5. Check the instance 1. Open **Instance administration → Overview**. 2. Read the **Configuration readiness** card. Each item under **Action required** needs a change and links to its section in [Configuration readiness](/next/admin/configuration-readiness.md). **Not configured** lists optional settings that you have not set, such as email. Leave them until you want them. The card never shows the value of a setting. 3. Correct each item under **Action required**. The card then reads **Every check that applies to this instance passes.** 4. In the settings of your GitHub App at GitHub, open **Advanced → Recent deliveries**. The latest deliveries show the response `202`. If the list is empty, open a pull request in a repository of the installation. [Failed deliveries and redelivery](/next/admin/github-integration.md#failed-deliveries-and-redelivery) helps with another response. 5. Optional: if you scrape metrics, check that Prometheus shows the target of each server Pod as up. [Scrape metrics](/next/admin/monitoring.md#scrape-metrics) gives the scrape configuration and `networkPolicy.metrics`. ## 6. Connect an AI provider Practice reviews need sandboxes. The one-host install, `small.yaml` and `cluster.yaml` turn them on. `dev.yaml` runs no practice reviews. 1. Connect the provider, then price, enable, and share a model, as [The staged flow](/next/admin/ai-providers.md#1-the-staged-flow-and-why-it-is-staged) describes. 2. As a workspace admin, assign the model to **Practice reviews** on the **AI models** page of the workspace. The row shows the model and does not read **Not ready**. ## 7. Run the first practice review A new instance starts in **Silent mode**. Sync and reviews can run, but outbound feedback is blocked. 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](/next/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 request before you approve it. 5. Open the feedback, and read the problems behind it. 6. Open **Instance administration → Instance settings**. 7. Turn silent mode off. This does not send the feedback that silent mode withheld. [Silent mode](/next/admin/instance-admin.md#silent-mode) describes the switch. 8. Approve or reject the feedback. ## Next steps * [Integration settings](/next/admin/production-setup.md): turn on GitLab, Slack, Outline, or email. * [Publish the legal pages](/next/admin/legal-pages.md): a public instance needs its own imprint and privacy notice before it admits users. * [Set up the Chrome extension](/next/admin/browser-extension.md): show practice reviews on GitHub or GitLab work pages. * [Run practice reviews](/next/admin/practice-review.md): widen review scope or raise the feedback mode.