GitHub Actions를 활용한 Fork 레포 자동 동기화 구현

gpt가 만들어준 썸네일

GitHub Actions를 활용한 Fork 레포 자동 동기화 구현기

수많은 시도끝에 성공한 github actions 배포 자동 구축,,

 

🚀 문제 상황

배경: Vercel 무료 계정의 제약사항

Vercel 무료 계정을 사용하고 있는 상황에서, Organization 레포를 직접 Vercel에 배포하려면 Vercel Pro 계정이 필요했습니다. 따라서 다음과 같은 우회 방법을 선택했습니다:

1. Organization 레포를 개인 계정으로 Fork
2. 개인 Fork 레포를 Vercel에 연결하여 배포
3. Organization 레포의 변경사항을 수동으로 Fork에 동기화(이게 너무너무!! 번거로웠음)

매번 배포때마다 했던 짓..

불편했던 기존 워크플로우

Organization 레포에서 개인 Fork 레포로 작업하며 Vercel에 배포하는 환경에서, 매번 수동으로 "Sync Fork" 버튼을 눌러야 하는 번거로움이 있었습니다.

기존 워크플로우 (불편한 점):

1. Organization 레포의 main 브랜치에 변경사항 발생
2. 수동으로 개인 Fork 레포에서 "Sync Fork" 버튼 클릭 ← 🙄 매번 해야 함ㅜㅜ
3. Vercel이 변경사항을 감지하고 자동 배포

특히 팀 프로젝트에서는:

• 다른 팀원이 Organization 레포에 작업을 push할 때마다
• 내가 직접 Fork 레포에 들어가서 동기화해야 함
• 깜빡하면 최신 버전이 배포되지 않는 문제 발생

목표:

• Organization 레포 변경 시 실시간 자동 동기화
• 수동 개입 없이 Vercel 자동 배포까지 연결
• Vercel 무료 계정 제약을 우회하면서도 편리한 CI/CD 구축

🛠️ 해결 방법

Repository Dispatch를 활용한 두 단계 자동화 구현:

1. Organization 레포: 변경사항 발생 시 개인 레포에 신호 전송
2. 개인 Fork 레포: 신호 수신 시 자동으로 upstream 동기화

이를 sequence diagram으로 나타내면 다음과 같습니다.

workflow

📋 구현 단계

1단계: Personal Access Token 생성

GitHub 개인 설정에서 토큰을 생성합니다.

경로: GitHub 프로필 → Settings → Developer settings → Personal access tokens → Tokens (classic)

필요 권한:

• repo (전체 레포 권한)
• workflow (워크플로우 권한)

2단계: Organization 레포에 Secret 등록

Organization 레포의 Settings → Secrets and variables → Actions에서 PERSONAL_ACCESS_TOKEN으로 토큰을 저장합니다.

3단계: Organization 레포 워크플로우 설정

파일 위치: .github/workflows/notify-fork.yml

name: Notify Fork of Changes

on:
  push:
    branches: [ main ]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger fork sync via API
        run: |
          curl -L \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            https://api.github.com/repos/YOUR_USERNAME/YOUR_FORKED_REPO_NAME/dispatches \
            -d '{"event_type":"upstream-updated"}'

4단계: 개인 Fork 레포 워크플로우 설정

파일 위치: .github/workflows/sync-on-dispatch.yml

name: Sync on Upstream Update

on:
  repository_dispatch:
    types: [upstream-updated]

permissions:
  contents: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      - name: Configure Git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Sync with upstream
        run: |
          git remote add upstream https://github.com/ORGANIZATION_NAME/ORIGINAL_REPO_NAME.git
          git fetch upstream
          git merge upstream/main --no-edit
          git push origin main

🐛 마주친 문제들과 해결책

문제 1: peter-evans/repository-dispatch 액션에서 토큰 에러

에러 메시지:

Error: Parameter token or opts.auth is required

시도한 해결책:

• @v3 → @v2로 버전 다운그레이드
• client-payload 제거
• 토큰 권한 재확인

문제는 위의 시도방법들이 다 안돼서, 결국 직접 github api 사용하여 token을 부여해주는 식으로 변경했다.

최종 해결: peter-evans/repository-dispatch 액션 대신 GitHub REST API를 직접 사용하는 방식으로 변경했습니다.

문제 2: 개인 레포에서 git push 권한 에러

에러 메시지:

remote rejected - refusing to allow a GitHub App to create or update workflow

해결책: YAML 파일에 permissions: contents: write 추가하여 GitHub Actions에 쓰기 권한을 명시적으로 부여했습니다.

문제 3: ad-m/github-push-action 사용 시 권한 에러

해결책: 복잡한 push 액션 대신 간단한 git push origin main 명령어를 사용하는 방식으로 변경했습니다.

✅ 최종 결과

동작 플로우:

1. Organization 레포 main 브랜치에 변경사항 발생
2. notify-fork.yml 워크플로우가 실행되어 GitHub API로 개인 레포에 신호 전송
3. 개인 레포의 sync-on-dispatch.yml 워크플로우가 즉시 실행
4. upstream 변경사항을 자동으로 fetch & merge
5. 개인 레포 main 브랜치에 push
6. Vercel이 변경사항을 감지하고 자동 배포

소요 시간: Organization 레포 변경 후 1-2분 내 전체 과정 완료

🎯 핵심 포인트

1. Repository Dispatch 패턴: 한 레포에서 다른 레포의 워크플로우를 트리거하는 방식
2. GitHub REST API 직접 사용: 써드파티 액션의 제약을 피하고 안정성 확보
3. 권한 설정의 중요성: permissions: contents: write 명시 필수

🔍 참고사항

• Personal Access Token은 정기적으로 갱신 권장 -> 아니면 no expiration date로 설정해두기
• Organization 레포에 워크플로우 추가 권한이 필요
• 브라우저 캐시로 인해 Actions 로그가 즉시 반영되지 않을 수 있음

이제 수동 개입 없이 Organization 레포의 모든 변경사항이 개인 Fork를 거쳐 Vercel까지 자동으로 배포시킬 수있다.!!!

정상적으로 개인레포에서 sync fork 및 배포된 모습

💭 마치며

이번 프로젝트를 통해 CI/CD 자동화를 처음 구축해보는 경험을 했습니다. 처음에는 복잡해 보였지만, 실제로 구현해보니 생각보다 간단하면서도 효과가 뛰어났습니다.

앞으로 백엔드 서버 배포를 맡게 된다면, 이번 경험을 바탕으로 더 복잡한 CI/CD 파이프라인도 도전해보고 싶습니다. 테스트 자동화, 스테이징 환경 구축, 무중단 배포 등 더 고도화된 DevOps 경험을 쌓아보는 것이 목표입니다.~!