Skip to main content
The backend serves orchestration APIs, GitHub app endpoints, and internal APIs the UI relies on.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Go 1.25 or later
  • Atlas CLI (for database migrations)
  • PostgreSQL (running locally or via Docker)
  • Docker (optional, for running PostgreSQL)
If you don’t have Atlas installed, you can install it via Homebrew: brew install ariga/tap/atlas

​
Quick start

  1. Start PostgreSQL (if using Docker): 
    cd backend
docker-compose up postgres -d
  2. Run database migrations: 
    atlas migrate apply --url "postgres://postgres:23q4RSDFSDFS@127.0.0.1:5432/postgres?sslmode=disable"
    If you encounter checksum or dirty state errors, add the --allow-dirty flag:
    atlas migrate apply --url "postgres://postgres:23q4RSDFSDFS@127.0.0.1:5432/postgres?sslmode=disable" --allow-dirty
  3. Create backend/.env with the essentials (adjust DB URL/ports): 
    DATABASE_URL=postgres://postgres:root@localhost:5432/postgres?sslmode=disable
DIGGER_INTERNAL_SECRET=orchestrator-secret          # must match UI ORCHESTRATOR_BACKEND_SECRET
DIGGER_ENABLE_INTERNAL_ENDPOINTS=true               # enables /_internal/*
DIGGER_ENABLE_API_ENDPOINTS=true                    # enables /api/*
HOSTNAME=http://localhost:3000                      # used for GitHub app callbacks
    Optional but useful:
    • GITHUB_APP_ID, GITHUB_APP_PEM, GITHUB_APP_WEBHOOK_SECRET if you already have an app.
    • GITHUB_ORG if you want /github/setup to target an org.
  4. Start the service (from backend/): 
    set -a; source .env; set +a
go run main.go              # or: make start
    Default port: 3000.

​
Make the UI happy

  • The UI calls /api/* and /github/* with Authorization: Bearer $DIGGER_INTERNAL_SECRET and DIGGER_ORG_ID/DIGGER_USER_ID headers.
  • You must upsert the WorkOS org + user the UI is authenticated as: 
    SECRET=$DIGGER_INTERNAL_SECRET
ORG_ID=org_xxx                           # WorkOS org id
ORG_NAME=my-org                          # slug shown in backend
ADMIN_EMAIL=you@example.com
USER_ID=user_xxx                         # WorkOS user id
USER_EMAIL=$ADMIN_EMAIL

# org
curl -s -X POST http://localhost:3000/_internal/api/upsert_org \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"org_name":"'"$ORG_NAME"'","external_source":"workos","external_id":"'"$ORG_ID"'","admin_email":"'"$ADMIN_EMAIL"'"}'

# user
curl -s -X POST http://localhost:3000/_internal/api/create_user \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"external_source":"workos","external_id":"'"$USER_ID"'","email":"'"$USER_EMAIL"'","external_org_id":"'"$ORG_ID"'"}'

​
GitHub app integration

  • For a quick install link, set ORCHESTRATOR_GITHUB_APP_URL in ui/.env.local to your app’s install URL (https://github.com/apps/<app>/installations/new).
  • To create a new app via the backend, open http://localhost:3000/github/setup (requires HOSTNAME set to a reachable URL for callbacks).

​
Troubleshooting

  • 404 on /api/repos: ensure DIGGER_ENABLE_API_ENDPOINTS=true and the org/user above are created.
  • 401/403: verify Authorization header uses DIGGER_INTERNAL_SECRET.
  • GitHub connect 404: set ORCHESTRATOR_GITHUB_APP_URL as described.
Only use this for local development and testing. Never use NOOP_AUTH in production.
If you need to quickly test the backend without setting up authentication, you can disable it entirely by adding to your .env:
NOOP_AUTH=true
This bypasses all authentication checks, allowing you to call any endpoint without credentials.