GitHub Actions

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

For App-based auto-runs, the Certyn GitHub App must subscribe to pull_request, push, and deployment_status and have repository access for Pull requests (read), Contents (read), Deployments (read), and Checks (write). These permissions are managed by the Certyn GitHub App administrator, not in an individual project rule.

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.

Automatic environment updates from GitHub deployments

An App-based On deployment rule can update its selected Certyn environment automatically when GitHub reports a successful deployment. The rule records a version-history entry before starting the suite. Environment sync is enabled by default and can be disabled in the rule.

Certyn reads optional version and changelog values from the GitHub deployment payload. When they are absent, it uses the deployed commit SHA as the version and the deployment description as the changelog. GitHub webhook redeliveries do not create duplicate runs or version-history entries.

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

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.