GitHub Actions 워크플로 이해 및 Secret 사용 모범 규약

1. Github Actions 란?

 => GitHub Actions는 빌드, 테스트 및 배포 파이프라인을 자동화할 수 있는 CI/CD(연속 통합 및 지속적인 업데이트) 플랫폼입니다. 리포지토리에 변경 내용을 푸시할 때마다 테스트를 실행하거나 병합된 pull request를 프로덕션에 배포하는 워크플로를 만들 수 있습니다.

 

2. 구성

 => 끌어오기 요청이 열리거나 이슈가 생성되는 것과 같은 ‘이벤트’가 리포지토리에서 발생할 때 트리거되도록 GitHub Actions ‘워크플로’를 구성할 수 있습니다. 워크플로는 순차적 또는 병렬로 실행될 수 있는 ‘작업’을 하나 이상 포함합니다. 각 작업은 자체 가상 머신 ‘실행기’ 또는 컨테이너 내에서 실행되며, 정의한 스크립트를 실행하거나 워크플로를 간소화할 수 있는 재사용 가능한 확장인 ‘작업’을 실행하는 ‘단계’를 하나 이상 포함합니다. 

 

3. Workflow 란?

=> 워크플로는 하나 이상의 작업을 실행할 구성 가능한 자동화된 프로세스입니다. 워크플로는 리포지토리에 체크 인된 YAML 파일에서 정의되며, 리포지토리의 이벤트로 트리거될 때 실행되거나 수동으로 또는 정의된 일정에 따라 트리거될 수 있습니다.

워크플로는 리포지토리의 .github/workflows 디렉터리에 정의됩니다. 리포지토리에 다음과 같은 각각의 다른 작업 집합을 수행하는 여러 워크플로가 있을 수 있습니다.

• 끌어오기 요청을 빌드하고 테스트합니다.
• 릴리스가 생성될 때마다 애플리케이션을 배포합니다.
• 새 문제가 보고될 때마다 레이블을 추가합니다.

워크플로를 자동으로 트리거하려면 를 사용하여 on워크플로를 실행할 수 있는 이벤트를 정의합니다. 구체적인 구문 링크는 아래를 참고하시기 바랍니다.

 

4. 이벤트

• 이벤트는 워크플로 실행을 트리거하는 리포지토리의 특정 활동입니다. 예를 들어 누군가가 끌어오기 요청을 만들거나, 이슈를 열거나, 리포지토리에 커밋을 푸시할 때 GitHub에서 활동이 시작될 수 있습니다. 일정에 따라 REST API에 게시하여 또는 수동으로 실행되도록 워크플로를 트리거할 수 있습니다.
• 주요 이벤트 트리거 커맨드
  
  • push: 브랜치 또는 태그에 변경 사항이 푸시될 때 트리거됩니다. 특정 파일 또는 폴더 변경에 따라 트리거를 제한하려면 paths 옵션을 사용할 수 있습니다. 
  • pull_request: 풀 리퀘스트가 생성, 업데이트 또는 닫힐 때 트리거됩니다.
  • workflow_dispatch: 사용자가 GitHub UI에서 워크플로우를 수동으로 실행할 때 트리거됩니다.
  • schedule: 지정된 cron 표현식에 따라 트리거됩니다. 예를 들어, 매일 자정에 실행되도록 설정할 수 있습니다.
  • release: 릴리즈가 생성, 업데이트 또는 삭제될 때 트리거됩니다. 
  • issues: 이슈가 생성, 업데이트 또는 닫힐 때 트리거됩니다.
  • pull_request_target: 풀 리퀘스트의 타겟 브랜치에 대한 변경 사항이 발생할 때 트리거됩니다.

5. Secret 설정

• 리포지토리 소유자만 개인 계정 리포지토리의 GitHub에 비밀 또는 변수를 만들 수 있습니다. GitHub에서 조직 리포지토리의 비밀이나 변수를 생성하려면 admin 액세스 권한이 있어야 합니다. 마지막으로, 협력자 액세스 권한이 있는 사용자만 REST API를 통해 개인 계정 리포지토리 또는 조직 리포지토리에 대한 비밀 또는 변수를 만들 수 있습니다.
• 조직에서 비밀 또는 변수를 만들 때, 정책을 사용하여 리포지토리별로 액세스를 제한할 수 있습니다. 예를 들어 모든 리포지토리에 대한 액세스 권한을 부여하거나 프라이빗 리포지토리 또는 지정된 리포지토리 목록에 대해서만 액세스를 제한할 수 있습니다
• 비밀 설정 관련 모범 사례
  • 최소 권한의 원칙
    • 저장소에 대한 쓰기 권한이 있는 모든 사용자는 저장소에 구성된 모든 비밀에 대한 읽기 권한을 갖습니다. 따라서 워크플로 내에서 사용되는 자격 증명에 필요한 최소한의 권한만 부여해야 합니다.
    • GITHUB_TOKEN작업은 컨텍스트 에서 에 액세스하여 을 사용할 수 있습니다 github.token. 자세한 내용은 컨텍스트 참조를GITHUB_TOKEN 참조하세요. 따라서 에 필요한 최소 권한이 부여되었는지 확인해야 합니다. 의 기본 권한을 저장소 콘텐츠에 대한 읽기 전용 권한으로 설정하는 것이 보안에 좋습니다. 그런 다음 필요에 따라 워크플로 파일 내의 개별 작업에 대한 권한을 늘릴 수 있습니다. 
  • 민감한 데이터 마스크
    • 민감한 데이터는 워크플로 파일에 일반 텍스트로 저장해서는 안 됩니다 . GitHub 비밀이 아닌 모든 민감한 정보는 ::add-mask::VALUE. 를 사용하여 마스크 처리하세요. 이렇게 하면 해당 값이 비밀로 처리되어 로그에서 삭제됩니다. 
  • 노출된 비밀 삭제 및 회전
    • 비밀 삭제는 워크플로 실행기에서 수행합니다. 즉, 작업 내에서 사용되었고 실행기가 액세스할 수 있는 비밀만 삭제됩니다. 삭제되지 않은 비밀이 워크플로 실행 로그로 전송된 경우, 로그를 삭제하고 해당 비밀을 순환해야 합니다. 
  • 구조화된 데이터를 비밀로 사용하지 마십시오
    • 구조화된 데이터는 로그 내 비밀 삭제가 실패하게 만들 수 있습니다. 삭제는 주로 특정 비밀 값과 정확히 일치하는 항목을 찾는 데 의존하기 때문입니다. 예를 들어, JSON, XML 또는 YAML(또는 유사한 형식)의 blob을 사용하여 비밀 값을 캡슐화하지 마십시오. 이렇게 하면 비밀이 제대로 삭제될 가능성이 크게 낮아집니다. 대신, 각 민감한 값에 대해 개별 비밀을 생성하십시오.
  • 워크플로 내에서 사용되는 모든 비밀을 등록합니다.
    • 워크플로 내에서 다른 민감한 값을 생성하는 데 비밀을 사용하는 경우, 생성된 값은 공식적으로 비밀로 등록 해야 로그에 기록될 경우 삭제됩니다. 예를 들어, 웹 API에 액세스하기 위해 개인 키를 사용하여 서명된 JWT를 생성하는 경우, 해당 JWT를 비밀로 등록해야 로그 출력에 기록될 경우 삭제되지 않습니다.
    • 비밀 등록은 모든 종류의 변환/인코딩에도 적용됩니다. 비밀이 Base64 또는 URL 인코딩 등 어떤 방식으로든 변환된 경우, 새 값도 비밀로 등록해야 합니다.
  • 비밀이 어떻게 처리되는지 감사
    • 비밀이 어떻게 사용되는지 감사하여 예상대로 처리되는지 확인하세요. 워크플로를 실행하는 저장소의 소스 코드를 검토하고 워크플로에서 사용되는 모든 작업을 확인하여 이를 수행할 수 있습니다. 예를 들어, 의도하지 않은 호스트로 전송되거나 로그 출력에 명시적으로 출력되지 않는지 확인하세요.
    • 유효/유효하지 않은 입력을 테스트한 후 워크플로 실행 로그를 확인하고, 비밀이 제대로 삭제되었는지 또는 표시되지 않았는지 확인하세요. 호출하는 명령이나 도구가 어떻게 오류를 STDOUT및 로 보내는지 항상 명확하게 알 수 있는 것은 아니며 STDERR, 결과적으로 비밀이 오류 로그에 기록될 수도 있습니다. 따라서 유효 및 유효하지 않은 입력을 테스트한 후 워크플로 로그를 수동으로 검토하는 것이 좋습니다. 
  • 등록된 비밀 감사 및 순환
    • 등록된 비밀번호를 정기적으로 검토하여 여전히 필요한지 확인하세요. 더 이상 필요하지 않은 비밀번호는 제거하세요.
    • 손상된 비밀이 유효한 시간 창을 줄이려면 비밀을 주기적으로 교체하세요.
  • 비밀에 대한 접근에 대한 검토를 요구하는 것을 고려하세요
    • 필수 검토자를 사용하여 환경 비밀을 보호할 수 있습니다. 워크플로 작업은 검토자의 승인을 받을 때까지 환경 비밀에 액세스할 수 없습니다. 

5. 참고 문서

• 워크플로 구문 및 Syntax : https://docs.github.com/ko/actions/reference/workflows-and-actions/workflow-syntax
• Gitaction Secret 사용 : https://docs.github.com/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets