Skip to main content
설명서에 자주 업데이트를 게시하며 이 페이지의 번역이 계속 진행 중일 수 있습니다. 최신 정보는 영어 설명서를 참조하세요.

이 버전의 GitHub Enterprise는 다음 날짜에 중단됩니다. 2023-03-15. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 성능 향상, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

자동 토큰 인증

GitHub는 GitHub Actions를 대신하여 인증하는 데 사용할 수 있는 토큰을 제공합니다.

참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.

GITHUB_TOKEN 비밀 정보

각 워크플로 실행이 시작될 때 GitHub은(는) 워크플로에서 사용할 고유한 GITHUB_TOKEN 비밀을 자동으로 만듭니다. GITHUB_TOKEN은 워크플로 실행에서 인증하는 데 사용할 수 있습니다.

GitHub Actions을(를) 사용하도록 설정하면 GitHub이(가) 리포지토리에 GitHub App을(를) 설치합니다. GITHUB_TOKEN 비밀은 GitHub App 설치 액세스 토큰입니다. 설치 액세스 토큰을 사용하여 리포지토리에 설치된 GitHub App을(를) 대신하여 인증할 수 있습니다. 토큰의 권한은 워크플로를 포함하는 리포지토리로 제한됩니다. 자세한 내용은 “GITHUB_TOKEN에 대한 권한”을 참조하세요.

각 작업이 시작되기 전에 GitHub은(는) 작업에 대한 설치 액세스 토큰을 가져옵니다. GITHUB_TOKEN은 작업이 완료되거나 최대 24시간 후에 만료됩니다.

토큰은 github.token 컨텍스트에서도 사용할 수 있습니다. 자세한 내용은 “컨텍스트”를 참조하세요.

워크플로에서 GITHUB_TOKEN 사용

다음과 같이 비밀을 참조하는 데 표준 구문을 사용하면 GITHUB_TOKEN을 사용할 수 있습니다. ${{ secrets.GITHUB_TOKEN }}. GITHUB_TOKEN 사용의 예에는 토큰을 입력으로 작업에 전달하거나 인증된 GitHub Enterprise Server API 요청을 수행하는 데 사용하는 경우가 포함됩니다.

중요: 워크플로가 GITHUB_TOKEN을 작업에 명시적으로 전달하지 않더라도 작업은 github.token 컨텍스트를 통해 GITHUB_TOKEN에 액세스할 수 있습니다. 좋은 보안 사례로, 항상 GITHUB_TOKEN에 부여된 권한을 제한하여 필요한 최소 액세스 권한만 갖도록 해야 합니다. 자세한 내용은 “GITHUB_TOKEN에 대한 권한”을 참조하세요.

리포지토리의 GITHUB_TOKEN을 사용하여 작업을 수행하는 경우 GITHUB_TOKEN는 새 워크플로 실행을 만들지 않습니다. 이렇게 하면 실수로 재귀 워크플로 실행을 만들지 못하도록 방지됩니다. 예를 들어, 워크플로 실행이 리포지토리의 GITHUB_TOKEN을 사용하여 코드를 푸시하는 경우 리포지토리가 push 이벤트 발생 시 실행되도록 구성된 워크플로를 포함하고 있더라도 새 워크플로가 실행되지 않습니다.

예제 1: 입력으로 GITHUB_TOKEN 전달

이 예제 워크플로는 repo-token 입력 매개 변수의 값으로 GITHUB_TOKEN이 필요한 레이블 지정자 작업을 사용합니다.

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v3
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

예제 2: REST API 호출

GITHUB_TOKEN은 인증된 API 호출을 수행하는 데 사용할 수 있습니다. 이 예제 워크플로는 GitHub REST API를 사용하여 이슈를 만듭니다.

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write 
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url http(s)://HOSTNAME/api/v3/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

GITHUB_TOKEN에 대한 권한

GitHub Apps에서 각 권한으로 액세스할 수 있는 API 엔드포인트에 대한 자세한 내용은 “GitHub App 권한”을 참조하세요.

다음 표에서는 기본적으로 GITHUB_TOKEN에 부여된 사용 권한을 보여 줍니다. 조직 또는 리포지토리에 대한 관리자 권한이 있는 사람은 기본 권한을 허용 또는 제한됨으로 설정할 수 있습니다. 엔터프라이즈, 조직 또는 리포지토리에 대해 GITHUB_TOKEN에 대한 기본 권한을 설정하는 방법에 대한 자세한 내용은 “엔터프라이즈에서 GitHub Actions엔터프라이즈에 대한 정책 적용”, “조직에 대한 GitHub Actions 사용 안 함 또는 제한” 또는 “리포지토리에 대한 GitHub Actions 설정 관리”를 참조하세요.

Scope기본 액세스 권한
(허용)
기본 액세스 권한
(제한)
에 대한 최대 액세스
에서 끌어오기 요청
퍼블릭 포크된 리포지토리[†]
actions읽기/쓰기없음읽기
checks읽기/쓰기없음읽기
내용읽기/쓰기읽기읽기
배포읽기/쓰기없음읽기
issues읽기/쓰기없음읽기
metadata읽기읽기읽기
패키지읽기/쓰기없음읽기
페이지읽기/쓰기없음읽기
pull-requests읽기/쓰기없음읽기
repository-projects읽기/쓰기없음읽기
security-events읽기/쓰기없음읽기
statuses읽기/쓰기없음읽기

[†] 프라이빗 리포지토리는 포크의 끌어오기 요청이 워크플로를 실행할 수 있는지 제어하고 에 할당된 GITHUB_TOKEN권한을 구성할 수 있습니다. 자세한 내용은 "리포지토리에 대한 GitHub Actions 설정 관리"를 참조하세요.

GITHUB_TOKEN에 대한 권한 수정

개별 워크플로 파일에서 GITHUB_TOKEN에 대한 권한을 수정할 수 있습니다. GITHUB_TOKEN에 대한 기본 권한이 제한적이면 일부 작업과 명령이 성공적으로 실행되도록 권한을 상승해야 할 수 있습니다. 기본 권한이 허용되는 경우 워크플로 파일을 편집하여 GITHUB_TOKEN에서 일부 권한을 제거할 수 있습니다. 적절한 보안 사례로, GITHUB_TOKEN에 최소한의 액세스 권한을 부여해야 합니다.

워크플로 실행 로그의 “작업 설정” 섹션에서 GITHUB_TOKEN이 특정 작업에 대해 가지고 있는 권한을 확인할 수 있습니다. 자세한 내용은 “워크플로 실행 로그 사용”을 참조하세요.

워크플로 파일의 permissions 키를 사용하여 전체 워크플로 또는 개별 작업에 대한 GITHUB_TOKEN의 권한을 수정할 수 있습니다. 이렇게 하면 워크플로 또는 작업에 필요한 최소 권한을 구성할 수 있습니다. permissions 키를 사용하는 경우 항상 읽기 액세스 권한을 가져오는 metadata 범위를 제외하고 지정되지 않은 모든 권한은 액세스 권한 없음으로 설정됩니다.

또한 permissions 키를 사용하여 포크된 리포지토리에 대한 읽기 권한을 추가 및 제거할 수 있지만 일반적으로 쓰기 액세스 권한은 부여할 수 없습니다. 이 동작의 예외는 관리 사용자가 GitHub Actions 설정의 끌어오기 요청에서 워크플로에 쓰기 토큰 보내기 옵션을 선택한 경우입니다. 자세한 내용은 “리포지토리에 대한 GitHub Actions 설정 관리”를 참조하세요.

이 문서의 앞부분에 있는 워크플로 예제 두 개는 워크플로 수준 및 작업 수준에서 사용 중인 permissions 키를 보여 줍니다. 예제 1에서는 전체 워크플로에 대해 두 가지 권한이 지정됩니다. 예제 2에서 단일 작업의 하나의 범위에 대해 쓰기 액세스 권한이 부여됩니다.

permissions 키에 대한 자세한 내용은 “GitHub Actions에 대한 워크플로 구문”을 참조하세요.

워크플로 작업에 대한 권한을 계산하는 방법

GITHUB_TOKEN에 대한 권한은 처음에 엔터프라이즈, 조직 또는 리포지토리의 기본 설정으로 설정됩니다. 기본값이 이러한 수준에서 제한된 권한으로 설정된 경우 관련 리포지토리에 적용됩니다. 예를 들어 조직 수준에서 제한된 기본값을 선택하는 경우 해당 조직의 모든 리포지토리는 제한된 권한을 기본값으로 사용합니다. 그런 다음 워크플로 파일 내의 구성에 따라 먼저 워크플로 수준에서 그리고 작업 수준에서 차례로 권한을 조정합니다. 마지막으로, 워크플로가 포크된 리포지토리의 끌어오기 요청에 의해 트리거되고 끌어오기 요청에서 워크플로에 쓰기 토큰 보내기 설정을 선택하지 않은 경우 읽기 전용으로 쓰기 권한을 변경하도록 권한이 조정됩니다.

추가 권한 부여

에서 GITHUB_TOKEN사용할 수 없는 권한이 필요한 토큰이 필요한 경우 personal access token를 만들고 리포지토리에서 비밀로 설정할 수 있습니다.

  1. 해당 리포지토리에 대한 적절한 권한이 있는 토큰을 사용하거나 만드세요. 자세한 내용은 "personal access token 만들기"를 참조하세요.
  2. 워크플로 리포지토리에 토큰을 비밀로 추가하고 ${{ secrets.SECRET_NAME }} 구문을 사용하여 토큰을 참조합니다. 자세한 내용은 “암호화된 비밀 만들기 및 사용”을 참조하세요.

추가 참고 자료