WireGuard를 GitHub Actions로 자동 배포하기

개요

이 글은 WireGuard를 GitHub Actions로 자동 배포하는 전체 과정을 초보자도 이해하기 쉽게 정리한다. 목표는 코드 변경 시 자동으로 WireGuard 설정을 서버에 반영하고 서비스 재시작까지 수행하는 CI/CD 파이프라인을 만드는 것이다. 특히 WireGuard CI/CD 배포와 GitHub Actions WireGuard 연동, WireGuard 자동 배포 스크립트 작성에 중점을 둔다.

준비물

• WireGuard가 설치된 리눅스 서버(또는 VM)
• GitHub 저장소와 Actions 사용 권한
• 서버 접속용 SSH 키 및 적절한 권한
• WireGuard 설정 파일(template)과 개인·공개 키 생성 방법

설계 철학

동작 흐름

간단한 흐름은 다음과 같다. 개발자가 repo에 변경을 푸시하면 GitHub Actions가 실행되어 빌드와 검증을 거친 뒤, SSH로 서버에 접속해 설정 파일을 덮어쓰고 WireGuard를 재시작한다. 필요한 경우 백업과 롤백 단계를 추가한다.

보안 고려사항

• 비밀키나 민감 정보는 GitHub Secrets에 보관한다.
• Actions에서는 최소 권한의 SSH 키를 사용하고, 키는 특정 유저만 허용하도록 서버에서 제한한다.
• 전송 시 SCP/rsync를 사용하고, 변경 전 파일을 백업한다.

단계별 구성

1. 서버 쪽 스크립트 준비

서버에는 원격에서 설정 파일을 교체하고 서비스 재시작을 안전하게 수행하는 스크립트를 둔다. 예시 스크립트는 다음과 같다. 이 스크립트는 /etc/wireguard/wg0.conf 를 백업한 뒤 새 파일로 교체하고 wg-quick를 재시작한다.

#!/bin/bash
set -e
CONF=/etc/wireguard/wg0.conf
BACKUP_DIR=/var/backups/wireguard
mkdir -p "$BACKUP_DIR"
TIMESTAMP=$(date +%Y%m%d%H%M%S)
cp "$CONF" "$BACKUP_DIR/wg0.conf.$TIMESTAMP" || true
mv /tmp/wg0.conf "$CONF"
chmod 600 "$CONF"
systemctl restart wg-quick@wg0

2. GitHub Secrets 설정

다음 값을 GitHub 저장소의 Secrets에 추가한다.

• SSH_PRIVATE_KEY: 배포용 SSH 개인키
• SSH_USER: 서버 로그인 유저
• SSH_HOST: 서버 주소
• SSH_PORT: (선택) SSH 포트

3. GitHub Actions 워크플로 예제

다음은 Push 시 동작하는 워크플로 예시다. 핵심은 빌드 후 SCP로 서버에 설정 파일을 전송하고, 원격에서 배포 스크립트를 실행하는 단계다.

name: deploy-wireguard
on:
  push:
    paths:
      - 'wireguard/**'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up SSH key
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -H "${{ secrets.SSH_HOST }}" >> ~/.ssh/known_hosts

      - name: Upload WireGuard config
        run: |
          scp -P "${{ secrets.SSH_PORT }}" wireguard/wg0.conf "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/tmp/wg0.conf"

      - name: Remote deploy
        run: |
          ssh -p "${{ secrets.SSH_PORT }}" "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}" 'sudo /usr/local/bin/deploy-wireguard.sh'

주의: SSH_PORT를 사용하지 않을 경우 포트 관련 옵션을 제거하면 된다. 또한 Actions에서 sudo 권한이 필요한 명령을 실행하려면 해당 유저에 대한 sudo 설정이 있어야 한다.

검증 방식

배포 후 다음 항목을 점검한다.

• 서버에서 wg show로 인터페이스 상태 확인
• 클라이언트에서 연결이 정상적으로 수립되는지 확인
• 로그(/var/log/syslog 또는 journalctl)에서 오류 발생 여부 확인

문제 해결

SSH 연결 실패

호스트 키가 등록되지 않거나 키 권한이 잘못된 경우가 많다. 로컬에서 ssh -v로 테스트하고, GitHub Actions 로그의 ssh 관련 출력으로 원인 파악을 시작한다.

WireGuard가 동작하지 않을 때

wg-quick restart가 실패하면 설정 파일 문법 오류 또는 권한 문제일 가능성이 크다. 배포 전 로컬에서 wg-quick 테스트를 해보고, 서버의 백업 파일을 확인해 이전 상태로 빠르게 복원한다.

확장 아이디어

• 테스트 단계에서 컨테이너 기반의 WireGuard 검증을 추가해 자동화 수준을 높인다.
• 그룹별로 다른 설정을 배포하려면 브랜치별 워크플로 또는 매개변수화된 워크플로를 사용한다.
• 변경 내용에 대한 감사 로그를 남기고, 실패 시 자동 롤백 스크립트를 구현한다.

결론

WireGuard CI/CD 배포는 비교적 단순한 패턴을 따르지만 보안과 검증이 핵심이다. GitHub Actions WireGuard 연동을 통해 구성 파일 변경을 자동화하면 운영 효율이 크게 올라간다. 위 예시를 바탕으로 WireGuard 자동 배포 스크립트와 워크플로를 프로젝트 상황에 맞게 조정하면 안전하고 반복 가능한 배포 환경을 만들 수 있다.