이 글에서 다루는 내용

GitHub Organizations가 무엇인지 살펴보고, Self-hosted Runner를 적용했을 때 어떤 장점이 있는지 알아본다.

GitHub Organizations

GitHub Organizations는 팀이나 회사 단위로 여러 저장소와 구성원을 중앙에서 관리할 수 있는 공유 계정이다. 회사, 오픈소스 프로젝트, 팀 단위 작업에 적합하다.

GitHub Organizations 주요 구성 요소

Members & Roles

  • Owner — 모든 권한 보유, 설정 변경 및 멤버 관리 가능
  • Member — 기본 멤버, 팀 및 레포에 따라 권한 상이
  • Outside Collaborator — 조직 외부인, 특정 레포에만 접근 허용
  • Billing Manager — 결제 관련 권한만 보유

Teams

Organization 내 소그룹으로 frontend-team, backend-team, devops-team으로 나누고 각 팀에게 특정 레포 접근 권한을 부여할 수 있다. @org/frontend-team 처럼 멘션도 가능하다.

Repository 권한 레벨

레벨 설명
Read 코드 조회만 가능
Triage PR/Issue 관리 가능
Write 코드 push 가능
Maintain 레포 설정 일부 가능
Admin 레포 모든 권한

Organization 플랜

  • Free — 공개 레포 무제한, 비공개 레포는 협업 기능 제한
  • Team — 비공개 레포 풀 기능, 코드 오너, 필수 리뷰어 설정 등
  • Enterprise — SSO, SAML, 감사 로그, 고급 보안 기능

주요 기능

Branch Protection Rules

팀 레벨에서 main 브랜치 보호 규칙을 강제할 수 있다. PR 필수, 리뷰어 수 지정, CI 통과 필수 등.

CODEOWNERS

특정 파일/디렉토리에 자동으로 리뷰어를 지정한다.

# .github/CODEOWNERS
/frontend/   @my-org/frontend-team
/backend/    @my-org/backend-team
*.yml        @my-org/devops-team

Actions & Secrets 관리

Organization 레벨에서 공통 Secrets와 Variables를 설정하면 하위 모든 레포에서 재사용 가능하다.

Audit Log

누가 언제 어떤 레포에 접근했는지, 설정 변경 이력 등을 추적할 수 있다.

실무 구조 예시

my-company (Organization)
├── Teams
│   ├── frontend-team  →  web-app, design-system
│   ├── backend-team   →  api-server, auth-service
│   └── devops-team    →  infra, ci-cd-scripts (모든 레포 write)
└── Repositories
    ├── web-app
    ├── api-server
    ├── design-system
    └── infra

Organization에서 Self-hosted Runner 사용 시 장점

개인 계정은 레포마다 러너를 따로 등록해야 하지만, Organization은 한 번만 등록하면 모든 레포에서 공유된다.

# 개인 계정
repo-A  →  runner 등록
repo-B  →  runner 등록  (별도 등록 필요)
repo-C  →  runner 등록  (별도 등록 필요)

# Organization
my-org (runner 1개 등록)
├── repo-A  ✅ 공유
├── repo-B  ✅ 공유
└── repo-C  ✅ 공유

Runner Groups으로 세밀한 권한 제어

Organization이면 Runner Group으로 팀별 분리도 가능하다.

Organization Runners
├── Group: production    →  frontend-team, backend-team만 접근
├── Group: staging       →  전체 팀 접근
└── Group: ios-build     →  mobile-team만 접근 (Mac runner)

jobs:
  deploy-prod:
    runs-on: [self-hosted, production]  # production 그룹만

  build:
    runs-on: [self-hosted, staging]     # staging 그룹

관리 포인트 1곳으로 집중

Organization Settings → Actions → Runners
  • 러너 상태 모니터링 → 한 곳에서
  • 토큰 갱신 → 한 곳에서
  • 레포 접근 제어 → 한 곳에서
  • Secrets 공유 → 한 곳에서

개인 계정은 레포가 10개면 설정도 10곳을 돌아다녀야 하지만, Organization은 Settings 한 곳에서 전부 관리된다.

Organization Runner 등록 방법

# Organization Settings → Actions → Runners → New runner
./config.sh --url https://github.com/my-org \
            --token [TOKEN]

# 워크플로우에서 사용
jobs:
  deploy:
    runs-on: [self-hosted, linux, production]
    #                            ^^^^^^^^^^  커스텀 태그로 그룹 지정