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, npm packages, pip packages, tar archives, 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

Authentication

Setting Up Your API Key

Go to the Settings page in the Runloop Dashboard
Create a new API key. For CI/CD workflows, consider using a restricted key scoped to only the resources the workflow needs (for example, Agents: write, Objects: write).
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. When using the API directly, use the ref field for versioning instead of the top-level version — see Agent Versioning.
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
    setup-commands: |
      npm install

Is equivalent to this API call.

agent = await runloop.agent.create(
  name="repository-name",
  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",
  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`, `npm`, `pip`, `tar`, or `file`
`agent-version`	❌	-	For npm/pip agents, pins the installed package version (e.g., `2.1.123`). Not used for git or object agents.
`agent-name`	❌	Repository name	Name for the agent (defaults to repository name)
`git-repository`	❌	Current repo	Git repository URL (auto-detected for `git` source)
`git-ref`	❌	Current ref	Git ref (branch or tag, auto-detected for `git` source)
`npm-package`	❌	-	npm package name (required for `npm` source, e.g., `@anthropic-ai/claude-code`)
`npm-registry-url`	❌	-	Custom npm registry URL (optional, defaults to public npm)
`pip-package`	❌	-	PyPI package name (required for `pip` source, e.g., `my-agent`)
`pip-index-url`	❌	-	Custom PyPI index URL (optional, defaults to public PyPI)
`path`	❌	-	Path to tar archive or single file (required for `tar`/`file` source types)
`content-type`	❌	Auto-detected	Object content type override (`unspecified`, `text`, `binary`, `gzip`, `tar`, `tgz`)
`setup-commands`	❌	-	Newline-separated setup commands to run after installation
`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
      
      - 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 tag.

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
          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 agent name:

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-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
          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
          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
          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
          path: ./scripts/agent.sh
          setup-commands: |
            chmod +x agent.sh

npm Package Deployment

Deploy an agent from an npm package. Use agent-version to pin a specific package version.

name: Deploy npm Agent

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Package version'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: npm
          agent-version: ${{ inputs.version }}  # Optional: pin package version
          agent-name: my-npm-agent
          npm-package: '@my-org/agent-package'

pip Package Deployment

Deploy an agent from a PyPI package. Use agent-version to pin a specific package version.

name: Deploy pip Agent

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Package version'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy agent
        uses: runloopai/deploy-agent@main
        with:
          api-key: ${{ secrets.RUNLOOP_API_KEY }}
          source-type: pip
          agent-version: ${{ inputs.version }}  # Optional: pin package version
          agent-name: my-pip-agent
          pip-package: my-agent-package

Best Practices

Version Management

Git agents: Use git-ref to pin to a branch, tag, or tag. The agent-version field is not used.
npm/pip agents: Use agent-version to pin the installed package version (e.g., 2.1.123). When omitted, the latest version from the registry is installed.
Tar/file agents: Each upload produces a new immutable object. The agent-version field is not used.

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
      
      - 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
Prefer restricted keys: Create keys with only the permissions your workflow needs to limit exposure if a key is compromised
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
For npm/pip sources, ensure agent-version is a valid package version string

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: support@runloop.ai

Using the Agents API - Direct API usage with Python and TypeScript
Agent Mounts - Mount agents to Devboxes
Storage Objects - Understanding object storage

Documentation Index

​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

​npm Package Deployment

​pip Package 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

npm Package Deployment

pip Package Deployment

Best Practices

Version Management

Workflow Organization

Security

Performance

Troubleshooting

Common Issues

Getting Help

Related Documentation