GitHop/docs/local-development.md

Local development

Start the foundation

Requirements: Docker with Compose v2, Go 1.26 or newer for host-side tests, and ports 3000, 8080, and 2222 available.

cp .env.example .env
make up

Open Gitea at http://localhost:3000. The Hop control plane exposes health at http://localhost:8080/healthz and readiness at http://localhost:8080/readyz.

Gitea self-registration is enabled for this local stack. After creating the first account, create an access token in Gitea and set GITEA_API_TOKEN in .env, then restart the control plane:

docker compose up -d --force-recreate control-plane

Link a repository

Create a repository in Gitea, then ask Hop to verify it through the Gitea API and record the link:

set -a
. ./.env
set +a

curl --fail-with-body \
  -H "Authorization: Bearer $HOP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"YOUR_USER","name":"YOUR_REPOSITORY"}' \
  http://localhost:8080/api/v1/repositories/link

Configure a webhook

In the Gitea repository, create a Gitea webhook with:

• target URL: http://control-plane:8080/api/v1/gitea/webhooks
• content type: application/json
• secret: the value of HOP_GITEA_WEBHOOK_SECRET in .env
• events: all events

The control plane verifies X-Gitea-Signature against the raw request body, records each delivery exactly once, and refreshes repository metadata from the signed payload.

Useful commands

make test
make config
make logs
make down

To destroy local data as well as containers, run docker compose down -v.