Voxli Voxli

GitHub

Run your Voxli bridge in GitHub Actions when Voxli assigns tests to a GitHub agent.

First connect and verify the bridge using Local. Reuse the same script, conversation state, tool recording, and latency measurement. The bot must be reachable from the runner. A bot started in the same job can use localhost; a bot running on your laptop needs a reachable endpoint or a suitable self-hosted runner.

Prepare the workflow

Save the workflow as .github/workflows/voxli-test.yml, with your working run_test.py at the repository root. Adapt dependency installation, bot startup, settings, and the command to your project.

name: Run Voxli Test


on:
  workflow_dispatch:
    inputs:
      test_result_ids:
        description: "JSON array of assigned test result IDs"
        required: true
        type: string


permissions:
  contents: read


jobs:
  run-test:
    runs-on: ubuntu-latest
    # Leave time for interactive tester turns, but bound runner usage.
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@v4


      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"


      - name: Install dependencies
        run: python -m pip install requests python-dotenv


      - name: Run test
        env:
          VOXLI_API_TOKEN: ${{ secrets.VOXLI_API_TOKEN }}
          TEST_RESULT_IDS: ${{ inputs.test_result_ids }}
          BOT_API_KEY: ${{ secrets.BOT_API_KEY }}
          BOT_API_URL: ${{ vars.BOT_API_URL }}
          BOT_MODEL: ${{ vars.BOT_MODEL }}
        run: python run_test.py

Voxli sends a JSON array in the test_result_ids input. The workflow passes it through the environment as TEST_RESULT_IDS. Keep the input out of shell command interpolation.

The job timeout bounds the whole batch. The bridge also has a deadline and turn limit for each conversation. Its process exit code reports bridge failures; assertion scores are checked separately in Voxli.

Configure credentials and the agent

  1. In Voxli, open Settings → Integrations, click Add integration, and choose GitHub. Install the Voxli GitHub App with access to this repository.
  2. In Settings → Developer, create a Voxli API key under API keys. Store it in the GitHub repository’s Settings → Secrets and variables → Actions as the VOXLI_API_TOKEN secret.
  3. Add the bot’s credentials as secrets and its endpoint and plain options as variables. Use the names in your adapter and workflow; the sample uses BOT_API_KEY, BOT_API_URL, and BOT_MODEL. Keep real .env files out of Git. The Local settings table shows the mapping.
  4. On Voxli’s Agents page, click Connect agent and choose GitHub. Select Repository, choose voxli-test.yml under Workflow File, and set Branch to the branch containing the bridge and workflow.

Keep keys out of chat. If an assistant prepares the files, complete the credential and UI steps yourself and confirm they are ready.

For several bots, keep one GitHub agent per bot. Agents can share a workflow when the bridge selects the bot from agent metadata. Reuse that routing if it exists. Separate workflows with fixed bot settings also work. Use GitHub Environments for separate credentials; their protection rules may require approval before a job starts.

Publish the files

The workflow must exist on the repository’s default branch before GitHub accepts workflow_dispatch. You can then choose a different branch containing that workflow in the agent settings. See GitHub’s manual workflow instructions.

Use your repository’s review process to publish the workflow and bridge. Saving the files locally does not make them available for dispatch.

Verify one test

Run one test in Voxli using the configured GitHub agent. Choose a test that exercises a known tool if the bot uses tools. Check that the workflow starts, then wait for scoring in Voxli and inspect the conversation for real bot replies and the expected tool records.

A green Actions job alone does not prove that setup is complete or that assertions passed. Record the Voxli run link and score, along with any integration limits. For an assistant-driven procedure, use get_voxli_guide("github-testing-setup") through the MCP Server.

Troubleshoot

  • No workflow starts: check App access, the workflow filename, branch, and workflow_dispatch on the default branch. A rejected dispatch leaves the tests pending in Voxli without an error, so cancel the run after fixing the cause and start a new one.
  • 401 from Voxli: check VOXLI_API_TOKEN and the matching API environment. The runner needs a Voxli API key.
  • Job starts without turns: check the input mapping, bot settings, adapter implementation, and network access from the runner.
  • Timeout or bridge error: cancel unfinished work in Voxli, fix the cause, and start a fresh run. Canceling the Actions job alone does not finish the Voxli run.

Environment

Local