> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Run AI agents in CI/CD workflows using the Station GitHub Action

# GitHub Actions

Run Station AI agents directly in your GitHub workflows without installing Station locally. The [station-action](https://github.com/cloudshipai/station-action) supports three modes for loading agents.

## Quick Start

The easiest way to add a Station agent workflow to your repository is using the CLI:

```bash theme={null}
stn github init
```

This interactive command will:

1. Ask how you want to provide agents (CloudShip bundle ID or local environment)
2. Help you select an agent to run
3. Configure the workflow trigger (push, PR, schedule, manual)
4. Generate `.github/workflows/station-agent.yml`
5. Tell you which GitHub secrets to configure

**Example session:**

```
$ stn github init

🚀 Station GitHub Actions Setup
================================

How would you like to provide agents?
  1. CloudShip Bundle ID (recommended - keeps repo clean)
  2. Local environment (agents stored in repo)

Choice [1]: 1
Enter your CloudShip Bundle ID: 970fa728-4276-4443-9e51-35919b650d7a
Enter agent name to run: posthog-dashboard-reporter

When should this workflow run?
  1. On push to main branch
  2. On pull requests
  3. On a schedule (e.g., daily)
  4. Manual trigger only

Choice [4]: 4

✅ GitHub Actions workflow created!

📄 File: .github/workflows/station-agent.yml

🔐 Required GitHub Secrets:
   OPENAI_API_KEY      - Your OpenAI API key
   CLOUDSHIP_API_KEY   - Your CloudShip API key

Set secrets at: https://github.com/<owner>/<repo>/settings/secrets/actions
```

***

### Manual Setup

Alternatively, you can manually create the workflow. The simplest approach is using a CloudShip bundle ID:

```yaml theme={null}
name: Run AI Agent

on: [push]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: cloudshipai/station-action@main
        with:
          agent: 'posthog-dashboard-reporter'
          task: 'List all my dashboards and summarize my analytics setup.'
          bundle-id: '970fa728-4276-4443-9e51-35919b650d7a'
          cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
```

## Agent Source Modes

Station action supports three ways to load agents:

<Tabs>
  <Tab title="Bundle ID (Recommended)">
    Use a bundle published to CloudShip. This is the cleanest approach - no Station files need to be committed to your repository.

    **Step 1: Publish your bundle to CloudShip**

    From your local Station workspace:

    ```bash theme={null}
    # Share an environment as a bundle
    stn bundle share default

    # Output:
    # Bundle shared successfully!
    # Bundle ID: 970fa728-4276-4443-9e51-35919b650d7a
    ```

    **Step 2: Use the bundle ID in your workflow**

    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Perform the task'
        bundle-id: '970fa728-4276-4443-9e51-35919b650d7a'
        cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    ```

    <Note>
      Get your CloudShip API key from [app.cloudshipai.com](https://app.cloudshipai.com) under Settings > API Keys.
    </Note>
  </Tab>

  <Tab title="Bundle URL">
    Download a bundle from any URL (S3, GitHub Releases, etc.):

    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Perform the task'
        bundle-url: 'https://github.com/myorg/myrepo/releases/download/v1.0.0/bundle.tar.gz'
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    ```

    **Creating a bundle for URL distribution:**

    ```bash theme={null}
    # Build a bundle locally
    stn bundle build default -o ./my-bundle.tar.gz

    # Upload to your release/storage
    gh release upload v1.0.0 ./my-bundle.tar.gz
    ```
  </Tab>

  <Tab title="Local Environment">
    Use agents defined in your repository's `environments/` folder:

    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Perform the task'
        environment: 'default'
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    ```

    **Repository structure:**

    ```
    your-repo/
    ├── environments/
    │   └── default/
    │       ├── agents/
    │       │   └── my-agent.yaml
    │       └── mcp/
    │           └── my-tools.yaml
    └── .github/
        └── workflows/
            └── agent.yml
    ```

    This mode is useful when you want to version control your agents alongside your application code.
  </Tab>
</Tabs>

## Action Inputs

| Input               | Description                                             | Required | Default          |
| ------------------- | ------------------------------------------------------- | -------- | ---------------- |
| `agent`             | Agent name to run                                       | Yes      | -                |
| `task`              | Task description for the agent                          | Yes      | -                |
| `bundle-id`         | CloudShip bundle ID                                     | No\*     | -                |
| `bundle-url`        | URL to download bundle from                             | No\*     | -                |
| `environment`       | Local environment name                                  | No\*     | `default`        |
| `cloudship-api-key` | CloudShip API key (for bundle-id mode)                  | No       | -                |
| `provider`          | AI provider (`openai`, `anthropic`, `gemini`, `ollama`) | No       | `openai`         |
| `model`             | Model override                                          | No       | Provider default |
| `base-url`          | Custom API endpoint                                     | No       | -                |
| `timeout`           | Execution timeout in seconds                            | No       | `300`            |
| `max-steps`         | Maximum agent steps                                     | No       | `50`             |

<Note>
  \*At least one of `bundle-id`, `bundle-url`, or `environment` must be specified. If none are provided, the action looks for a local `environments/default` folder.
</Note>

## AI Provider Configuration

<Tabs>
  <Tab title="OpenAI">
    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Analyze the codebase'
        bundle-id: 'your-bundle-id'
        cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        provider: 'openai'
        model: 'gpt-4o'
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    ```
  </Tab>

  <Tab title="Anthropic">
    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Analyze the codebase'
        bundle-id: 'your-bundle-id'
        cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        provider: 'anthropic'
        model: 'claude-sonnet-4-20250514'
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    ```
  </Tab>

  <Tab title="Google Gemini">
    ```yaml theme={null}
    - uses: cloudshipai/station-action@main
      with:
        agent: 'my-agent'
        task: 'Analyze the codebase'
        bundle-id: 'your-bundle-id'
        cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        provider: 'gemini'
        model: 'gemini-2.0-flash-exp'
      env:
        GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
    ```
  </Tab>
</Tabs>

## Complete Examples

### Analytics Reporter

Run a PostHog analytics agent to summarize your dashboards:

```yaml theme={null}
name: Weekly Analytics Report

on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9 AM
  workflow_dispatch:

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: cloudshipai/station-action@main
        with:
          agent: 'posthog-dashboard-reporter'
          task: |
            Generate a weekly analytics report:
            1. List all dashboards
            2. Summarize key metrics from each
            3. Highlight any significant changes
          bundle-id: '970fa728-4276-4443-9e51-35919b650d7a'
          cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
```

### PR Code Review

Review pull requests automatically:

```yaml theme={null}
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: cloudshipai/station-action@main
        with:
          agent: 'code-reviewer'
          task: |
            Review the changes in this PR. Focus on:
            - Security vulnerabilities
            - Performance issues
            - Code quality and best practices
            - Potential bugs
          bundle-id: 'your-code-review-bundle-id'
          cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

### Security Scan on Push

Scan for security issues on every push:

```yaml theme={null}
name: Security Scan

on:
  push:
    branches: [main]

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

      - uses: cloudshipai/station-action@main
        with:
          agent: 'security-scanner'
          task: 'Scan the codebase for security vulnerabilities, exposed secrets, and dependency issues'
          bundle-id: 'your-security-bundle-id'
          cloudship-api-key: ${{ secrets.CLOUDSHIP_API_KEY }}
          timeout: '600'
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

## Publishing Bundles to CloudShip

To use bundle-id mode, first publish your agents to CloudShip:

```bash theme={null}
# 1. Create agents in your local Station workspace
stn init
stn agent add --name "my-agent" --description "Does something useful"

# 2. Add MCP tools
stn mcp add --name "my-tools" --url "https://api.example.com/mcp"

# 3. Test locally
stn run "my-agent" --task "Test the agent"

# 4. Share to CloudShip
stn bundle share default

# Output shows your bundle ID:
# Bundle ID: abc123-def456-...
```

<Tip>
  Store your bundle ID somewhere safe. You'll need it for the `bundle-id` input in your workflows.
</Tip>

## Build-Time Actions

Station also provides reusable actions for building bundles and Docker images.

### Build Bundle

Create distributable bundles from environments:

```yaml theme={null}
- uses: cloudshipai/station/.github/actions/build-bundle@main
  id: bundle
  with:
    environment: 'production'
    version: '1.0.0'

- run: echo "Bundle created at ${{ steps.bundle.outputs.bundle-path }}"
```

### Build Docker Image

Build and push Docker images:

```yaml theme={null}
- uses: cloudshipai/station/.github/actions/build-image@main
  with:
    source-type: 'environment'
    environment: 'production'
    image-name: 'my-org/station-production'
    image-tag: 'latest'
    push: 'true'
    registry-username: ${{ github.actor }}
    registry-password: ${{ secrets.GITHUB_TOKEN }}
```

### Setup Station CLI

Install Station CLI without running an agent:

```yaml theme={null}
- uses: cloudshipai/station/.github/actions/setup-station@main
  with:
    version: 'latest'
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

- run: stn --version
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use bundle-id mode for production">
    Bundle-id mode keeps your repository clean - no Station configuration files to maintain. Agents are versioned separately in CloudShip.
  </Accordion>

  <Accordion title="Store API keys as GitHub secrets">
    Never hardcode API keys. Use GitHub secrets:

    ```yaml theme={null}
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      CLOUDSHIP_API_KEY: ${{ secrets.CLOUDSHIP_API_KEY }}
    ```
  </Accordion>

  <Accordion title="Set appropriate timeouts">
    Complex tasks may need longer timeouts:

    ```yaml theme={null}
    with:
      timeout: '600'  # 10 minutes
    ```
  </Accordion>

  <Accordion title="Use workflow_dispatch for testing">
    Add manual trigger for easy testing:

    ```yaml theme={null}
    on:
      workflow_dispatch:
      push:
        branches: [main]
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent not found">
    Ensure the agent name matches exactly (case-sensitive). List available agents:

    ```bash theme={null}
    stn agent list
    ```
  </Accordion>

  <Accordion title="Bundle download failed">
    For bundle-id mode, verify:

    * `cloudship-api-key` is set correctly
    * Bundle ID is valid and not deleted
    * Your CloudShip account has access to the bundle
  </Accordion>

  <Accordion title="MCP tools not available">
    Ensure required environment variables are passed:

    ```yaml theme={null}
    env:
      POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

* [Bundles](/station/bundles) - Learn more about packaging agents
* [GitOps Workflow](/station/gitops) - Version control your agents
* [Docker Deployment](/station/docker) - Container deployment options