GitHub Actions Tutorial

Automate your agent testing by integrating Cekura with GitHub Actions. This guide walks you through setting up workflows to test your agents automatically on every code change, pull request, or on a custom schedule. The Cekura GitHub Action is a simple, dependency-free solution that uses standard tools available on GitHub runners (curl, bash, and python3 for JSON parsing). No installation or setup required - it works out of the box.

Before You Get Started

Important: Before setting up a workflow, ensure your agent is properly configured with scenarios in the Cekura dashboard.

You’ll need your Agent ID and either Scenario IDs or Tags to select which tests to run.

Finding Your Agent ID

Using the Dashboard

Log in to your Cekura dashboard
Navigate to the Agents section
Select your agent
Copy the Agent ID displayed in the agent details

Using the API

You can retrieve your agent ID programmatically using the Cekura API:

curl --request GET \
  --url https://api.cekura.ai/test_framework/v1/aiagents/ \
  --header 'X-CEKURA-API-KEY: <api-key>'

The response will include your agent ID in the id field.

Using Tags vs Scenario IDs

You can run tests in two ways:

Using Scenario IDs

Run specific scenarios by their IDs. Use this when you want to test exact scenarios.

- uses: cekura-ai/cekura-github-actions@v1.2.3
  with:
    agent_id: ${{ vars.AGENT_ID }}
    scenario_ids: ${{ vars.SCENARIO_IDS }}
    api_key: ${{ secrets.CEKURA_API_KEY }}

Using Tags

Run all scenarios with specific tags. Use this when you want to test groups of scenarios (e.g., smoke-test, critical).

- uses: cekura-ai/cekura-github-actions@v1.2.3
  with:
    agent_id: ${{ vars.AGENT_ID }}
    tags: ${{ vars.TAGS }}
    api_key: ${{ secrets.CEKURA_API_KEY }}

Step-by-Step Tutorial

Create Workflow File

In your repository, create a file at .github/workflows/test-agents.yml:

name: Agent Tests

on:
  workflow_dispatch:
    inputs:
      agent_id:
        description: 'The agent identifier'
        required: false
        type: string
      scenario_ids:
        description: 'Comma-separated scenario IDs (e.g., "123,456,789")'
        required: false
        type: string
      api_url:
        description: 'Custom Cekura API endpoint'
        required: false
        type: string
        default: 'https://api.cekura.ai'

  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]

jobs:
  run-simulation-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Cekura Run Tests
        uses: cekura-ai/cekura-github-actions@v1.2.3
        with:
          agent_id: ${{ inputs.agent_id || vars.AGENT_ID }}
          scenario_ids: ${{ inputs.scenario_ids || vars.SCENARIO_IDS }}
          api_url: ${{ inputs.api_url || vars.API_URL }}
          api_key: ${{ secrets.CEKURA_API_KEY }}

Configure Variables & Secrets

Go to your repository → Settings → Secrets and variables → ActionsAdd Secret (API Key):

Click New repository secret
Name: CEKURA_API_KEY
Value: Your API key from the Cekura dashboard

Add Variables:

Click the Variables tab
Click New repository variable
Add required variables:
- AGENT_ID - Your agent ID (required)
Add one or both of the following:
- SCENARIO_IDS - Comma-separated scenario IDs (e.g., 123,456,789)
- TAGS - Comma-separated tags (e.g., smoke-test,critical)
Optionally add:
- PHONE_NUMBER - Outbound phone number for testing (e.g., +1234567890)

Start Test Run

To test your workflow, make a change to your codebase and raise a pull request. This will trigger the workflow automatically.

Monitor Workflow

Go to your repository on GitHub
Click the Actions tab
You’ll see your workflow running
Click on the workflow run to see detailed logs

Advanced Usage

Different Triggers

Run on Push Only

on:
  push:
    branches: [main]

Run on Pull Request Only

on:
  pull_request:
    types: [opened, synchronize]

Manual Trigger

on:
  workflow_dispatch:

Then trigger from the Actions tab → Run workflow button.

For more information about workflow triggers and events, check out the GitHub Actions official documentation.

Environment-Specific Testing

Test different environments (staging, production) with separate secrets:

jobs:
  staging-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Test Staging
        uses: cekura-ai/cekura-github-actions@v1.2.3
        with:
          agent_id: ${{ vars.STAGING_AGENT_ID }}
          tags: ${{ vars.STAGING_TAGS }}
          api_url: 'https://api.cekura.ai'
          api_key: ${{ secrets.STAGING_API_KEY }}

  production-tests:
    runs-on: ubuntu-latest
    needs: staging-tests
    steps:
      - name: Test Production
        uses: cekura-ai/cekura-github-actions@v1.2.3
        with:
          agent_id: ${{ vars.PROD_AGENT_ID }}
          tags: ${{ vars.PROD_TAGS }}
          api_key: ${{ secrets.PROD_API_KEY }}

Testing with Phone Numbers

When testing agents that make outbound calls, you can specify a phone number:

jobs:
  run-simulation-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run Cekura Tests
        uses: cekura-ai/cekura-github-actions@v1.2.3
        with:
          agent_id: ${{ vars.AGENT_ID }}
          scenario_ids: ${{ vars.SCENARIO_IDS }}
          phone_number: ${{ vars.PHONE_NUMBER }}
          api_key: ${{ secrets.CEKURA_API_KEY }}

Execution Modes

execution_mode picks how the scenarios reach your agent. It defaults to voice.

Mode	Runs scenarios as	Selection	Mode-specific inputs
`voice`	Phone calls	`scenario_ids` and/or `tags`	`phone_number`
`text`	Text / chat simulations	`scenario_ids` and/or `tags`	`websocket_url`, `phone_number` (the outbound number for SMS agents)
`livekit_v2`	LiveKit sessions, using the agent’s LiveKit credentials in Cekura	`scenario_ids` only	`livekit_data`
`pipecat_v2`	Pipecat Cloud sessions, using the agent’s Pipecat Cloud credentials in Cekura	`scenario_ids` only	`pipecat_data`

- name: Run text tests
  uses: cekura-ai/cekura-github-actions@v1.2.3
  with:
    agent_id: ${{ vars.AGENT_ID }}
    tags: ${{ vars.TAGS }}
    execution_mode: text
    api_key: ${{ secrets.CEKURA_API_KEY }}

- name: Run LiveKit tests
  uses: cekura-ai/cekura-github-actions@v1.2.3
  with:
    agent_id: ${{ vars.AGENT_ID }}
    scenario_ids: ${{ vars.SCENARIO_IDS }}
    execution_mode: livekit_v2
    livekit_data: >-
      {"agent_name":"production-agent","config":{"empty_timeout":300}}
    api_key: ${{ secrets.CEKURA_API_KEY }}

livekit_data accepts agent_name, url and config; pipecat_data accepts pipecat_agent_name, config and room_properties. Both override the agent’s saved connection settings for that run only. Do not put LiveKit or Pipecat Cloud credentials in the workflow.

Action Inputs

Input	Description	Required	Default
`agent_id`	Agent ID to test	Yes	-
`api_key`	Cekura API key	Yes	-
`scenario_ids`	Comma-separated scenario IDs (e.g., `123,456,789`)	No*	-
`tags`	Comma-separated tags (e.g., `smoke-test,critical`); `voice` and `text` only	No*	-
`execution_mode`	`voice`, `text`, `livekit_v2` or `pipecat_v2`	No	`voice`
`livekit_data`	JSON overrides for `livekit_v2` runs	No	-
`pipecat_data`	JSON overrides for `pipecat_v2` runs	No	-
`websocket_url`	Websocket URL for `text` runs, overriding the agent’s saved one	No	-
`phone_number`	Outbound phone number (`voice` and `text` only)	No	-
`name`	Name for the result in the dashboard	No	-
`api_url`	Cekura API URL	No	`https://api.cekura.ai`
`frequency`	Run each scenario N times	No	`1`
`concurrency_limit`	Maximum calls Cekura runs at once for this result. Defaults to your organization’s limit; a value above what your plan allows is lowered to that limit	No	-
`timeout`	Seconds to wait for the result before failing	No	`3600`

*Provide scenario_ids or tags (or both) for voice and text; livekit_v2 and pipecat_v2 require scenario_ids.

Action Outputs

Output	Description
`result_id`	ID of the Cekura result
`result_url`	Shareable link to the result, valid for 7 days

- name: Run Cekura Tests
  id: cekura
  uses: cekura-ai/cekura-github-actions@v1.2.3
  with:
    agent_id: ${{ vars.AGENT_ID }}
    tags: smoke-test
    api_key: ${{ secrets.CEKURA_API_KEY }}

- name: Link the result
  if: always()
  run: echo "Cekura result ${{ steps.cekura.outputs.result_id }}: ${{ steps.cekura.outputs.result_url }}"

When the Action Passes

The action polls the result every 30 seconds until it is completed, failed, timeout or cancelled, then writes a summary to the job and:

passes when the result is completed and every run passed;
fails otherwise — a run that failed its checks, errored, never connected or timed out counts as not passed, and so does a result that ends failed, timeout or cancelled.

The job summary shows the result’s counts and one row per run, with the scenario, the outcome and, for a run that did not pass, why (the failed metrics or the error). If the result is still running after timeout seconds, the action ends its active calls, writes the result ID and a shareable link to the job summary, and fails the step. Result statuses and gating explains each status and count.

Cancelling and job timeouts

If the workflow is cancelled, or the job hits its timeout-minutes, the action:

asks Cekura to end the result’s active calls, so no runs are left going in the background;
still writes the result ID to the job summary and sets the result_id output, so you can open the result in Cekura;
adds a shareable link (and the result_url output) if Cekura answers within GitHub’s few-second cancellation window.

Example with All Options

jobs:
  run-simulation-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run Cekura Tests
        uses: cekura-ai/cekura-github-actions@v1.2.3
        with:
          agent_id: ${{ vars.AGENT_ID }}
          scenario_ids: ${{ vars.SCENARIO_IDS }}
          tags: ${{ vars.TAGS }}
          phone_number: ${{ vars.PHONE_NUMBER }}
          api_url: 'https://api.cekura.ai'
          frequency: '3'      # Run each scenario 3 times
          timeout: '7200'     # 2 hour timeout
          api_key: ${{ secrets.CEKURA_API_KEY }}

Running Many Groups Under One Concurrency Limit

To run several agents’ scenarios from one step, use the run-batch action. A group can also have several legs that must run at the same time, each as its own result, such as the caller and the transfer target of a warm transfer, or the parties of a 3-way call. You set a single concurrency, and the action starts groups only while their calls fit under it, so you don’t need a matrix or a job per batch.

- uses: cekura-ai/cekura-github-actions/run-batch@v1.2.3
  with:
    api_key: ${{ secrets.CEKURA_API_KEY }}
    concurrency: 10
    batch: |
      - name: inbound-smoke
        agent_id: 123
        scenario_ids: 1001,1002,1003
      - name: warm-transfer
        legs:
          - name: caller
            agent_id: 456
            scenario_ids: 2001,2001
          - name: transfer-target
            agent_id: 123
            scenario_ids: 3001,3002

Single-agent group (agent_id + scenario_ids): runs as one result. It reserves scenarios × frequency calls, or the whole concurrency if that is smaller, and Cekura runs no more than that many at once.
Group with legs (two or more): the legs are matched by position, so scenario i of every leg forms set i, and every leg needs the same number of scenarios. Repeat an ID to reuse a scenario. Each set starts one result per leg together, in separate contexts, and counts as one call per leg. frequency repeats the whole set rather than the runs inside each result. A leg’s optional name labels it in the summary; keys set on the group, such as agent_id, are defaults for every leg.
Scheduling: groups start in the order listed, each one only when its calls fit in what is left of concurrency. A group’s calls are freed when its result finishes. Set dry_run: true to validate the batch and print the plan without placing calls.
Job summary: one row per result, with links, plus every run that did not pass and why. The step passes only when every run in every result passed. The passed, total_runs, passed_runs and result_ids outputs carry the same totals.
Cancelling or timing out: ends every active result’s calls and skips the groups that have not started.

Keep concurrency at or below your organization’s Cekura concurrency limit, minus any other runs (schedules, other workflows) that share it. Above that limit Cekura queues the extra results, so calls wait in the queue and the legs of a set may not start at the same time.

batch accepts JSON or YAML (YAML needs PyYAML on the runner), or use batch_file. The run-batch README lists every key and input.

Troubleshooting

Workflow Not Found

Make sure your workflow file is:

Located in .github/workflows/ directory
Pushed to your repository (workflows don’t run from local files)
Named with .yml or .yaml extension

Secrets Not Working

Common secret issues:

Secret names are case-sensitive - must match exactly
Secrets must be added in Settings → Secrets and variables → Actions
Forked repos can’t access secrets from the parent repository

Workflow Runs But Tests Fail

Check these in your workflow logs:

API key is valid and has correct permissions
Agent ID and Scenario IDs are correct
Scenario IDs format: comma-separated with no spaces (e.g., 123,456,789)
Try increasing timeout with timeout: '7200' parameter

Variables Not Found

Make sure you’re using Variables (not Secrets) for Agent ID and Scenario IDs:

Go to Settings → Secrets and variables → Actions → Variables tab
Variables are referenced with vars.VARIABLE_NAME
Secrets are referenced with secrets.SECRET_NAME

Get Started

Key Concepts

Guides

Integrations

Advanced

GitHub Actions Tutorial

Before You Get Started

Finding Your Agent ID

Using Tags vs Scenario IDs

Using Scenario IDs

Using Tags

Step-by-Step Tutorial

Advanced Usage

Different Triggers

Environment-Specific Testing

Testing with Phone Numbers

Execution Modes

Action Inputs

Action Outputs

When the Action Passes

Cancelling and job timeouts

Example with All Options

Running Many Groups Under One Concurrency Limit

Troubleshooting

​Before You Get Started

​Finding Your Agent ID

​Using Tags vs Scenario IDs

Using Scenario IDs

Using Tags

​Step-by-Step Tutorial

​Advanced Usage

​Different Triggers

​Environment-Specific Testing

​Testing with Phone Numbers

​Execution Modes

​Action Inputs

​Action Outputs

​When the Action Passes

​Cancelling and job timeouts

​Example with All Options

​Running Many Groups Under One Concurrency Limit

​Troubleshooting

Before You Get Started

Finding Your Agent ID

Using Tags vs Scenario IDs

Step-by-Step Tutorial

Advanced Usage

Different Triggers

Environment-Specific Testing

Testing with Phone Numbers

Execution Modes

Action Inputs

Action Outputs

When the Action Passes

Cancelling and job timeouts

Example with All Options

Running Many Groups Under One Concurrency Limit

Troubleshooting