인증

Workflow의 첫 Step은 대부분 저장소 체크아웃입니다. CollabOps는 이때의 인증으로 JobToken을 권장합니다. 이 문서는 JobToken이 무엇인지, 왜 권장하는지, 기존 SSH 키 기반 워크플로우를 어떻게 옮기는지 설명합니다.

JobToken이란

JobToken은 Job 실행 시점에 플랫폼이 자동으로 발급·주입하고 Job 종료 시 즉시 폐기되는 단명(短命) 자격증명입니다. 다음 특성을 가집니다.

단명 (ephemeral) — Job 실행 컨테이너 안에서만 유효하며, Job이 끝나면 자동으로 무효화됩니다.

범위 제한 (scoped) — 발급된 Job이 속한 저장소에 대한 read 권한으로 한정됩니다. 다른 저장소나 워크스페이스에는 접근할 수 없습니다.

시스템 발급 — 개인 사용자에게 묶이지 않습니다. 발급자가 퇴사하거나 권한이 변경되어도 파이프라인은 영향을 받지 않습니다.

추적 가능 (auditable) — 모든 접근이 Job 실행 컨텍스트(Run ID, 저장소, 트리거 이벤트)와 함께 감사 로그에 기록됩니다.

설정 불필요 — 사용자가 키를 생성/등록/순환할 필요가 없습니다. collabops/checkout@v2가 HTTPS URL을 받으면 자동으로 사용합니다.

왜 JobToken을 권장하는가

기존 관행대로 개인 SSH 개인 키를 워크스페이스 변수에 등록해 체크아웃에 사용하는 패턴은 동작은 하지만 다음 위험이 있습니다.

특히 개인 키는 한 명에게 묶여 있다는 점이 운영상 가장 큰 부채입니다. 그 사람이 퇴사하거나 권한이 회수되면 같은 변수를 쓰는 모든 워크플로우가 한꺼번에 중단됩니다.

권장 패턴

repo-url을 HTTPS scheme으로 작성하면 끝입니다. 인증 관련 추가 입력은 필요하지 않습니다.

jobs:
  build:
    steps:
      # JobToken 자동 주입 — ssh-key, 변수 등록 모두 불필요
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

      - name: build
        run: npm ci && npm run build
        image: node:18

URL의 <collabops-host>, <workspace>, <repository>만 환경에 맞게 채우면 됩니다. 토큰을 표현식으로 직접 참조할 필요도 없습니다.

SSH 키는 언제 사용하나

ssh-key 입력은 다음과 같은 제한된 상황에서만 사용하세요.

외부(타사) Git 호스팅 저장소를 체크아웃해야 할 때

On-Premise 환경의 네트워크 정책상 HTTPS가 막히고 SSH만 허용되는 경우

JobToken 범위를 넘어선 다른 저장소를 추가로 clone 해야 하는 특수 케이스

이 경우에도 가능하면 개인 계정 키 대신 저장소 전용 Deploy Key를 발급해 사용하세요. Deploy Key는 단일 저장소에 한정되므로 유출 시 영향 범위가 작습니다.

마이그레이션

기존 SSH 키 기반 체크아웃을 JobToken으로 옮기는 절차입니다.

Before

# ❌ 개인 SSH 키 기반 — 권한이 개인에 묶이고 키 관리 부담
jobs:
  build:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "git@<collabops-host>:<workspace>/<repository>.git"
          ssh-key: "${{ secrets.GIT_SSH_KEY }}"

After

# ✅ JobToken 기반 — URL만 https로 변경, 그 외 인증 입력 모두 제거
jobs:
  build:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

체크리스트

repo-url을 git@... / ssh://...에서 https://...로 변경

with.ssh-key 항목 제거

다른 Step에서 SSH 키를 참조하지 않는지 확인 (e.g. git submodule, 사설 패키지 설치)

Workflow가 정상 동작하면 워크스페이스 변수의 SSH 키 폐기 (저장소 측 등록 키도 함께 삭제)

FAQ

JobToken을 표현식으로 직접 참조할 수 있나요?

체크아웃에는 직접 참조가 필요 없습니다. collabops/checkout@v2가 내부적으로 사용합니다. Job 안에서 git을 직접 호출해야 하는 드문 경우에는 동일한 자격증명이 컨테이너에 자동 구성되어 있으므로 별도 작업 없이 그대로 사용할 수 있습니다.

JobToken으로 push도 가능한가요?

JobToken은 read 전용입니다. 워크플로우에서 커밋·푸시가 필요하면 워크스페이스 단위의 자동화 계정 자격증명을 별도로 발급해 사용하세요.

사설 npm/PyPI 등 다른 시스템 인증은 어떻게 하나요?

Git 체크아웃 외 외부 레지스트리는 JobToken 범위 밖입니다. 워크스페이스 secrets에 별도 토큰을 등록해 $\{\{ secrets.NPM_TOKEN \}\}처럼 참조하세요. Docker 레지스트리 인증은 docker-login (GCP는 gcloud-docker-auth, AWS ECR은 aws-ecr-auth) 템플릿을 사용하세요.

SSH 키 등록 절차

collabops/checkout 의 ssh-key 입력은 OpenSSH private key 의 base64 인코딩 형태로 등록하는 것이 정식 정책입니다. 임시 우회가 아니라 권장 입력 형식입니다.

SSH key 는 개행이나 공백 한 글자만 어긋나도 인증이 실패합니다. Secret 입력 UI 에 여러 줄 문자열을 붙여넣는 과정에서 손상 위험이 항상 존재하기 때문에, 줄바꿈 없는 한 줄 base64 문자열로 등록하면 손상 가능성이 사라집니다.

OS별 인코딩 명령

# macOS — clipboard 로 복사
cat /path/to/private_key | base64 | pbcopy

# Linux — 줄바꿈 없는 한 줄 문자열로 stdout 출력
cat /path/to/private_key | base64 -w0

# Windows PowerShell — clipboard 로 복사
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$env:USERPROFILE\.ssh\id_rsa")) | Set-Clipboard

결과는 줄바꿈 없는 한 줄 문자열이어야 합니다. Secret 값으로 그대로 등록하세요. WSL 환경은 Linux 명령을 그대로 사용할 수 있습니다.

인증 실패 시 진단

디코딩에 실패하거나 디코딩 결과가 OpenSSH private key 형식이 아니면, 워크플로우 로그에 OS별 인코딩 명령 안내가 함께 출력됩니다. 다음 항목을 확인하세요.

인코딩 결과가 줄바꿈 없는 한 줄 문자열인지

디코딩한 내용이 -----BEGIN OPENSSH PRIVATE KEY----- 같은 헤더로 시작하는지

공개키가 저장소(또는 Deploy Key) 측에 등록되어 있는지

관련 문서

collabops/checkout@v2 템플릿 입력 표

환경 변수 및 secrets