# GitHub Deployment Guide

Deploy your Streamline automations directly from GitHub with automatic synchronization. Every time you push code, your automation updates automatically.

## Overview

GitHub deployment provides:

- **Automatic Sync**: Push to GitHub, and your automation updates automatically
- **Version Control**: Full Git history for your automation code
- **Collaboration**: Work with your team using standard Git workflows
- **Webhook Integration**: GitHub notifies Streamline of code changes


## Prerequisites

- GitHub account with repository access
- Freddy account with Streamline access
- Aitronos CLI installed ([installation guide](/docs/documentation/streamline/cli-installation))
- GitHub Personal Connector configured in Freddy Hub


## Step 1: Connect GitHub Account

Before deploying, connect your GitHub account to Freddy:

1. Go to [Freddy Hub](https://freddy-hub.aitronos.com)
2. Navigate to **Settings** → **Personal Connectors**
3. Click **Connect** next to GitHub
4. Authorize Freddy to access your GitHub account
5. Select the repositories you want to grant access to


## Step 2: Create GitHub Repository

### Option A: Using the CLI (Recommended)

The CLI can create a repository for you:


```bash
# Create a new repository
aitronos streamline repo create \
  --name my-automation \
  --description "My Streamline automation" \
  --private

# Output:
# ✓ Repository created: https://github.com/your-username/my-automation
# ✓ Clone URL: https://github.com/your-username/my-automation.git
```

### Option B: Manual Creation

Create a repository manually on GitHub:

1. Go to [GitHub](https://github.com/new)
2. Enter repository name (e.g., `my-automation`)
3. Choose visibility (Public or Private)
4. Click **Create repository**


## Step 3: Prepare Your Automation

Ensure your project has the required structure:


```
my-automation/
├── streamline.yaml      # Required: Automation configuration
├── main.py             # Your automation code
├── requirements.txt    # Python dependencies
├── .gitignore         # Git ignore file
└── README.md          # Documentation
```

**streamline.yaml** (required):


```yaml
name: my-automation
description: Description of what this automation does
execution_file: main.py
parameters:
  - name: param1
    type: string
    required: false
    default: "default_value"
```

**.gitignore**:


```
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.so
*.egg
*.egg-info/
dist/
build/
.venv/
venv/
.env
.DS_Store
```

## Step 4: Push Code to GitHub

Initialize Git and push your code:


```bash
# Initialize git repository
git init
git add .
git commit -m "Initial commit"

# Add remote (use URL from Step 2)
git remote add origin https://github.com/your-username/my-automation.git

# Push to GitHub
git branch -M main
git push -u origin main
```

## Step 5: Deploy to Streamline

### Option A: Using the CLI


```bash
# Deploy from GitHub repository
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automation.git \
  --branch main \
  --name "My Automation"

# Output:
# ✓ Automation uploaded from Git
# ✓ Automation ID: auto_abc123def456
# ✓ GitHub webhook configured
# ✓ Automatic sync enabled
```

### Option B: Using the API


```bash
curl -X POST "https://api.aitronos.com/v1/streamline/automations/upload/git?organization_id=org_xyz" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "git_url": "https://github.com/your-username/my-automation.git",
    "branch": "main",
    "automation_name": "My Automation"
  }'
```

## Step 6: Verify Webhook Setup

After deployment, verify the webhook was created:

1. Go to your GitHub repository
2. Navigate to **Settings** → **Webhooks**
3. You should see a webhook pointing to:

```
https://api.aitronos.com/v1/streamline/webhooks/github
```


The webhook triggers on **push** events to automatically sync your automation.

## Automatic Synchronization

### How It Works

1. You push code to GitHub
2. GitHub sends a webhook to Streamline
3. Streamline pulls the latest code
4. Your automation is updated automatically
5. Next execution uses the new code


### Sync Process


```
Developer Push → GitHub Webhook → Streamline Sync → Updated Automation
```

### Manual Sync

Trigger a manual sync if needed:


```bash
# Using CLI
aitronos streamline sync <automation-id>

# Using API
curl -X POST "https://api.aitronos.com/v1/streamline/automations/{automation_id}/sync" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

## Multi-Automation Repositories

You can host multiple automations in a single repository using subdirectories.

### Repository Structure


```
my-automations-repo/
├── automation-1/
│   ├── streamline.yaml
│   ├── main.py
│   └── requirements.txt
├── automation-2/
│   ├── streamline.yaml
│   ├── main.py
│   └── requirements.txt
└── README.md
```

### Deploy from Subdirectory


```bash
# Deploy automation-1
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automations-repo.git \
  --branch main \
  --subdirectory automation-1 \
  --name "Automation 1"

# Deploy automation-2
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automations-repo.git \
  --branch main \
  --subdirectory automation-2 \
  --name "Automation 2"
```

Both automations will sync automatically when you push to the repository.

## Branch Management

### Using Different Branches

Deploy from different branches for staging/production:


```bash
# Deploy from development branch
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automation.git \
  --branch development \
  --name "My Automation (Dev)"

# Deploy from main branch
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automation.git \
  --branch main \
  --name "My Automation (Prod)"
```

Each deployment syncs independently based on its configured branch.

### Workflow Example


```bash
# Development workflow
git checkout -b feature/new-feature
# ... make changes ...
git commit -m "Add new feature"
git push origin feature/new-feature

# Merge to development
git checkout development
git merge feature/new-feature
git push origin development
# → Dev automation syncs automatically

# After testing, merge to main
git checkout main
git merge development
git push origin main
# → Production automation syncs automatically
```

## Disconnecting GitHub

To stop automatic synchronization:


```bash
# Using CLI
aitronos streamline disconnect <automation-id>

# Using API
curl -X DELETE "https://api.aitronos.com/v1/streamline/automations/{automation_id}/github/disconnect" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

This removes the webhook from GitHub and clears the Git configuration. Your automation code is preserved.

## Monitoring Sync Status

### View Sync History


```bash
# Using CLI
aitronos streamline sync-history <automation-id>

# Using API
curl "https://api.aitronos.com/v1/streamline/automations/{automation_id}/syncs" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

### Sync Job Status

Each sync creates a job with status:

- `pending`: Sync queued
- `in_progress`: Currently syncing
- `completed`: Sync successful
- `failed`: Sync failed (check error message)


## Troubleshooting

### Webhook Not Triggering

**Check webhook configuration:**

1. Go to GitHub repository → Settings → Webhooks
2. Click on the Streamline webhook
3. Check "Recent Deliveries" for errors
4. Verify the webhook URL is correct


**Re-create webhook:**


```bash
# Disconnect and reconnect
aitronos streamline disconnect <automation-id>
aitronos streamline connect <automation-id> \
  --repo https://github.com/your-username/my-automation.git \
  --branch main
```

### Sync Failed

**Check sync job details:**


```bash
aitronos streamline sync-history <automation-id> --limit 1
```

**Common issues:**

- Invalid `streamline.yaml` format
- Missing required files
- Python syntax errors
- Repository access denied


### Authentication Issues

**Reconnect GitHub:**

1. Go to Freddy Hub → Personal Connectors
2. Disconnect GitHub
3. Reconnect and re-authorize


## Best Practices

### 1. Use Branch Protection

Protect your main branch:

- Require pull request reviews
- Require status checks to pass
- Prevent force pushes


### 2. Test Before Merging

Test changes in a development branch before merging to main:


```bash
# Create feature branch
git checkout -b feature/my-feature

# Deploy to test automation
aitronos streamline deploy \
  --repo https://github.com/your-username/my-automation.git \
  --branch feature/my-feature \
  --name "My Automation (Test)"

# Test the automation
aitronos streamline execute <test-automation-id>

# If successful, merge to main
git checkout main
git merge feature/my-feature
git push origin main
```

### 3. Use Semantic Versioning

Tag releases for easy rollback:


```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
```

### 4. Document Changes

Maintain a CHANGELOG.md:


```markdown
# Changelog

## [1.0.0] - 2025-11-27
### Added
- Initial release
- Basic automation functionality

## [1.1.0] - 2025-11-28
### Added
- New parameter for custom messages
### Fixed
- Error handling for API failures
```

### 5. Monitor Sync Status

Set up monitoring for sync failures:


```bash
# Check sync metrics
curl "https://api.aitronos.com/v1/streamline/metrics/sync" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

## Next Steps

- **[Scheduling](/docs/documentation/streamline/scheduling)** - Schedule your automation to run automatically
- **[Parameters](/docs/documentation/streamline/parameters)** - Configure automation parameters
- **[Best Practices](/docs/documentation/streamline/best-practices)** - Follow recommended patterns
- **[API Reference](/docs/api-reference/streamline/introduction)** - Complete API documentation


## Support

Need help with GitHub deployment?

- **Email**: support@aitronos.com
- **Hub**: [Freddy Hub](https://freddy-hub.aitronos.com)
- **Documentation**: [Streamline Overview](/docs/documentation/streamline/overview)