GitHub Actions

Use certyn-one/action@v1 when GitHub Actions should trigger Certyn from a pull request, deploy, nightly job, or manual workflow.

The action can run in three modes:

• Run a predefined process with process_slug.
• Run tests selected by tags.
• Ask Certyn with instruction only, letting Certyn decide what to inspect or update.

You can also combine instruction with process_slug or tags when you want deterministic test gating plus an AI summary or follow-up task.

Prerequisites

Create a Certyn API key and store it as a GitHub secret.

Required secret:

• CERTYN_API_KEY

Common variables:

• CERTYN_PROJECT_SLUG
• CERTYN_ENVIRONMENT_KEY
• CERTYN_API_URL if you are not using https://api.certyn.io

Recommended API key scopes:

• ci:trigger
• ci:status
• ci:cancel

See API Keys API for API key creation and scope details.

Inputs

Minimum inputs:

api_key: ${{ secrets.CERTYN_API_KEY }}
project_slug: my-app

Choose one of these execution selectors:

• process_slug: smoke-suite
• tags: smoke,critical
• instruction: "Ask Certyn what to do"

process_slug and tags are mutually exclusive. instruction can be used by itself or alongside one selector.

Useful control inputs:

• environment_key: target environment, such as staging or prod.
• wait_for_completion: defaults to true.
• timeout_seconds: defaults to 1800.
• fail_on_failed: defaults to true.
• fail_on_blocked: defaults to true.
• cancel_on_timeout: defaults to true.

Common outputs:

• run_id
• status_url
• app_url
• state
• conclusion
• total, passed, failed, blocked, pending, skipped
• conversation_id, conversation_state, conversation_response when instruction is used

PR Smoke Gate

Use a predefined smoke process when a pull request should fail if critical paths fail or are blocked.

name: Certyn PR Smoke Gate

on:
  pull_request:
    branches: [main]

jobs:
  certyn:
    runs-on: ubuntu-latest
    steps:
      - name: Run Certyn smoke suite
        id: certyn
        uses: certyn-one/action@v1
        with:
          api_key: ${{ secrets.CERTYN_API_KEY }}
          project_slug: ${{ vars.CERTYN_PROJECT_SLUG }}
          environment_key: ${{ vars.CERTYN_ENVIRONMENT_KEY || 'staging' }}
          process_slug: smoke-suite

      - name: Add Certyn summary
        if: always()
        run: |
          echo "## Certyn Result" >> "$GITHUB_STEP_SUMMARY"
          echo "- Run: ${{ steps.certyn.outputs.status_url }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- Failed: ${{ steps.certyn.outputs.failed }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- Blocked: ${{ steps.certyn.outputs.blocked }}" >> "$GITHUB_STEP_SUMMARY"

Tagged Critical Tests

Use tags when you want a small, configurable set of tests without creating a dedicated process.

- uses: certyn-one/action@v1
  with:
    api_key: ${{ secrets.CERTYN_API_KEY }}
    project_slug: my-app
    environment_key: staging
    tags: smoke,critical
    fail_on_failed: true
    fail_on_blocked: true

Ask Certyn After Deploy

Use instruction-only mode when Certyn should decide what to inspect based on project context and the task you give it.

name: Ask Certyn After Deploy

on:
  push:
    branches: [main]

jobs:
  ask-certyn:
    runs-on: ubuntu-latest
    steps:
      - uses: certyn-one/action@v1
        id: certyn
        with:
          api_key: ${{ secrets.CERTYN_API_KEY }}
          project_slug: my-app
          environment_key: staging
          instruction: |
            We deployed ${{ github.sha }} to staging.
            Bump the staging environment version.
            Inspect the riskiest user journeys affected by this release.
            Run relevant smoke coverage and create new test cases for gaps.

      - name: Print Certyn response
        run: echo "${{ steps.certyn.outputs.conversation_response }}"

Instruction-only mode creates an Ask Certyn run. It is useful for release review, environment updates, exploratory checks, test-case creation, and other assistant-driven workflows.

For hard merge or deploy gates, prefer process_slug or tags so the action gates on known test counters.

Post-Deploy Smoke Plus AI Summary

Combine process_slug and instruction when you want deterministic smoke gating and an AI response in one step.

- uses: certyn-one/action@v1
  id: certyn
  with:
    api_key: ${{ secrets.CERTYN_API_KEY }}
    project_slug: my-app
    environment_key: prod
    process_slug: production-smoke
    instruction: |
      Production was updated to ${{ github.sha }}.
      Summarize smoke test health, user-facing risk, and recommended follow-up.

- name: Add Certyn AI summary
  if: always()
  run: |
    cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
    ## Certyn AI Summary

    ${{ steps.certyn.outputs.conversation_response }}
    EOF

Pass Release Change Context

The action sends repository metadata, ref, commit SHA, event name, and workflow run URL. If you want Certyn to reason about release changes reliably, pass a compact change summary in instruction.

- uses: actions/checkout@v4
  with:
    fetch-depth: 2

- name: Build change summary
  id: changes
  run: |
    {
      echo "summary<<EOF"
      git log --oneline -20
      echo ""
      git diff --name-status HEAD~1..HEAD
      echo "EOF"
    } >> "$GITHUB_OUTPUT"

- uses: certyn-one/action@v1
  id: certyn
  with:
    api_key: ${{ secrets.CERTYN_API_KEY }}
    project_slug: my-app
    environment_key: staging
    instruction: |
      We deployed ${{ github.sha }} to staging.

      Release changes:
      ${{ steps.changes.outputs.summary }}

      Bump the staging environment version.
      Run relevant smoke coverage.
      Create new test cases for uncovered high-risk behavior.

For large releases, pass a compact summary, changed file list, PR title/body, or release notes instead of a full diff.

Fire And Forget

Set wait_for_completion: false when another workflow, dashboard, or notification system will track the run.

- uses: certyn-one/action@v1
  id: certyn
  with:
    api_key: ${{ secrets.CERTYN_API_KEY }}
    project_slug: my-app
    process_slug: smoke-suite
    wait_for_completion: false

- run: echo "Run URL ${{ steps.certyn.outputs.status_url }}"

Recommended Placement

Team workflow	Where to place Certyn
Pull requests	Smoke gate with process_slug or tags
Post-deploy staging	Smoke gate plus optional instruction
Production deploy	Production smoke process with strict failure/blocking rules
Nightly	Regression process
Release review	Instruction-only Ask Certyn run with release notes or changed files

Troubleshooting

• 401 or 403: check the API key and make sure it has ci:trigger, ci:status, and ci:cancel.
• Project not found: verify project_slug matches the Certyn project slug.
• Environment not found: verify environment_key exists in the project.
• No matching test cases found: confirm the process or tags select active, non-quarantined tests.
• Duplicate runs after workflow retries: keep the default idempotency key or pass your own idempotency_key.