Developer

GitHub Actions self-hosted runner install script

Enter your repository and labels to get a script that installs the runner under its own user and starts it as a service. You enter the token on your server, not here.

Runs entirely in your browser — nothing you enter is sent to our servers.

Repository or organization URLReplace the example with your own address. For an organization-wide runner, keep only the organization.

Runner nameLabels, comma-separatedLinux user

Install Docker for jobs that need it

Private repositories only. In a public one, a pull request from a fork can run code on your server.

Install script

#!/usr/bin/env bash
# Installs a self-hosted GitHub Actions runner as a systemd service (Debian, Ubuntu).
# Run as root: bash install-runner.sh
set -euo pipefail

REPO_URL="https://github.com/your-org/your-repo"
RUNNER_NAME="vps-runner-1"
RUNNER_LABELS="vps"
RUNNER_USER="runner"
RUNNER_DIR="/home/$RUNNER_USER/actions-runner"

[ "$(id -u)" -eq 0 ] || { echo "Run this script as root." >&2; exit 1; }
command -v apt-get >/dev/null || { echo "This script supports Debian and Ubuntu only." >&2; exit 1; }
case "$(uname -m)" in
  x86_64) ARCH=x64 ;;
  aarch64) ARCH=arm64 ;;
  *) echo "Unsupported CPU: $(uname -m)" >&2; exit 1 ;;
esac
[ ! -f "$RUNNER_DIR/.runner" ] || { echo "A runner is already configured in $RUNNER_DIR." >&2; exit 1; }

read -rsp "Registration token from GitHub: " RUNNER_TOKEN; echo
[ -n "$RUNNER_TOKEN" ] || { echo "The token is empty." >&2; exit 1; }

apt-get update -y
apt-get install -y curl tar ca-certificates
id "$RUNNER_USER" >/dev/null 2>&1 || useradd -m -s /bin/bash "$RUNNER_USER"

# Latest runner release
VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/actions/runner/releases/latest | sed 's|.*/tag/v||')"
FILE="actions-runner-linux-$ARCH-$VERSION.tar.gz"
as_runner() { runuser -u "$RUNNER_USER" -- env HOME="/home/$RUNNER_USER" "$@"; }
as_runner mkdir -p "$RUNNER_DIR"
cd "$RUNNER_DIR"
as_runner curl -fsSL -o "$FILE" "https://github.com/actions/runner/releases/download/v$VERSION/$FILE"
as_runner tar xzf "$FILE"
rm -f "$FILE"
./bin/installdependencies.sh

# Register with GitHub and start as a service
as_runner ./config.sh --unattended --url "$REPO_URL" --token "$RUNNER_TOKEN" --name "$RUNNER_NAME" --labels "$RUNNER_LABELS" --replace
./svc.sh install "$RUNNER_USER"
./svc.sh start
./svc.sh status --no-pager

Line for your workflow

runs-on: [self-hosted, vps]

How to run it

On GitHub open Settings → Actions → Runners → New self-hosted runner and copy the token.
Copy the script to your Debian or Ubuntu server and run it as root: bash install-runner.sh.
Paste the token when the script asks. It stays on your server and never passes through this page.
Put the runs-on line into your workflow.

Step-by-step guide: self-hosted runner on a VPS

Need a server for the runner? Small plan: 4 vCPU, 4 GB RAM, root access, $8/month.

Small plan

How it works

A self-hosted runner works on your own machine: it connects to GitHub, picks up jobs and runs them there. The script installs the required packages, creates a separate Linux user, downloads the latest runner release, registers it and sets up a systemd service that survives reboots. The script is built in your browser, so read every line before you run it. The server only needs outbound access to GitHub, no dedicated IP required.

FAQ

Where do I get the registration token?

In your repository open Settings → Actions → Runners → New self-hosted runner. The token is valid for one hour. For an organization-wide runner, use the same path in the organization settings.

Can I use a self-hosted runner with a public repository?

GitHub advises against it: a pull request from a fork can run code on your server. Use self-hosted runners with private repositories.

Does the server need a dedicated IP?

No. The runner only makes outbound connections to GitHub, so a plan without a dedicated IP works. As for power, 4 vCPU and 4 GB of RAM are enough for most projects.

Related tools

b64

Base64 encoder/decoder

Text and files to Base64 and back, URL-safe option.

UUID generator

UUID v4 and time-ordered v7, in bulk.

*/5

Cron expression helper

Explain a crontab line and show the next run times.

Аa

Transliteration

Cyrillic to Latin: passport standards and URL slugs.

All tools →