Overview

This workflow installs the Zof CLI in GitHub Actions, runs a staging smoke suite on every pull request, and fails the job when validation does not pass, blocking merge until reliability criteria are met.

Replace ZOF_PROJECT_ID and suite name with values from Operate → Projects and Quality → Test suites. Never commit API keys; use repository secrets.

Who should read this

QA engineers, SREs, platform teams, and developers operating Zof Console and APIs.

Prerequisites

Organization API key or authenticated CLI
Staging environment for safe experimentation

When to use this workflow

Onboarding new team members to Zof terminology and workflows
Authoring internal runbooks aligned with Console labels
Designing CI/CD or webhook integrations against documented behavior

Step-by-step procedure

Create repository secrets

GitHub → Settings → Secrets → ZOF_API_KEY from Admin Center API keys.

ZOF_PROJECT_ID from Console project settings.

Add workflow file

Copy .github/workflows/zof-pr-gate.yml from this example.

Adjust --env and --suite to match staging names.

Enforce branch protection

Require the Zof PR Gate check before merge to main.

Document override process for hotfixes in team runbook.

Key concepts

Expected success: Job exits 0; run status passed in Console Operate → Runs.
Expected failure: Job exits non-zero; PR blocked; reviewers inspect run URL from Actions logs.

Best practices

Validate changes in staging before applying release gates to production.
Include run IDs and timestamps when escalating issues to support or auditors.
Align internal runbook terminology with Zof Console UI labels for clarity.

Common issues

Authentication failure: Invalid or expired ZOF_API_KEY; CLI exit code 2.
Queued run timeout: Agent capacity saturated; increase fleet or stagger suites.
Wrong environment: Suite targets URLs not reachable from cloud agents; use endpoint agents for private staging.

Example implementation

# .github/workflows/zof-pr-gate.yml
# Replace pr-smoke with your suite ID from Quality → Test suites
name: Zof PR Gate
on:
  pull_request:
    branches: [main]
jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @zof-ai/cli
      - name: Staging validation
        run: zof run --wait --env staging --suite pr-smoke
        env:
          ZOF_API_KEY: ${{ secrets.ZOF_API_KEY }}
          ZOF_PROJECT_ID: ${{ secrets.ZOF_PROJECT_ID }}
# Success: exit 0, run status passed
# Failure: exit non-zero, merge blocked when branch protection requires this check