보안·관리 실습 예시

시크릿 제외 · 노출 대응 · 인증 운영을 난이도별 시나리오로 직접 따라 해보는 가이드 | ← 레퍼런스 문서로 돌아가기

대상 범위GitHub 보안 기능 · git 2.5x (2026-06)

이 파일의 목적매뉴얼의 개념을 실제 명령 흐름으로 재현해 보완

레퍼런스 문서Security_Manual.html — 각 시나리오에서 링크로 연결됩니다

작성일2026년 6월 16일

● 초급 Getting Started 처음 만든 프로젝트에서 비밀 파일이 올라가지 않도록 첫 방어선을 세운다

G-1 초급 .env를 .gitignore로 제외하기

Node.js 프로젝트를 막 시작했고 API 키를 .env에 적어 두려 합니다. 이 파일과 node_modules/가 실수로 커밋되지 않도록, 첫 커밋을 하기 전에 .gitignore로 미리 제외하려 합니다. 작업 대상은 현재 프로젝트 폴더이며 아직 .env는 커밋된 적이 없습니다.

사용 요소

.gitignore 패턴 문법

단계별 실행

.gitignore 파일 만들기
프로젝트 루트에 빈 .gitignore를 생성합니다.
```
touch .gitignore
```
제외 패턴 추가하기
환경설정·의존성·OS 부산물을 한 줄씩 적습니다. node_modules/는 끝 슬래시로 디렉터리만 제외합니다.
```
.env
node_modules/
.DS_Store
```
제외가 적용됐는지 확인하기
git status에서 .env가 Untracked 목록에도 보이지 않으면 성공입니다.
```
git status
```
규칙을 커밋해 공유하기
.gitignore 자체는 커밋해서 협업자와 같은 규칙을 공유합니다.
```
git add .gitignore
git commit -m "chore: add .gitignore for env and deps"
```

.gitignore에 적힌 패턴과 일치하는 파일은 Git이 추적 대상에서 빼므로, git add .를 해도 .env는 스테이징되지 않습니다. git status의 Untracked 목록에도 나타나지 않는 것이 정상입니다.

.gitignore는 아직 추적되지 않은 파일에만 효과가 있습니다. 비밀 파일을 만들기 전에 미리 패턴을 추가해 두면 실수를 원천 차단할 수 있어 가장 안전합니다.

● 중급 Daily Workflow 이미 올라간 비밀을 발견했을 때, 피해를 막는 올바른 순서로 대응한다

D-1 중급 실수로 커밋한 키 대응 + 회전

실무자가 .env에 든 API 키를 .gitignore에 넣기 전에 이미 커밋·푸시했음을 뒤늦게 발견했습니다. 전제: 키를 발급한 외부 서비스의 대시보드에 접근 권한이 있고, 저장소도 이미 원격에 올라가 있습니다. 노출을 최소화하면서 추적을 끊으려 합니다.

사용 요소

git rm --cached Actions secrets

회전이 최우선이다. 키가 한 번 커밋·푸시된 순간 이미 노출된 것이며, git rm --cached나 히스토리 정리는 과거 노출을 되돌리지 못합니다. 무엇보다 먼저 발급처에서 키를 폐기하고 새로 발급(회전)해야 합니다. 아래 1단계를 건너뛰면 나머지 작업은 의미가 없습니다.

단계별 실행

발급처에서 키를 즉시 회전하기 (최우선)
외부 서비스 대시보드에서 노출된 키를 폐기하고 새 키를 발급합니다. 이 단계가 가장 먼저입니다.
```
# 서비스 대시보드 → API keys → 기존 키 폐기(revoke) → 새 키 발급
```
추적에서 .env 빼기 (로컬은 보존)
--cached는 인덱스에서만 제거하고 로컬 파일은 그대로 둡니다.
```
git rm --cached .env
```
.gitignore 확인 후 커밋하기
.gitignore에 .env가 들어 있는지 확인한 뒤 변경을 커밋합니다.
```
git commit -m "chore: stop tracking .env, rotate exposed key"
git push
```
새 키는 secrets로만 주입하기
새 키는 더 이상 커밋하지 않고 .env(로컬)나 Actions secrets로만 주입합니다.
```
gh secret set API_KEY
```

git rm --cached는 추적만 끊을 뿐 과거 히스토리에는 옛 키가 그대로 남습니다. 누구든 이전 커밋을 들여다보면 키를 볼 수 있으므로, 1단계의 회전으로 옛 키를 무효화하는 것이 실질적인 방어입니다. 이후 커밋부터 .env는 추적되지 않습니다.

새 키를 다시 run:에서 echo하거나 코드에 하드코딩하지 마세요. Actions에서는 env:로 주입하고, 로그에서 ***로 마스킹되는지 확인합니다.

● 고급 Power User 인증 수단과 Actions secrets를 조합해 안전한 자동화 파이프라인을 운영한다

P-1 고급 PAT/SSH 인증 + Actions secrets 운영

숙련자가 새 머신에서 저장소에 인증을 설정하고, 워크플로가 외부 API 키를 안전하게 쓰도록 Actions secrets를 운영하려 합니다. 전제: macOS 머신이며 GitHub 계정에 SSH 키 또는 토큰을 등록할 권한이 있고, 저장소에 GitHub Actions 워크플로가 있습니다.

사용 요소

ssh-keygen gh auth login gh secret set

단계별 실행

SSH 키 생성·등록 또는 gh로 로그인하기
ed25519 키를 만들어 agent에 추가하고 공개키를 GitHub에 등록하거나, 간단히 gh auth login(HTTPS)으로 자격증명을 저장합니다.
```
ssh-keygen -t ed25519 -C "email"
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# 또는
gh auth login
```
API 키를 Actions secret으로 등록하기
워크플로가 쓸 외부 API 키를 저장소 secret으로 올립니다.
```
gh secret set API_KEY
```
워크플로에서 env로 참조하기
secret은 run:에 직접 쓰지 않고 env:로 주입한 뒤 따옴표로 감싸 사용합니다.
```
steps:
  - shell: bash
    env:
      API_KEY: ${{ secrets.API_KEY }}
    run: example-command "$API_KEY"
```

SSH/HTTPS 인증으로 push·pull이 자격증명 입력 없이 동작하고, secret은 암호화되어 저장된 뒤 워크플로 실행 시 env로만 노출됩니다. 로그에 출력되더라도 GitHub가 ***로 마스킹합니다. fine-grained PAT를 쓴다면 만료일과 필요한 저장소·권한만 지정합니다.

secret이 실제로 로그에서 ***로 마스킹되는지 워크플로 실행 후 확인하세요. fine-grained PAT는 만료일 + 최소 권한 원칙으로 발급하는 것이 안전합니다.

GITHUB_TOKEN을 제외한 secrets는 fork PR 워크플로에는 전달되지 않습니다. 외부 기여자의 fork에서 secret이 필요한 작업이 돌아가지 않도록 트리거 조건을 설계하세요.

GitHub 보안 기능 · git 2.5x 기준 | 2026년 6월 16일 작성
← 보안·관리 매뉴얼