GitHub Action

Deploy and manage Hatcher agents directly from your GitHub repository using the official HatcherLabs/deploy-action. Every push to main can automatically create or update your agent.

Quick Start

Add this workflow to .github/workflows/deploy.yml in your repository:

.github/workflows/deploy.yml


name: Deploy to Hatcher
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: HatcherLabs/deploy-action@v1
        with:
          api-key: ${{ secrets.HATCHER_API_KEY }}

This reads hatcher.json from your repository root and deploys the agent on every push.

Setup

Get your API key

Go to Dashboard > Settings > API Keys and generate a key. It starts with hk_.

Add the secret to GitHub

In your GitHub repository, go to Settings > Secrets and variables > Actions and create a new secret:

Name: HATCHER_API_KEY
Value: your hk_... key

Never commit your API key directly in the workflow file. Always use GitHub Secrets.

Create `hatcher.json`

Add a hatcher.json file to your repository root:

hatcher.json


{
  "name": "My Agent",
  "framework": "openclaw",
  "description": "A research agent deployed via CI/CD",
  "personality": "You are a helpful research assistant.",
  "model": "llama-4-scout",
  "tools": ["web-search", "memory", "calculator"]
}

Push and deploy

Commit and push. The action will automatically create a new agent (or update an existing one if agent-id is set) and start it.

Inputs

Input	Required	Default	Description
`api-key`	Yes	—	Your Hatcher API key (`hk_...`). Use a GitHub Secret.
`config-file`	No	`hatcher.json`	Path to the agent config file, relative to repo root.
`agent-id`	No	—	Existing agent ID to update. If omitted, a new agent is created.
`api-url`	No	`https://api.hatcher.host`	API base URL (for self-hosted or staging).

Outputs

Output	Description
`agent-id`	The ID of the created or updated agent.
`agent-url`	Direct link to the agent in the Hatcher dashboard.

Use outputs in subsequent steps:


- uses: HatcherLabs/deploy-action@v1
  id: deploy
  with:
    api-key: ${{ secrets.HATCHER_API_KEY }}
 
- run: echo "Agent deployed at ${{ steps.deploy.outputs.agent-url }}"

`hatcher.json` Config Format

Field	Required	Description
`name`	Yes	Agent display name.
`framework`	Yes	One of: `openclaw`, `hermes`.
`description`	No	Agent description shown in the dashboard.
`personality`	No	System prompt / personality for the agent.
`model`	No	LLM model identifier (e.g., `llama-4-scout`).
`tools`	No	Array of tool names to enable (e.g., `["web-search", "memory"]`).
`integrations`	No	Integration config object (Telegram tokens, Discord tokens, etc.).

Any additional fields in hatcher.json are passed through to the agent’s configJson.

Examples

Update an existing agent on push

Once you have an agent ID from the first deploy, pin it so future pushes update rather than create:


- uses: HatcherLabs/deploy-action@v1
  with:
    api-key: ${{ secrets.HATCHER_API_KEY }}
    agent-id: "abc123-your-agent-id"

Deploy only on release


name: Deploy on Release
 
on:
  release:
    types: [published]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: HatcherLabs/deploy-action@v1
        with:
          api-key: ${{ secrets.HATCHER_API_KEY }}
          config-file: deploy/hatcher.json

Deploy with environment-specific configs


- uses: HatcherLabs/deploy-action@v1
  with:
    api-key: ${{ secrets.HATCHER_API_KEY }}
    config-file: config/${{ github.ref_name }}.json

Behavior

No agent-id provided: Creates a new agent, starts it, and outputs the new ID.
agent-id provided: Updates the existing agent config, then restarts it. If the agent is already running, it stops and restarts automatically.
Agent not found (404): If the provided agent-id no longer exists, the action fails with an error.
The action writes a summary table to the GitHub Actions run summary with the agent name, framework, ID, and dashboard link.

Troubleshooting

”Invalid API key format”

API keys must start with hk_. Double-check that the secret is set correctly in GitHub and does not contain extra whitespace.

”Config file not found”

The action looks for hatcher.json (or your config-file path) relative to the repository root. Make sure the file exists and is committed.

”Invalid framework”

The framework field must be exactly one of: openclaw, hermes.

Agent created but failed to start

The agent was saved but the container could not start. Check the agent logs in your Hatcher dashboard. Common causes: tier limits reached, or the agent config has errors.