개발자용

셀프호스트 GitHub Actions 러너 설치 스크립트

저장소와 라벨을 입력하면 러너를 별도 사용자로 설치하고 서비스로 시작하는 스크립트를 받습니다. 토큰은 여기가 아니라 서버에서 입력합니다.

완전히 브라우저 안에서 실행됩니다. 입력한 내용은 저희 서버로 전송되지 않습니다.

저장소 또는 조직 URL예시를 내 주소로 바꾸세요. 조직 전체용 러너라면 조직까지만 남기세요.

러너 이름라벨(쉼표로 구분)Linux 사용자

필요한 작업을 위해 Docker 설치

비공개 저장소 전용입니다. 공개 저장소에서는 포크에서 온 pull request가 내 서버에서 코드를 실행할 수 있습니다.

설치 스크립트

#!/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

workflow에 넣을 줄

runs-on: [self-hosted, vps]

실행 방법

GitHub에서 Settings → Actions → Runners → New self-hosted runner를 열고 토큰을 복사하세요.
스크립트를 Debian 또는 Ubuntu 서버로 복사해 root로 실행하세요: bash install-runner.sh
스크립트가 물으면 토큰을 붙여 넣으세요. 토큰은 내 서버에 남고 이 페이지를 거치지 않습니다.
runs-on 줄을 workflow에 넣으세요.

단계별 가이드: VPS에서 셀프호스트 러너 실행

러너용 서버가 필요하신가요? Small 요금제: 4 vCPU, RAM 4 GB, root 권한, 월 8달러.

Small 요금제

작동 방식

셀프호스트 러너는 내 장비에서 동작합니다. 직접 GitHub에 연결해 작업을 가져와 그곳에서 실행합니다. 스크립트는 필요한 패키지를 설치하고, 별도의 Linux 사용자를 만들고, 최신 러너를 내려받아 등록한 뒤, 재부팅 후에도 계속 도는 systemd 서비스를 설정합니다. 스크립트는 브라우저에서 만들어지므로 실행 전에 모든 줄을 읽어 보세요. 서버에는 GitHub로 나가는 접속만 있으면 되고 전용 IP는 필요 없습니다.

자주 묻는 질문

등록 토큰은 어디서 받나요?

저장소에서 Settings → Actions → Runners → New self-hosted runner를 여세요. 토큰은 1시간 동안 유효합니다. 조직 전체용 러너라면 조직 설정에서 같은 경로를 따르세요.

셀프호스트 러너를 공개 저장소에서 써도 되나요?

GitHub는 권장하지 않습니다. 포크에서 온 pull request가 내 서버에서 코드를 실행할 수 있습니다. 셀프호스트 러너는 비공개 저장소에서 사용하세요.

서버에 전용 IP가 필요한가요?

아니요. 러너는 GitHub로 나가는 연결만 열기 때문에 전용 IP가 없는 요금제로 충분합니다. 성능은 대부분의 프로젝트에 4 vCPU와 RAM 4 GB면 충분합니다.

셀프호스트 GitHub Actions 러너 설치 스크립트

실행 방법

작동 방식

자주 묻는 질문

관련 도구