파이썬 프로그램을 서버에 처음 배포할 때는 직접 SSH로 접속하여 코드를 내려받고 프로그램을 다시 실행하는 경우가 많습니다.
프로젝트가 작을 때는 큰 문제가 없습니다.
하지만 코드를 자주 수정하면 매번 다음 과정을 반복해야 합니다.
코드 수정↓GitHub Push↓서버 SSH 접속↓git pull↓라이브러리 설치↓서비스 재시작
작은 수정 하나를 할 때마다 같은 작업을 반복하게 됩니다.
이러한 과정을 자동화하는 개념이 CI/CD이며 GitHub에서는 GitHub Actions를 이용해 자동화 워크플로를 만들 수 있습니다.
CI/CD란 무엇인가?
CI는 Continuous Integration의 약자로 지속적 통합을 의미합니다.
여러 번 변경되는 코드를 하나의 저장소에서 관리하면서 테스트와 검증 과정을 자동화하는 개념입니다.
CD는 문맥에 따라 Continuous Delivery 또는 Continuous Deployment를 의미합니다.
쉽게 설명하면 코드 변경 이후 배포 가능한 상태로 만들거나 실제 서버 배포까지 자동화하는 방식입니다.
개인 파이썬 프로젝트에서는 다음 정도로 이해해도 충분합니다.
GitHub에 코드 Push↓자동 작업 실행↓테스트↓서버 배포↓서비스 재시작
GitHub Actions란?
GitHub Actions는 GitHub 저장소에서 특정 이벤트가 발생했을 때 미리 정의한 작업을 실행할 수 있는 자동화 기능입니다.
예를 들어 main 브랜치에 코드가 Push될 때 자동으로 테스트를 수행하도록 만들 수 있습니다.
기본적인 YAML 파일은 다음과 같은 형태입니다.
name: Python CIon: push: branches: - mainjobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install dependencies run: | pip install -r requirements.txt
프로젝트에 맞게 테스트나 배포 단계를 추가할 수 있습니다.
workflow 파일은 어디에 만들까?
GitHub Actions 설정은 일반적으로 프로젝트의 다음 경로에 저장합니다.
.github/workflows/
예를 들어 다음과 같습니다.
.github/workflows/deploy.yml
이 파일을 GitHub에 Push하면 저장소의 Actions 메뉴에서 실행 결과를 확인할 수 있습니다.
먼저 자동 테스트부터 구성하는 것이 좋은 이유
곧바로 운영 서버 자동 배포부터 만드는 것보다 기본 테스트를 먼저 실행하도록 구성하는 편이 안전합니다.
잘못된 코드가 Push되자마자 운영 서버에 배포되면 서비스 전체가 중단될 수도 있기 때문입니다.
예를 들어 간단한 프로젝트라면 다음 순서를 사용할 수 있습니다.
Push↓Python 환경 생성↓requirements 설치↓테스트 실행↓테스트 성공↓배포
자동배포의 핵심은 무조건 빠르게 서버에 반영하는 것이 아니라 문제가 있는 코드를 최대한 배포 전에 걸러내는 것입니다.
requirements.txt 관리하기
서버와 GitHub Actions 환경에서 같은 라이브러리를 설치하려면 프로젝트 의존성을 관리해야 합니다.
예를 들어 다음과 같이 작성할 수 있습니다.
fastapiuvicornrequestspython-dotenv
현재 환경의 패키지를 파일로 저장할 수도 있습니다.
pip freeze > requirements.txt
다만 개발환경에 불필요한 패키지가 많이 설치되어 있다면 그대로 모두 저장하기보다 프로젝트에서 실제 필요한 라이브러리를 정리하는 편이 좋습니다.
서버 배포에 필요한 정보 관리
GitHub Actions가 VPS에 접속하려면 서버 주소와 인증정보 등이 필요할 수 있습니다.
이러한 정보를 YAML 파일에 직접 작성해서는 안 됩니다.
GitHub 저장소에는 Secrets 기능이 있으며 민감한 값을 별도로 관리할 수 있습니다.
예를 들어 다음과 같은 값을 사용할 수 있습니다.
SERVER_HOSTSERVER_USERSSH_PRIVATE_KEY
중요한 것은 SSH 개인키를 코드나 공개 저장소에 직접 올리지 않는 것입니다.
.env 파일을 GitHub에 업로드하지 않는 것과 같은 원리입니다.
SSH 키 기반 인증을 사용하는 이유
자동화 작업에서는 매번 비밀번호를 직접 입력할 수 없습니다.
따라서 공개키와 개인키를 이용한 SSH 인증 방식을 사용하는 경우가 많습니다.
서버에는 공개키를 등록하고 GitHub Actions에서는 필요한 인증정보를 Secret으로 관리하는 방식입니다.
이때 자동배포 전용 사용자를 별도로 만들고 필요한 권한만 부여하는 방식도 고려할 수 있습니다.
자동화 계정에 불필요하게 강력한 권한을 주지 않는 것이 보안상 좋습니다.
서버에서 실제 배포하는 과정
서버에서 프로젝트가 다음 위치에 있다고 가정해보겠습니다.
/home/user/myapp
배포 과정은 개념적으로 다음과 같습니다.
cd /home/user/myappgit pull origin main
가상환경을 사용한다면 필요한 패키지를 설치할 수 있습니다.
source venv/bin/activatepip install -r requirements.txt
그리고 systemd로 프로그램을 운영 중이라면 서비스 재시작 과정이 필요할 수 있습니다.
sudo systemctl restart myapp
실제 환경에서는 사용자 권한과 systemd 설정에 맞춰 구성해야 합니다.
자동배포 구조를 단순하게 이해하기
전체 흐름은 다음과 같습니다.
개발 PC↓git push↓GitHub↓GitHub Actions↓테스트↓SSH↓Ubuntu Server↓git pull↓dependency 설치↓systemd restart↓새 코드 적용
이 구조를 한번 만들어 두면 개발자는 코드 변경 후 Push하는 것만으로 배포 작업의 상당 부분을 자동화할 수 있습니다.
배포에 실패하면 어떻게 할까?
자동배포에서 반드시 고려해야 하는 부분입니다.
git pull에 실패할 수도 있고 패키지 설치 중 오류가 발생할 수도 있습니다.
새 코드 자체에 문제가 있을 수도 있습니다.
따라서 단순히 마지막에 restart 명령을 실행하는 것보다 각 단계가 성공했을 때만 다음 단계가 실행되도록 구성해야 합니다.
GitHub Actions에서는 각 Step의 성공 여부를 확인할 수 있으므로 어느 단계에서 문제가 생겼는지 파악하기 편합니다.
로그와 알림 연동
배포 성공이나 실패 결과를 별도로 알려주도록 만들 수도 있습니다.
예를 들어 텔레그램 봇, Slack 또는 이메일과 연동하여 다음과 같은 알림 체계를 만들 수 있습니다.
배포 시작↓테스트 완료↓서버 배포↓성공 또는 실패 알림
개인 서버 여러 개를 운영한다면 매번 Actions 페이지를 확인하는 것보다 알림 시스템을 만드는 것이 편리합니다.
자동배포가 반드시 필요한 것은 아니다
프로젝트를 하루에 한 번도 수정하지 않는다면 CI/CD 환경 구축에 시간을 많이 사용할 필요는 없습니다.
반대로 여러 서버를 운영하거나 수정 사항이 자주 발생한다면 자동화 효과가 커집니다.
즉 CI/CD 자체가 목적이 되어서는 안 됩니다.
사람이 반복하는 배포 작업에서 실수를 줄이고 시간을 절약하는 것이 목적입니다.
운영 서버에서는 더욱 신중해야 한다
자동배포는 편리하지만 잘못 구성하면 문제가 있는 코드가 빠르게 운영환경에 적용된다는 단점도 있습니다.
따라서 중요한 서비스에서는 다음과 같은 구조를 고려할 수 있습니다.
개발↓테스트↓Staging 서버↓검증↓Production 배포
개인 프로젝트에서는 처음부터 복잡하게 구성할 필요는 없지만 테스트 단계를 생략하지 않는 습관은 중요합니다.
GitHub Actions와 .env의 관계
GitHub 저장소에 소스코드를 올리더라도 API 키나 DB 비밀번호를 코드와 함께 저장하면 안 됩니다.
GitHub Actions에 필요한 값은 Secrets를 이용하고 서버에서 사용하는 환경변수는 서버 환경에 별도로 보관하는 방식이 좋습니다.
즉 코드는 공유하되 비밀정보는 환경별로 분리하는 것이 핵심입니다.
자주 묻는 질문
GitHub Actions는 초보자도 사용할 수 있나요?
YAML 문법과 Git의 기본 개념을 이해해야 하지만 간단한 테스트 자동화부터 시작하면 충분히 배울 수 있습니다.
GitHub에 Push할 때마다 자동으로 배포할 수 있나요?
가능합니다. 특정 브랜치에 Push되는 이벤트를 기준으로 Workflow를 실행하도록 설정할 수 있습니다.
자동배포가 수동배포보다 무조건 좋은가요?
그렇지는 않습니다. 프로젝트가 작고 변경이 드물다면 수동배포가 단순할 수 있습니다. 업데이트가 잦아질수록 자동화의 효과가 커집니다.
서버 비밀번호를 YAML에 넣어도 되나요?
민감한 인증정보를 저장소 파일에 직접 기록하는 것은 피해야 합니다. GitHub Secrets 등의 기능을 이용해 분리해서 관리하는 것이 좋습니다.
마무리
GitHub Actions를 이용한 CI/CD는 파이썬 자동화 서버 구축 과정의 마지막 단계와 잘 어울립니다.
처음에는 직접 서버에 접속해 프로그램을 설치하고 실행하는 과정을 경험하는 것이 좋습니다. 그래야 어떤 작업을 자동화하는지 정확하게 이해할 수 있기 때문입니다.
이후 반복되는 배포 과정을 GitHub Actions로 옮기면 개발 과정이 훨씬 편리해집니다.
결국 자동화의 핵심은 복잡한 기술을 많이 사용하는 것이 아니라 사람이 반복해서 수행하는 작업을 찾아 안전하고 예측 가능한 프로그램으로 바꾸는 것입니다.
이 구조까지 완성했다면 Ubuntu → Python → FastAPI → Nginx → systemd → GitHub Actions로 이어지는 하나의 실제 파이썬 서버 운영 환경을 경험했다고 볼 수 있습니다.