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/[email protected]
  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/[email protected]
  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/[email protected]
        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/[email protected]
        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/[email protected]
        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/[email protected]
        with:
          agent_id: ${{ vars.AGENT_ID }}
          scenario_ids: ${{ vars.SCENARIO_IDS }}
          phone_number: ${{ vars.PHONE_NUMBER }}
          api_key: ${{ secrets.CEKURA_API_KEY }}

Action Inputs

The action accepts these 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`)	No*	-
`phone_number`	Outbound phone number for testing	No	-
`api_url`	Cekura API URL	No	`https://api.cekura.ai`
`frequency`	Run each scenario N times	No	`1`
`timeout`	Timeout in seconds	No	`3600`

*Either scenario_ids or tags must be provided (or both)

Example with All Options

jobs:
  run-simulation-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run Cekura Tests
        uses: cekura-ai/[email protected]
        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 }}

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

Action Inputs

Example with All Options

Troubleshooting

Get Started

Key Concepts

Guides

Integrations

Advanced

​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

​Action Inputs

​Example with All Options

​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

Action Inputs

Example with All Options

Troubleshooting