How to Run an AI Agent from GitHub Actions

Overview

Runcept agents are plain HTTP endpoints. You can call them from any GitHub Actions step using curl. Add your API key as a repository secret and you're set.

Setup

1. Go to Settings → Secrets and variables → Actions

2. Add a secret: RUNCEPT_API_KEY = your key from runcept.com/dashboard

Reusable Polling Step

This shell function handles the async job pattern — start, poll, return output:

- name: Run Runcept agent
  id: agent
  env:
    RUNCEPT_API_KEY: ${{ secrets.RUNCEPT_API_KEY }}
  run: |
    # Start the job
    RESPONSE=$(curl -sS -X POST https://www.runcept.com/api/v1/run \
      -H "Authorization: Bearer $RUNCEPT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"agent": "runcept-echo", "input": {"text": "from CI"}}')
    JOB_ID=$(echo $RESPONSE | jq -r '.job_id')
    echo "job_id=$JOB_ID" >> $GITHUB_OUTPUT

    # Poll
    for i in {1..30}; do
      sleep 3
      RESULT=$(curl -sS "https://www.runcept.com/api/v1/jobs/$JOB_ID" \
        -H "Authorization: Bearer $RUNCEPT_API_KEY")
      STATUS=$(echo $RESULT | jq -r '.status')
      if [ "$STATUS" = "complete" ]; then
        echo "output=$(echo $RESULT | jq -c '.output')" >> $GITHUB_OUTPUT
        exit 0
      fi
      if [ "$STATUS" = "failed" ]; then
        echo "Agent failed" && exit 1
      fi
    done
    echo "Timeout waiting for agent" && exit 1

PR Description Workflow

name: PR Description
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  describe:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate description
        id: pr
        env:
          RUNCEPT_API_KEY: ${{ secrets.RUNCEPT_API_KEY }}
        run: |
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD | head -c 8000)
          RESPONSE=$(curl -sS -X POST https://www.runcept.com/api/v1/run \
            -H "Authorization: Bearer $RUNCEPT_API_KEY" \
            -H "Content-Type: application/json" \
            --data-raw "{\"agent\": \"pr-description\", \"input\": {\"diff\": $(echo "$DIFF" | jq -Rs .)}}")
          JOB_ID=$(echo $RESPONSE | jq -r '.job_id')
          for i in {1..20}; do
            sleep 4
            RESULT=$(curl -sS "https://www.runcept.com/api/v1/jobs/$JOB_ID" \
              -H "Authorization: Bearer $RUNCEPT_API_KEY")
            if [ "$(echo $RESULT | jq -r '.status')" = "complete" ]; then
              echo "desc=$(echo $RESULT | jq -r '.output.description')" >> $GITHUB_OUTPUT
              break
            fi
          done

      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: ${{ steps.pr.outputs.desc }}
            })

Next Steps

Related guides