Tutorial External CICD

Tutorial: External CI/CD

Run zyvor-qa as a QA gate inside your own project’s pipeline — no checkout of ZyAIQAAgent, no committed .env. Uses the published GHCR image and/or the reusable GitHub Action.

Deep docs: Tutorial 15 · action.yml · templates/ci/.

Want GitHub as a spec source (issues/docs → generate tests)? That is Tutorial: GitHub Integration.

Two paths

A) GitHub Actions — reusable Action

jobs:
  qa:
    runs-on: ubuntu-latest   # Docker Action = Linux only
    steps:
      - uses: hypersdk/ZyAIQAAgent@v0.4.0
        id: qa
        with:
          command: test
          target-url: https://staging.example.com
          grep: '@smoke'
          # For AI commands (run / create / flow --describe):
          # openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          # fail-on-error: 'true'   # default; set 'false' for report-only

      - name: Publish QA artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: zyvor-qa-report
          path: reports/

      - name: Gate on failures
        if: steps.qa.outputs.failed != '0'
        run: exit 1

Useful inputs: command, args, target-url, grep, shard, zyvor-env, target-allowlist, allow-private-targets, llm-provider, openai-api-key, anthropic-api-key, fail-on-error.

Outputs: exit-code, passed, failed, summary-path (from reports/summary.json).

Image under the hood: ghcr.io/hypersdk/zyaiqaagent:v0.4.0.

B) Any CI — container directly

docker run --rm \
  -e ZYVOR_BASE_URL=https://staging.example.com \
  -v "$PWD/reports:/app/reports" \
  ghcr.io/hypersdk/zyaiqaagent:v0.4.0 \
  test --grep @smoke

Copy-paste starters:

CI	Template
GitLab CI	templates/ci/gitlab-ci.yml
CircleCI	templates/ci/circleci-config.yml
Jenkins	templates/ci/Jenkinsfile
Azure Pipelines	templates/ci/azure-pipelines.yml

.env gotcha

zyvor-qa only auto-loads the .env next to its installed package, never your product repo’s .env. In external CI, pass settings as env vars / secrets only.

Exit-code contract

Commands	Exit 0	Exit 1	Exit 2
run, test, flow, api-test, ai-test, auth-test, har-replay, realtime	all passed	failures	—
flow			missing --describe and --steps
route-sweep	no route over visual threshold	routes changed	—
vitals	all CWV “good”	below “good”	—

reports/summary.json contract

{
  "schema_version": 1,
  "command": "test",
  "target_url": "https://staging.example.com",
  "passed": 18,
  "failed": 0,
  "status": "passed",
  "exit_code": 0,
  "artifacts": { "raw_json": "reports/results.json" }
}

jq -r '.failed' reports/summary.json

Upload reports/ (+ test-results/, screenshots/, traces/ if present) as CI artifacts.

Env vars for CI

Variable	Purpose
ZYVOR_BASE_URL	URL under test
ZYVOR_GREP / ZYVOR_SHARD	Filter / shard
ZYVOR_ENV	development (permissive) or production (allowlist)
ZYVOR_TARGET_ALLOWLIST	Hosts allowed in production mode
ZYVOR_ALLOW_PRIVATE_TARGETS / ZYVOR_ALLOW_HTTP_TARGETS	Overrides
OPENAI_API_KEY / ANTHROPIC_API_KEY / …	Only for AI commands

Private staging: start with ZYVOR_ENV=development, or set production + allowlist hostname.

Troubleshooting

Symptom	Fix
Target rejected by policy	Allowlist host or use ZYVOR_ENV=development
Playwright missing (non-container)	Prefer the GHCR image
create / AI cmds fail immediately	Provide LLM secret
Committed .env ignored	Expected — use CI secrets

Next

• Tutorial: GitHub Integration — specs from issues/PRs
• Tutorial: Agent CI & Kubernetes — agent repo workflows + k8s
• CI-CD hub · Configuration