Setup Guide

Setup Guide

This guide walks through everything required to run gsd-orchestrator from a clean machine. Every step is copy-pasteable and verified against the source code.

Prerequisites

• Windows (10 or later)
• .NET 10 SDK — required to build and run the orchestrator
• GitHub Personal Access Token — required scopes: repo, read:org. Create at https://github.com/settings/tokens
• Anthropic API key — required for autonomous orchestrator operation. Create at https://console.anthropic.com

Clone the Repository

git clone https://github.com/Coding-Autopilot-System/gsd-orchestrator.git
cd gsd-orchestrator

Configure Environment

cp .env.example .env

Then edit .env and fill in the four required values:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
ANTHROPIC_API_KEY=sk-ant-your_key_here
GSD_GITHUB_OWNER=your-github-username-or-org
GSD_GITHUB_REPO=your-target-repository-name

Security note: .env is listed in .gitignore. Never commit it to the repository.

Optional Variables

• GSD_REVIEWERS — comma-separated GitHub usernames to request as PR reviewers (leave empty to skip)
• GSD_AUTO_MERGE=true — automatically squash-merges the PR after the Documenting state completes
• GSD_MCP_BINARY — full path to github-mcp-server.exe if auto-discovery fails

Run the Orchestrator

cd src/GsdOrchestrator
dotnet run -- --issue 42

Replace 42 with the GitHub issue number on your target repository.

To resume an interrupted workflow:

dotnet run -- --resume <workflow-id>

Checkpoint files are stored at .gsd/state/{workflowId}.json — the workflow ID is printed at startup.

To run in watch mode (polls open issues every 5 minutes):

dotnet run -- --watch

What a Successful Run Looks Like

What a successful run produces is the following terminal output showing state machine transitions:

info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      Workflow abc123def456 starting at state Idle
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Analyzing
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Branching
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Editing
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Validating
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Committing
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → PrCreating
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Reviewing
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Documenting
info: GsdOrchestrator.Workflows.GsdStateMachine[0]
      [abc123def456] → Done

✓ PR created:   https://github.com/your-org/your-repo/pull/N
✓ Docs updated: docs/github-mcp-tools.md, CHANGELOG.md
  Workflow ID:  abc123def456

If GSD_AUTO_MERGE=true, the PR will be squash-merged automatically after the Documenting state.