RunsOn CLI

The RunsOn CLI (roc) is a command line tool designed to help you manage and troubleshoot your RunsOn installation. It provides essential debugging and management capabilities for your self-hosted GitHub Actions runners.

Prerequisites

• RunsOn version >= v2.6.3
• AWS Session Manager plugin (for connect command)
• Appropriate AWS credentials configured

Installation

Download the latest release binary for your platform from the GitHub Releases page ↗.

macOS (ARM64)

curl "https://github.com/runs-on/cli/releases/download/v0.1.3/roc-v0.1.3-darwin-arm64.tar.gz" -Lo- | tar -xvz
./roc --help

Linux

# Replace with appropriate architecture (amd64, arm64)
curl "https://github.com/runs-on/cli/releases/download/v0.1.3/roc-v0.1.3-linux-amd64.tar.gz" -Lo- | tar -xvz
./roc --help

Commands

roc connect

Connect directly to a job instance via AWS Systems Manager (SSM) for debugging purposes.

# Connect using job ID
roc connect 12345678

# Connect using GitHub job URL
roc connect https://github.com/owner/repo/actions/runs/123/job/456

# Connect with debug output
roc connect 12345678 --debug

# Wait for connection availability
roc connect 12345678 --watch

Flags:

• --debug: Enable debug output
• --watch: Watch for connection availability

roc logs

Fetch RunsOn server and instance logs for troubleshooting.

# Get logs for a specific job
roc logs 12345678

# Get logs using GitHub job URL
roc logs https://github.com/owner/repo/actions/runs/123/job/456

# Get logs from last 30 minutes
roc logs 12345678 --since 30m

# Watch for new logs in real-time
roc logs 12345678 --watch

# Combine flags
roc logs 12345678 --since 1h --watch

Flags:

• -s, --since: Log duration (default: 2h)
• -w, --watch: Watch for new logs

roc stack doctor

Perform comprehensive health checks on your RunsOn stack and export diagnostic information.

roc stack doctor

This command performs the following checks:

• CloudFormation stack status
• AppRunner service health
• Endpoint accessibility
• Service configuration validation
• Resource availability

The results are exported as a timestamped ZIP file containing all diagnostic information, which can be shared with support for troubleshooting.

Use Cases

Debugging Job Failures

When a GitHub Actions job fails on your RunsOn infrastructure:

1. Get logs: Use roc logs JOB_ID to fetch detailed logs
2. Connect to instance: Use roc connect JOB_ID to SSH into the runner
3. Check stack health: Run roc stack doctor to ensure infrastructure is healthy

Real-time Monitoring

# Monitor logs in real-time for active jobs
roc logs JOB_ID --watch

Health Checks

# Regular stack health verification
roc stack doctor

Troubleshooting

Connection Issues

If roc connect fails:

• Ensure AWS Session Manager plugin is installed
• Verify your AWS credentials have appropriate permissions to access the RunsOn stack
• Check that you are targetting the correct stack (--stack flag or RUNS_ON_STACK environment variable) and region (set in your AWS profile or with AWS_REGION environment variable)
• Use --debug flag for detailed error information

Log Access Issues

If roc logs returns no results:

• Verify the job ID or URL is correct
• Check your AWS credentials and permissions
• Check that you are targetting the correct stack (--stack flag or RUNS_ON_STACK environment variable) and region (set in your AWS profile or with AWS_REGION environment variable)
• Try adjusting the --since timeframe

Support

For issues with the RunsOn CLI:

• Open an issue on GitHub ↗
• Contact support at [email protected]
• Include output from roc stack doctor when reporting problems

License

The RunsOn CLI is open source software licensed under the MIT License.