Set up a workspace

This walkthrough follows the Next steps checklist on the Overview page of a new workspace. It takes an administrator from an empty workspace to a service that people can request changes on. Steps 1 to 3 give you a governed workspace. Steps 4 and 5 are needed before the request-to-pull-request flow can run; deployments are separate and optional. If you have not created the workspace yet, or are unsure who “your operator” is, read Before you begin first.

Who can do this

A workspace Owner or Administrator. The first sign-in on a fresh installation creates the workspace and its Owner; see Before you begin.

1. Connect a repository source

Open Settings → Repositories and choose Add source. Pick Gitea bot or GitHub App. The identity you connect defines the ceiling of what Helmhive can see; nothing is enrolled by connecting it.

Details and provider differences: Connect a repository source.

2. Enroll a service

After the source synchronizes, the Repository candidates list shows what it can access. Choose Enroll service on the repository you want, give it a name and a stable slug, and choose Enroll and activate (or Save as draft).

Enrollment records identity only. The service page then opens on its Policy tab, where you confirm the detected commands, protected paths, expected checks, and repository read authority. Details: Enroll a service and Manage a service’s execution policy.

3. Invite people and assign roles

Everyone needs a platform account with a verified email, or Company SSO once you configure it. Open Settings → People. Invite member creates a workspace invitation (Member or Administrator). Grant service access assigns a Requester, Developer, or Administrator role on one service, creating a verified-email invitation when the person is new.

A service needs at least one Developer before any plan can be approved. Details: Invite people and assign roles.

4. Prepare AI delivery (needed for AI-generated plans)

Open AI and follow its readiness checklist: create an execution environment, register a runner, verify the provider sign-in, confirm the discovered models, and choose profiles. Then assign the environment revision to each service that should receive plans; without that binding, planning stays disabled for the service. Nothing in this area is required until a service should receive AI-generated plans, and two of its steps need your operator (a runner image and a runner host). Start with Set up AI delivery.

The change and pull-request capabilities on a service policy are currently enabled through the API by your operator; see Manage a service’s execution policy.

5. Enable pull-request delivery (needed to open pull requests)

Repository discovery is read-only. To let Helmhive push a branch and open a pull request, configure a separate bot with an exact repository allowlist under Settings → Repositories → Pull request delivery. See Enable pull-request delivery.

6. Prepare deployments (optional)

Deployment is independent from change delivery, with its own runners, connections, environments, and approvals. Start with Set up deployments.

What the checklist means

Each step on the Overview page shows Complete, Next step, or Not started. A step is computed from live facts, never from a flag you set: a repository source counts as connected only while its connection is healthy, and AI assistance counts as prepared only while a runner is online, authenticated, active, publishing a model that an active profile maps to. When a check cannot run, the step shows Last known or Could not check, and nothing is changed for you.