워크플로 실행 전 저장소 코드를 안전하게 가져오는 기본 단계
깃허브 액션스 워크플로가 시작될 때 필요한 코드 파일을 작업 공간에 내려받는 과정을 자동화합니다. 이는 워크플로가 실행되는 환경에 저장소의 특정 버전이나 브랜치를 준비해 주는 도구입니다. 덕분에 스크립트나 빌드 명령이 바로 코드를 참조할 수 있게 됩니다.
포크 요청 보안 강화
최근 버전에서는 포크 저장소에서 온 풀 리퀘스트 코드 처리 방식을 바꿨습니다. pull_request_target이나 workflow_run 트리거로 실행되는 워크플로는 기본 저장소의 토큰과 시크릿을 사용하므로, 포크 코드를 실행하면 보안 취약점이 생길 수 있습니다. 이를 막기 위해 기본적으로 포크 코드 체크아웃을 거부합니다. 위험을 검토한 후에도 포크 코드를 실행해야 한다면 allow-unsafe-pr-checkout: true 옵션을 설정해야 합니다. 또한 인증 정보를 .git/config 파일이 아닌 $RUNNER_TEMP 하위의 별도 파일에 저장하도록 변경되어 보안이 강화되었습니다.
유연한 체크아웃 옵션
전체 저장소를 가져오는 것 외에도 필요한 부분만 선택적으로 다운로드할 수 있습니다. sparse-checkout을 사용하면 루트 파일이나 특정 폴더, 단일 파일만 가져와 빌드 시간을 줄일 수 있습니다. fetch-depth 값을 조절해 가져올 커밋 이력의 범위를 지정할 수도 있습니다. 여러 저장소를 동시에 체크아웃할 때는 path 옵션으로 각 저장소를 나란히 또는 중첩된 구조로 배치할 수 있습니다. 사설 저장소를 체크아웃하려면 해당 저장소에 접근할 수 있는 개인 액세스 토큰(PAT)을 token 입력값으로 제공해야 합니다.
권한 설정과 요구 사항
이 액션을 사용할 때는 GITHUB_TOKEN의 권한을 contents: read로 설정하는 것이 권장됩니다. 이는 저장소 내용을 읽는 데 필요한 최소 권한입니다. Git 2.18 이상 버전이 시스템에 없다면 REST API를 통해 파일을 다운로드하는 방식으로 동작합니다. Docker 컨테이너 액션에서 인증된 git 명령을 실행하려면 Actions Runner v2.329.0 이상 버전이 필요합니다. 또한 이 저장소는 현재 외부 기여를 받지 않으며, 버그 보고와 보안 업데이트만 제공합니다.
적용 전 확인 사항
특히 pull_request_target을 사용하는 경우 포크 코드 실행 위험성을 반드시 검토해야 합니다. 사설 저장소를 다루는 경우 토큰의 범위를 최소화하는 것이 좋습니다. 이 액션은 MIT 라이선스로 공개되어 있어 자유롭게 사용할 수 있습니다. 다만, 특정 기능이나 버그 수정을 위해 직접 코드를 수정하거나 기여하는 것은 불가능하므로, 필요한 기능이 없다면 공식 로드맵이나 커뮤니티 토론을 통해 업데이트 여부를 확인하는 것이 좋습니다.
