Skip to main content

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​

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, or the same settings of your organization.
  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 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 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 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/<login>. On public github.com, another person can take an abandoned login, but never a numeric ID.

Add one item for each admin, as <provider>:<numeric-id> or <provider>:@<username>. 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.

3. Sign in​

  1. Open https://<your hostname>. 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 describes. Its webhook URL is https://<your hostname>/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 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. 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 helps with another response.
  5. Optional: if you scrape metrics, check that Prometheus shows the target of each server Pod as up. 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 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.
  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 describes the switch.
  8. Approve or reject the feedback.

Next steps​