runner/docs/automate.md

Automate Configuring Self-Hosted Runners

Export PAT

Before running any of these sample scripts, create a GitHub PAT and export it before running the script

export RUNNER_CFG_PAT=yourPAT

Create running as a service

Scenario: Run on a machine or VM (not container) which automates:

• Resolving latest released runner
• Download and extract latest
• Acquire a registration token
• Configure the runner
• Run as a systemd (linux) or Launchd (osx) service

👉 Sample script here 👈

Run as a one-liner. NOTE: replace with yourorg/yourrepo (repo level) or just yourorg (org level)

curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | bash -s yourorg/yourrepo

You can call the script with additional arguments:

#   Usage:
#       export RUNNER_CFG_PAT=<yourPAT>
#       ./create-latest-svc -s scope -g [ghe_domain] -n [name] -u [user] -l [labels]
#       -s          required  scope: repo (:owner/:repo) or org (:organization)
#       -g          optional  ghe_hostname: the fully qualified domain name of your GitHub Enterprise Server deployment
#       -n          optional  name of the runner, defaults to hostname
#       -u          optional  user svc will run as, defaults to current
#       -l          optional  list of labels (split by comma) applied on the runner"

Use -- to pass any number of optional named parameters:

curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | bash -s -- -s myorg/myrepo -n myname -l label1,label2

Why can't I use a container?

The runner is installed as a service using systemd and systemctl. Docker does not support systemd for service configuration on a container.

Uninstall running as service

Scenario: Run on a machine or VM (not container) which automates:

• Stops and uninstalls the systemd (linux) or Launchd (osx) service
• Acquires a removal token
• Removes the runner

👉 Sample script here 👈

Repo level one liner. NOTE: replace with yourorg/yourrepo (repo level) or just yourorg (org level)

curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/remove-svc.sh | bash -s yourorg/yourrepo

Delete an offline runner

Scenario: Deletes a registered runner that is offline:

• Ensures the runner is offline
• Resolves id from name
• Deletes the runner

👉 Sample script here 👈

Repo level one-liner. NOTE: replace with yourorg/yourrepo (repo level) or just yourorg (org level) and replace runnername

curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/delete.sh | bash -s yourorg/yourrepo runnername

Troubleshooting

Common Issues

Permission Denied

# Ensure scripts have execute permissions
chmod +x ./config.sh ./run.sh

PAT Token Issues

# Verify your PAT has the correct scopes:
# - repo (for repository-level runners)
# - admin:org (for organization-level runners)
export RUNNER_CFG_PAT=your_token_here
echo $RUNNER_CFG_PAT  # Verify it's set

Network Connectivity

# Test GitHub connectivity
curl -H "Authorization: token $RUNNER_CFG_PAT" https://api.github.com/user

# For GitHub Enterprise Server
curl -H "Authorization: token $RUNNER_CFG_PAT" https://your-github-enterprise/api/v3/user

Service Installation Fails

# Check if running as appropriate user
whoami

# For Linux - ensure systemd is available
systemctl --version

# For macOS - ensure launchd is available
launchctl version

Runner Registration Fails

# Check if runner already exists
curl -H "Authorization: token $RUNNER_CFG_PAT" \
  "https://api.github.com/repos/OWNER/REPO/actions/runners"

# Remove existing runner if needed
./config.sh remove --token $RUNNER_CFG_PAT

Getting Help

• Configuration Issues: Check the Prerequisites for your platform
• Network Problems: Review network troubleshooting guide
• General Support: Visit GitHub Community Discussions

Advanced Examples

Organization-level Runner with Custom Labels

export RUNNER_CFG_PAT=your_org_pat
curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
  bash -s -- -s myorg -n prod-runner-1 -l production,linux,docker

Repository-level Runner for GitHub Enterprise

export RUNNER_CFG_PAT=your_ghe_pat
curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
  bash -s -- -s myorg/myrepo -g github.company.com -n build-server -u builder