GitOps Workflow

Station is designed for GitOps - version control your agent configurations, MCP templates, and variables just like infrastructure code.

Why GitOps?

Traditional	GitOps with Station
Manual config changes	Version-controlled changes
No audit trail	Full Git history
Hard to rollback	Easy `git revert`
Single machine	Team collaboration
Config drift	Consistent state

Directory Structure

A typical Station GitOps repository:

my-station-config/
├── config.yaml                    # Station configuration
├── environments/
│   ├── production/
│   │   ├── agents/
│   │   │   ├── incident-coordinator.prompt
│   │   │   ├── logs-investigator.prompt
│   │   │   └── metrics-analyst.prompt
│   │   ├── template.json          # MCP server configs
│   │   └── variables.yml          # Secrets and config
│   │
│   ├── staging/
│   │   ├── agents/
│   │   ├── template.json
│   │   └── variables.yml
│   │
│   └── development/
│       ├── agents/
│       ├── template.json
│       └── variables.yml
│
└── reports/                       # Generated performance reports

Getting Started

1. Create a Git Repository

mkdir my-station-config
cd my-station-config
git init

2. Initialize Station

export STATION_WORKSPACE=$(pwd)
stn init --provider anthropic --ship

3. Commit Initial Configuration

git add .
git commit -m "Initial Station configuration"

4. Push to Remote

git remote add origin git@github.com:your-team/station-config.git
git push -u origin main

Team Workflow

Clone and Run

Team members can clone and run Station with your configuration:

# Clone team repository
git clone git@github.com:your-team/station-config.git
cd station-config

# Run Station with this workspace
export STATION_WORKSPACE=$(pwd)
stn stdio

Making Changes

Create a branch:
```
git checkout -b add-cost-analyzer
```
Make changes (add agents, update configs)
Test locally:
```
stn agent run cost-analyzer "Test task"
```

Commit and push:

git add .
git commit -m "Add cost analyzer agent"
git push origin add-cost-analyzer

Create Pull Request for team review

Code Review

Agent changes are reviewable like any code:

# incident-coordinator.prompt
 ---
 metadata:
   name: "incident_coordinator"
+  description: "Enhanced incident response with severity classification"
 model: gpt-4o-mini
-max_steps: 15
+max_steps: 20
 agents:
   - "logs_investigator"
   - "metrics_investigator"
+  - "security_analyst"
 ---

Configuration Files

config.yaml

Global Station configuration:

# config.yaml
ai_provider: anthropic
ai_model: claude-sonnet-4-20250514

# Workspace can be set here or via STATION_WORKSPACE env var
workspace: /path/to/environments

# Optional: CloudShip integration
cloudship:
  enabled: true
  registration_key: "{{ .CLOUDSHIP_KEY }}"
  name: "production-station"

template.json

MCP server configurations with template variables:

{
  "mcpServers": {
    "aws": {
      "command": "aws-mcp",
      "env": {
        "AWS_REGION": "{{ .AWS_REGION }}",
        "AWS_PROFILE": "{{ .AWS_PROFILE }}"
      }
    },
    "datadog": {
      "command": "datadog-mcp",
      "env": {
        "DD_API_KEY": "{{ .DATADOG_API_KEY }}",
        "DD_APP_KEY": "{{ .DATADOG_APP_KEY }}"
      }
    }
  }
}

variables.yml

Environment-specific values (keep secrets out of Git!):

# variables.yml - DO NOT COMMIT SECRETS
AWS_REGION: us-east-1
AWS_PROFILE: production
# DATADOG_API_KEY: <set via environment variable>

Best practice: Use environment variables for secrets:

export DATADOG_API_KEY="your-secret-key"
export DATADOG_APP_KEY="your-app-key"

Environment Management

Multiple Environments

Station supports multiple environments for dev/staging/prod:

environments/
├── production/    # Production agents and configs
├── staging/       # Pre-production testing
└── development/   # Local development

Switching Environments

# Run with specific environment
stn --environment production agent run cost-analyzer "Analyze costs"

# Default environment
stn --environment development agent run cost-analyzer "Test analysis"

Environment-Specific Configs

Each environment has its own:

agents/ - Agent definitions
template.json - MCP server configs
variables.yml - Environment-specific values

CI/CD Integration

GitHub Actions Example

# .github/workflows/validate.yml
name: Validate Station Config

on:
  pull_request:
    paths:
      - 'environments/**'
      - 'config.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Station
        run: |
          curl -fsSL https://raw.githubusercontent.com/cloudshipai/station/main/install.sh | bash
      
      - name: Validate Configuration
        run: |
          export STATION_WORKSPACE=$(pwd)
          stn validate
      
      - name: Lint Agent Prompts
        run: |
          stn agent lint --all

Deploy on Merge

# .github/workflows/deploy.yml
name: Deploy Station

on:
  push:
    branches: [main]
    paths:
      - 'environments/production/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy to Fly.io
        run: |
          stn deploy station-prod --target fly
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Secrets Management

Never Commit Secrets

Add to .gitignore:

# Secrets
variables.yml
*.secret
.env

# But track the template
!variables.yml.example

Use Environment Variables

# Set secrets as environment variables
export OPENAI_API_KEY="sk-..."
export AWS_SECRET_ACCESS_KEY="..."
export DATADOG_API_KEY="..."

# Station resolves {{ .VAR }} from environment
stn serve

Template for Team

Create a variables.yml.example:

# variables.yml.example - Copy to variables.yml and fill in values
AWS_REGION: us-east-1
AWS_PROFILE: ""           # Your AWS profile name
# Set these as environment variables:
# OPENAI_API_KEY
# DATADOG_API_KEY

Best Practices

One repo per team/project - Keep related agents together
Use branches for changes - Never commit directly to main
Review agent changes - Treat prompts like code
Test before merging - Run agents locally first
Keep secrets out of Git - Use environment variables
Document your agents - Use clear descriptions in metadata
Version your prompts - Git history shows evolution

Rollback

Revert a Change

# Revert last commit
git revert HEAD

# Revert specific commit
git revert abc1234

# Push the revert
git push origin main

Restore Previous Version

# View history
git log --oneline environments/production/agents/

# Checkout specific version
git checkout abc1234 -- environments/production/agents/incident-coordinator.prompt

# Commit the restoration
git add .
git commit -m "Restore incident-coordinator to previous version"

Next Steps

Bundles - Package and share agents
Deployment - Deploy to production
CI/CD Integration - Automated pipelines