Deploying Agents with GitHub Actions

Start with the Runloop Quickstart to understand the basics of agents.

Overview

Runloop’s deploy-agent GitHub Action automates agent deployment directly from your GitHub workflows. It provides a convenient way to deploy agents without writing custom API integration code, while maintaining the same functionality as the Agents API.

Key Features

Zero-config Git deployments - Automatically deploys your current repository
Release tag support - Deploys specific versions when releases are published
Multiple source types - Git repositories, tar archives (.tar, .tar.gz, .tgz), and single files
Flexible packaging - Create tar archives however you want in your workflow
Setup commands - Run custom setup commands after agent installation
Public/private agents - Control agent visibility
TTL support - Set expiration time for uploaded objects

Quick Start

Basic Git Deployment

Deploy your current repository as an agent with minimal configuration.

name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: 1.0.0

Authentication

Setting Up Your API Key

Go to the API Keys page in the Runloop Dashboard
Create a new API key
Add it as a GitHub secret:
- Go to your repository’s Settings → Secrets and variables → Actions
- Click New repository secret
- Name: RUNLOOP_API_KEY
- Value: Your Runloop API key
- Click Add secret

Relationship to Agents API

The GitHub Action provides a convenient wrapper around the Agents API.

For Git sources: Creates an agent with source.type: "git" and the repository/ref information
For Tar/File sources:
- Can upload the file/archive as a storage object
- Creates an agent with source.type: "object" referencing the uploaded object
- Applies any setup commands as agent_setup in the object source

Equivalent API Calls

The GitHub Action deployment.

- uses: runloopai/deploy-agent@main
  with:
    api-key: ${{ secrets.RUNLOOP_API_KEY }}
    source-type: git
    agent-version: 1.0.0
    setup-commands: |
      npm install

Is equivalent to this API call.

agent = await runloop.agent.create(
  name="repository-name",
  version="1.0.0",
  source={
    "type": "git",
    "git": {
      "repository": "https://github.com/user/repo",
      "ref": "main",
      "agent_setup": ["npm install"]
    }
  }
)

For tar/file sources, the action first uploads the object, then creates the agent.

# Step 1: Upload object (done automatically by action)
storage_object = await runloop.storage_object.upload_from_file(
  file_path='./agent.tar.gz',
  name='agent.tar.gz'
)

# Step 2: Create agent from object (done automatically by action)
agent = await runloop.agent.create(
  name="repository-name",
  version="1.0.0",
  source={
    "type": "object",
    "object": {
      "object_id": storage_object.id,
      "agent_setup": ["npm install"]
    }
  }
)

Input Parameters

Input	Required	Default	Description
`api-key`	✅	-	Runloop API key (store in secrets)
`source-type`	✅	-	Agent source type: `git`, `tar`, or `file`
`agent-version`	✅	-	Agent version (semver string like `2.0.65` or git SHA)
`agent-name`	❌	Repository name	Name for the agent (defaults to repository name)
`git-repository`	❌	Current repo	Git repository URL (auto-detected)
`git-ref`	❌	Current commit/tag	Git ref (branch/tag/commit SHA, auto-detected)
`path`	❌	-	Path to tar archive or single file (required for `tar`/`file` source types)
`setup-commands`	❌	-	Newline-separated setup commands to run after installation
`is-public`	❌	`false`	Whether the agent should be publicly accessible
`api-url`	❌	`https://api.runloop.ai`	Runloop API URL
`object-ttl-days`	❌	-	Time-to-live for uploaded objects in days

Outputs

Output	Description
`agent-id`	The ID of the created agent (e.g., `agt_xxxx`)
`agent-name`	The name of the created agent
`object-id`	The ID of the uploaded object (if applicable, e.g., `obj_xxxx`)

Using Deployment Outputs

Capture and use the agent ID and other outputs from the deployment.

name: Deploy and Use Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        id: deploy
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: 1.0.0
      
      - name: Use agent ID
        run: |
          echo "Agent ID: ${{ steps.deploy.outputs.agent-id }}"
          echo "Agent Name: ${{ steps.deploy.outputs.agent-name }}"
          
          # Use the agent ID in subsequent steps
          # For example, create a devbox with this agent

Deployment Examples

Git Source (Auto-detect)

Deploy the current repository as an agent. The action automatically detects the repository and commit SHA.

name: Deploy Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: 1.0.0
          setup-commands: |
            chmod +x scripts/agent.sh
            npm install

Git Source (On Release)

Deploy an agent when a new release is published, using the release tag as the version:

name: Deploy Agent on Release

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: ${{ github.event.release.tag_name }}
          agent-name: my-agent-${{ github.event.release.tag_name }}

Git Source (Custom Repository)

Deploy an agent from a specific Git repository and branch:

name: Deploy Agent from Custom Repo

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: 1.0.0
          git-repository: https://github.com/username/agent-repo
          git-ref: main

Tar Archive Deployment

Package your agent files into a tar archive and deploy it.

name: Deploy Agent from Archive

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Create agent archive
        run: |
          tar -czf agent.tar.gz -C ./agent-code .
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: tar
          agent-version: 1.0.0
          path: agent.tar.gz
          object-ttl-days: 30
          setup-commands: |
            pip install -r requirements.txt
            chmod +x agent.py

Tar Archive with Custom Build

Build your agent with custom steps, then deploy the resulting archive.

name: Build and Deploy Agent

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Build agent
        run: |
          npm install
          npm run build
          tar -czf agent.tar.gz -C ./dist .
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: tar
          agent-version: ${{ github.sha }}
          path: agent.tar.gz
          agent-name: my-built-agent

Single File Deployment

Deploy a single file as an agent.

name: Deploy Single File Agent

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: file
          agent-version: 1.0.0
          path: ./scripts/agent.sh
          setup-commands: |
            chmod +x agent.sh

Best Practices

Version Management

Use semantic versioning: Use semver strings like 1.0.0, 2.1.5 for releases
Use Git SHAs for commits: Use ${{ github.sha }} for commit-based versions
Use release tags: Use ${{ github.event.release.tag_name }} for release deployments

Workflow Organization

Separate build and deploy: Create separate jobs for building and deploying
Conditional deployment: Only deploy on specific branches or tags
Error handling: Add error handling and notifications

name: Deploy Agent

on:
  push:
    branches: [main]
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: git
          agent-version: ${{ github.ref == 'refs/heads/main' && github.sha || github.ref_name }}
      
      - name: Notify on failure
        if: failure()
        run: |
          echo "Deployment failed"
          # Add your notification logic here

Security

Never commit API keys: Always use GitHub secrets
Use environment-specific keys: Use different API keys for different environments
Limit secret access: Use environment protection rules for production secrets

Performance

Cache dependencies: Use GitHub Actions caching for faster builds
Optimize archive size: Only include necessary files in tar archives
Use object TTL: Set object-ttl-days for temporary deployments

Troubleshooting

Common Issues

Deployment fails with authentication error

Verify your RUNLOOP_API_KEY secret is correctly set
Check that the API key is valid and has the necessary permissions

Agent creation fails

Verify the source repository/branch exists and is accessible
Check that the tar archive or file path is correct
Ensure the agent version follows semver or is a valid Git SHA

Setup commands fail

Verify the commands are valid for the agent’s environment
Check that required dependencies are available
Review agent logs in the Runloop Dashboard

Getting Help

GitHub Action Repository: runloopai/deploy-agent
Runloop Documentation: Using the Agents API
Support: [email protected]

Using the Agents API - Direct API usage with Python and TypeScript
Agent Mounts - Mount agents to Devboxes
Storage Objects - Understanding object storage
API Reference: Create an Agent - Full API documentation

Overview

Tools

Components

Repo Connect

Benchmarks & Evals

Debugging

Developer Tools

Deploying Agents with GitHub Actions

Overview

Key Features

Quick Start

Basic Git Deployment

Authentication

Setting Up Your API Key

Relationship to Agents API

Equivalent API Calls

Input Parameters

Outputs

Using Deployment Outputs

Deployment Examples

Git Source (Auto-detect)

Git Source (On Release)

Git Source (Custom Repository)

Tar Archive Deployment

Tar Archive with Custom Build

Single File Deployment

Best Practices

Version Management

Workflow Organization

Security

Performance

Troubleshooting

Common Issues

Getting Help

Overview

Tools

Components

Repo Connect

Benchmarks & Evals

Debugging

Developer Tools

​Overview

​Key Features

​Quick Start

​Basic Git Deployment

​Authentication

​Setting Up Your API Key

​Relationship to Agents API

​Equivalent API Calls

​Input Parameters

​Outputs

​Using Deployment Outputs

​Deployment Examples

​Git Source (Auto-detect)

​Git Source (On Release)

​Git Source (Custom Repository)

​Tar Archive Deployment

​Tar Archive with Custom Build

​Single File Deployment

​Best Practices

​Version Management

​Workflow Organization

​Security

​Performance

​Troubleshooting

​Common Issues

​Getting Help

​Related Documentation

Overview

Key Features

Quick Start

Basic Git Deployment

Authentication

Setting Up Your API Key

Relationship to Agents API

Equivalent API Calls

Input Parameters

Outputs

Using Deployment Outputs

Deployment Examples

Git Source (Auto-detect)

Git Source (On Release)

Git Source (Custom Repository)

Tar Archive Deployment

Tar Archive with Custom Build

Single File Deployment

Best Practices

Version Management

Workflow Organization

Security

Performance

Troubleshooting

Common Issues

Getting Help

Related Documentation