Skip to content

README.md

Latest commit

 

History

History
182 lines (129 loc) · 3.52 KB

README.md

File metadata and controls

182 lines (129 loc) · 3.52 KB
Raw

Hydra

npm version License Bundle Size

Manage GitHub Actions self-hosted runners.

Quick Start

# Install
bun add -g @r5n/hydra

# Initialize config
hydra init

# Create runners
hydra create -t $TOKEN -u https://github.com/org/repo -m 3

# Check status
hydra status -t $TOKEN -u https://github.com/org/repo

Why?

Setting up self-hosted runners manually is tedious. Hydra automates it:

  • Create multiple runners in parallel
  • Reusable profile configs
  • Monitor runner status
  • Cross-platform (macOS, Linux, Windows)

Commands

hydra init

Create a config file with profiles.

hydra init              # Interactive
hydra init --toml       # Use TOML format

hydra create

Create and register new runners.

# Basic
hydra create -t TOKEN -u REPO_URL

# Multiple with labels
hydra create -t TOKEN -u REPO_URL -m 5 -l "docker,gpu"

# Using profile
hydra create -p production -t TOKEN

Options:

  • -t, --token — GitHub PAT (required)
  • -u, --url — Repo/org URL (required)
  • -m, --numberOfMachines — Number of runners (default: 1)
  • -n, --name — Runner name prefix
  • -l, --labels — Comma-separated labels
  • -d, --directory — Runners directory
  • -o, --os — OS: osx, linux, windows
  • -p, --profile — Use config profile

hydra run

Start existing runners.

hydra run -t TOKEN -u REPO_URL -m 3
hydra run -p production -t TOKEN

hydra remove

Remove runners and unregister from GitHub.

hydra remove -t TOKEN -u REPO_URL -m 3
hydra remove -p production -t TOKEN -f  # Force without unregistering

hydra status

Check runner status.

hydra status -t TOKEN -u REPO_URL
hydra status -p production -t TOKEN --json

Configuration

Profiles

Save common configs in hydra.json or hydra.toml:

{
  "profiles": {
    "production": {
      "url": "https://github.com/org/repo",
      "name": "prod-runner",
      "numberOfMachines": 3,
      "labels": "linux,docker",
      "directory": "/opt/runners",
      "os": "linux"
    },
    "dev": {
      "url": "https://github.com/org/dev-repo",
      "name": "dev-runner",
      "numberOfMachines": 2,
      "labels": "test"
    }
  },
  "defaultProfile": "production"
}

Then use with -p:

hydra create -p production -t $TOKEN
hydra status -p dev -t $TOKEN

Environment Variables

  • GITHUB_PERSONAL_ACCESS_TOKEN — Default token
  • HYDRA_CONFIG — Config file path

Token Permissions

  • Repository runners: repo scope
  • Organization runners: admin:org scope

Never commit tokens. Use environment variables or pass via -t.

Examples

# Development setup
hydra create -p dev -t $TOKEN -m 2

# Production with specific labels
hydra create -p prod -t $TOKEN -l "deploy,production"

# Monitor all runners
hydra status -p prod -t $TOKEN --json | jq '.[] | select(.status == "offline")'

# Cleanup
hydra remove -p dev -t $TOKEN

Troubleshooting

Invalid token error:

  • Check token has repo or admin:org scope
  • Verify token isn't expired

Runner config failed:

  • Check network connectivity
  • Verify GitHub URL format
  • Ensure write permissions in runner directory

Debug mode:

DEBUG=* hydra create -t TOKEN -u URL

License

Apache 2.0 — see LICENSE