GitHub Actions PR gate

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

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

Related documentation