## Fetch the complete documentation index

Fetch the complete documentation index at: [/llms.txt](https://docs.poolside.ai/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](https://docs.poolside.ai/api/overview#get-and-set-your-api-key).

## Steps

1. **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](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).

2. **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](https://docs.poolside.ai/tools/github-actions#workflow-examples) into a new file, such as `.github/workflows/poolside.yml`. Update the model and endpoint values as described in [Set workflow variables](https://docs.poolside.ai/tools/github-actions#set-workflow-variables), then commit the file to your default branch.

3. **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](https://docs.poolside.ai/tools/github-actions#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](https://docs.poolside.ai/api/openai-api-examples#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

```yaml
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

```yaml
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

```yaml
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

```yaml
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](https://docs.poolside.ai/permissions) and [sandboxes](https://docs.poolside.ai/sandboxes) to limit what the agent can access and run.