Run Poolside in GitHub Actions - Poolside

Fetch the complete documentation index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

GitHub Actions runs Poolside on an event, a schedule, or on demand from the Actions tab, so repository work does not depend on someone opening a terminal to run it. Use it to review pull requests, scan for vulnerabilities, draft release notes, or run any task you would give Poolside interactively.

Watch the setup video

Poolside with GitHub Actions

Prerequisites

You can create GitHub Actions workflows and repository secrets.
You have a Poolside API key. Workflows authenticate with an API key instead of pool login, so any access method works: Poolside Platform, your organization’s Poolside deployment, OpenRouter, or another OpenAI-compatible provider that serves Poolside models. See Get and set your API key.

Steps

Add your API key as a repository secret:
1. In your GitHub repository, go to Settings.
2. Select Secrets and variables, then select Actions.
3. Click New repository secret.
4. Name the secret POOLSIDE_API_KEY and paste your Poolside API key as the value.
5. Click Add secret.

pool checks the POOLSIDE_API_KEY environment variable before it reads stored credentials, so workflows do not need a login step. For more options, see use secrets in GitHub Actions.

Add a workflow file: A workflow is a YAML file in your repository’s .github/workflows/ directory. Copy one of the examples under Workflow examples into a new file, such as .github/workflows/poolside.yml. Update the model and endpoint values as described in Set workflow variables, then commit the file to your default branch.
Run the workflow: How a workflow starts depends on its trigger. A workflow with on: pull_request runs the next time someone opens a pull request. A workflow with on: workflow_dispatch waits for you to start it by hand from the Actions tab, using the Run workflow button. Open the Actions tab to watch the run and see its output. Each example under Workflow examples states where its result appears.

Set workflow variables

The pool exec examples use Poolside Platform by default. Before you copy a workflow, replace <poolside-model-id> with a model available to your API key. To find model IDs for your access method, see List available models.

Poolside deployment: Replace the Poolside Platform environment variables with:
```
POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
POOLSIDE_API_URL: <api-url>
```
Use the API URL from your administrator. Do not use your deployment’s /openai/v1 endpoint for POOLSIDE_API_URL. Remove the POOLSIDE_STANDALONE_BASE_URL and POOLSIDE_STANDALONE_MODEL lines when you switch to a deployment. Do not set POOLSIDE_API_URL alongside the standalone variables.

OpenRouter or another OpenAI-compatible provider: Replace the Poolside Platform environment variables with:

POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
POOLSIDE_STANDALONE_BASE_URL: <provider-base-url>
POOLSIDE_STANDALONE_MODEL: <model-id>

Workflow examples

Review pull requests

name: Poolside code review

on:
  pull_request:

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

- name: Install Poolside Agent CLI
        env:
          POOL_INSTALL_ACCEPT_EULA: "1"
        run: |
          curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- name: Review the changes
        env:
          POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
          POOLSIDE_STANDALONE_BASE_URL: https://inference.poolside.ai/v1
          POOLSIDE_STANDALONE_MODEL: <poolside-model-id>
          BASE_REF: ${{ github.base_ref }}
        run: >-
          pool exec
          --prompt "Review the changes on this branch against origin/$BASE_REF. Flag risks, breaking changes, and missing tests. Write the review as a Markdown comment to review.md."
          --output json
          --unsafe-auto-allow

- name: Post the review
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: gh pr comment "$PR_NUMBER" --body-file review.md

Scan the repository on a schedule

name: Poolside nightly scan

on:
  schedule:
    - cron: "0 3 * * *"

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

- name: Scan the repository
        env:
          POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
          POOLSIDE_STANDALONE_BASE_URL: https://inference.poolside.ai/v1
          POOLSIDE_STANDALONE_MODEL: <poolside-model-id>
        run: >-
          pool exec
          --prompt "Scan the repository for security vulnerabilities. Write a JSON report with severity, location, and remediation for each finding to scan-report.json."
          --output json
          --unsafe-auto-allow

- name: Upload the report
        uses: actions/upload-artifact@v4
        with:
          name: poolside-scan
          path: scan-report.json
          if-no-files-found: error

Generate release notes when you publish a release

name: Poolside release notes

on:
  release:
    types: [published]

jobs:
  notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      TAG: ${{ github.event.release.tag_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

- name: Generate release notes
        env:
          POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
          POOLSIDE_STANDALONE_BASE_URL: https://inference.poolside.ai/v1
          POOLSIDE_STANDALONE_MODEL: <poolside-model-id>
        run: >-
          pool exec
          --prompt "Find the tag immediately before $TAG, read the commits between that tag and $TAG with git log, and write concise release notes grouped by type of change to notes.md."
          --output json
          --unsafe-auto-allow

- name: Update the release
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release edit "$TAG" --notes-file notes.md

Classify new issues

name: Poolside issue triage

on:
  issues:
    types: [opened]

jobs:
  triage:
    if: >-
      github.event.issue.author_association == 'OWNER' ||
      github.event.issue.author_association == 'MEMBER' ||
      github.event.issue.author_association == 'COLLABORATOR'
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Classify the issue
        env:
          POOLSIDE_API_KEY: ${{ secrets.POOLSIDE_API_KEY }}
          ISSUE_BODY: ${{ github.event.issue.body }}
        run: |
          jq -n --arg body "$ISSUE_BODY" '{
            model: "<poolside-model-id>",
            messages: [{\
              role: "user",\
              content: ("Classify this issue as bug, feature, or question. Reply with one word.\n\n" + $body)\
            }]
          }' > request.json

curl --fail-with-body --request POST \
            --url https://inference.poolside.ai/v1/chat/completions \
            --header "Content-Type: application/json" \
            --header "Authorization: Bearer $POOLSIDE_API_KEY" \
            --data @request.json

Customize a workflow

Use the examples as starting points. Change the trigger, prompt, output step, and model settings to fit the repository task you want to automate.

Change the trigger

GitHub Actions supports a wide range of workflow events. The same patterns extend to other triggers:

Trigger	When it runs	Example task
`push`	Commits land on a branch	Keep generated files or documentation in sync with `main`
`issues`	Someone opens an issue	Triage, label, and request missing reproduction details
`issue_comment`	Someone comments on an issue or pull request	On-demand agent runs from a slash command
`workflow_run`	Another workflow completes	Analyze a failing CI run and suggest a fix
`workflow_dispatch`	You trigger the workflow manually	Ad-hoc tasks with custom inputs

Change the prompt

The prompt is the part of the workflow that is yours. Prompts that work well in CI name the input, the output, and where the output goes:

Review the changes on this branch against origin/main. Write the review to review.md.
Find TODO comments added in the last 30 days and write them to todos.md as a checklist.
Update the API reference in docs/api.md to match the exported functions in src/.
Summarize the test failures in test-output.txt and suggest a fix for each one.

Change the model and settings

To use a different model with Poolside Platform or an OpenAI-compatible provider, change POOLSIDE_STANDALONE_MODEL in the workflow. Each example workflow uses two pool exec flags that suit automation:

--output json prints newline-delimited JSON that later steps can parse.
--unsafe-auto-allow lets the agent run without approval prompts. Explicit deny rules still apply.

Secure agent workflows

--unsafe-auto-allow approves the agent’s tool actions without prompting. Before you use it:

Run agent workflows only from trusted events, branches, and actors. Event payloads such as pull request diffs, issue bodies, and comments become agent input.
Pass event values such as branch names, issue titles, and comment bodies through the env block instead of placing them directly in the run command.
Use permissions and sandboxes to limit what the agent can access and run.