First Issue Walkthrough

This walkthrough takes you from a fresh environment to your first merged pull request produced by the OpenFlows team. It is the fastest path to seeing the whole loop work.

1Stand up the control plane

Start with Coder, the coordination store, and the database running together (see Installation for the topology). Once they are up, confirm that Coder is reachable at your access URL.

2Bootstrap the environment

Run the bootstrap step. It:

• Creates the initial administrator.
• Registers the workspace templates for each agent role.
• Verifies that your model gateway and GitHub authentication are configured.

Bootstrap should complete cleanly. If it reports a missing integration - for example, GitHub authentication not set up - resolve that before continuing.

3Add a tenant for your repository

Add a tenant bound to the GitHub repository you want OpenFlows to work on. This creates the long-lived orchestrator workspace for that repository and initializes a fresh agent team.

A note on "tenant": in OpenFlows, one Coder server serves many teams. Each tenant is one team bound to one repository. If you only have one team, think of this simply as "setting up your project."

4Complete GitHub OAuth for that tenant

OpenFlows acts on GitHub through a real identity, not a shared token. In the Coder dashboard (or the OpenFlows control panel), link GitHub OAuth for the tenant you just created. This is how agents gain the ability to push branches, open pull requests, and comment on issues - scoped to that identity. No raw token ever sits inside a worker workspace. See the Identity & OAuth page for the full model.

5(Optional) Turn on notifications

For the smoothest experience, configure at least one notification channel (Slack, Discord, or WhatsApp). These are how OpenFlows tells you when it needs a human decision and how it surfaces reactions you must make. Without them, it still works - you would just check the control panel.

6Open an issue

Create a clearly-scoped GitHub issue in the bound repository. The better the issue is described, the better the plan FORGE will produce. A good issue contains:

• Context - why the change is needed.
• Goal - a single sentence describing what success looks like.
• Constraints - non-functional requirements such as performance or security.
• Acceptance criteria - a checklist the reviewer can verify against.

You do not need to write a plan, write tests, or assign the issue. The team handles all of that.

7Review what came back

When the work finishes, you get a merged pull request plus a record of the decisions made along the way. If at any point OpenFlows needed a human call - a security concern, an ambiguous spec, or a merge block - you were notified. Walk to that decision, resolve it, and the team continues. See Completion & Merge for how to review what came back.

Next steps