Tutorial GitHub Integration

Tutorial: GitHub Integration

Connect a product repository as the requirement source: fetch specs/issues, run the pipeline, comment on PRs, and optionally auto-run via webhooks.

Deep docs: Tutorial 04 · Test Authoring.

Different from external CI? This tutorial uses the agent against GitHub as a spec source. To gate any project’s pipeline with the published container/Action (no agent checkout), see Tutorial: External CI/CD.

1. Authenticate

# Recommended
gh auth login

# Or in .env
GITHUB_TOKEN=ghp_...

Needs Contents: Read; add Pull requests: Write for PR comments. Verify: gh auth token.

2. Point at the product repo

# .env — owner/repo, not a URL
ZYVOR_PRODUCT_REPO=ssahani/hypersdk-web
ZYVOR_BASE_URL=https://staging.example.com

3. Run from a GitHub spec

zyvor-qa run --source github --spec docs/specs/my-feature.md

# Blob / raw URLs also work
zyvor-qa run --source github \
  --spec https://github.com/owner/repo/blob/main/docs/specs/my-feature.md

File lands in tests/fixtures/fetched/, then parse → generate → execute → report.

4. Run from everything (no --spec)

zyvor-qa run --source github

Source	Saved as
Open issues labeled qa, user-story, feature-spec, or enhancement	issue-<n>.md
Every .md in docs/specs/	spec-*.md
CHANGELOG.md, README.md	spec-*.md

Tip: treat qa-labeled issues as your test backlog.

5. Comment on a pull request

zyvor-qa run --source github --spec docs/specs/my-feature.md --pr-number 42

Posts pass/fail, optional LLM summary, failure analysis, coverage hints. The PR body is also parsed as a spec; changed files scope coverage discovery.

6. Webhook auto-runs

# .env
GITHUB_WEBHOOK_SECRET=<random-string>

zyvor-qa serve --port 8080

Product repo → Settings → Webhooks → Add webhook:

Field	Value
Payload URL	https://<host>:8080/webhook/github
Content type	application/json
Secret	same as GITHUB_WEBHOOK_SECRET
Events	push, pull_request, (+ repository_dispatch for deploys)

Event	Behavior
pull_request	Full pipeline; comment on PR
push	Full pipeline; changed files scope coverage
repository_dispatch (staging-deployed)	Post-deploy pipeline

Local check:

curl -s http://localhost:8080/health   # {"status":"ok"}
# Tunnel (ngrok / cloudflared / ssh -R) for real GitHub delivery

Fire post-deploy from your deploy job:

gh api repos/$ZYVOR_PRODUCT_REPO/dispatches \
  -f event_type=staging-deployed \
  -F 'client_payload[pr_number]=42'

7. Generate-only (review before run)

zyvor-qa generate --source github --spec docs/specs/my-feature.md
git diff tests/generated/

Next

• Tutorial: External CI/CD — reusable Action / container in your repo
• Tutorial: Agent CI & Kubernetes — this agent’s own smoke/post-deploy workflows
• Coverage expansion: Tutorial 05