자동 토큰 인증

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에 의해 트리거되는 이벤트(workflow_dispatch 및 repository_dispatch 예외),는 새 워크플로 실행을 만들지 않습니다. 이렇게 하면 실수로 재귀 워크플로 실행을 만들지 못하도록 방지됩니다. 예를 들어, 워크플로 실행이 리포지토리의 GITHUB_TOKEN을 사용하여 코드를 푸시하는 경우 리포지토리가 push 이벤트 발생 시 실행되도록 구성된 워크플로를 포함하고 있더라도 새 워크플로가 실행되지 않습니다.

GITHUB_TOKEN을 사용하는 GitHub Actions 워크플로에서 푸시한 커밋은 GitHub Pages 빌드를 트리거하지 않습니다.

예제 1: 입력으로 GITHUB_TOKEN 전달

이 예제 워크플로는 GH_TOKEN 입력 매개 변수의 값으로 GITHUB_TOKEN이 필요한 GitHub CLI를 사용합니다.

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_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 앱에 필요한 권한”을 참조하세요.

다음 표에서는 기본적으로 GITHUB_TOKEN에 부여된 사용 권한을 보여 줍니다. 조직 또는 리포지토리에 대한 관리자 권한이 있는 사람은 기본 권한을 허용 또는 제한됨으로 설정할 수 있습니다. 엔터프라이즈, 조직 또는 리포지토리에 대한 기본 사용 권한을 설정하는 방법에 대한 GITHUB_TOKEN 자세한 내용은 "AUTOTITLE", "[엔터프라이즈에서 GitHub Actions에 대한 정책 적용](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization)" 또는 "리포지토리에 대한 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 키를 보여 줍니다. 이는 권한 범위를 제한하는 모범 사례이기 때문입니다.

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

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

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

추가 권한 부여

사용할 수 GITHUB_TOKEN없는 권한이 필요한 토큰이 필요한 경우 GitHub App을(를) 만들고 워크플로 내에서 설치 액세스 토큰을 생성할 수 있습니다. 자세한 내용은 "GitHub Actions 워크플로에서 GitHub 앱을 사용하여 인증된 API 요청 만들기"을(를) 참조하세요. 또는 personal access token을 만들고, 리포지토리에 비밀로 저장하고, ${{ secrets.SECRET_NAME }} 구문을 사용하여 워크플로의 토큰을 사용할 수 있습니다. 자세한 내용은 "개인용 액세스 토큰 관리" 및 "GitHub Actions에서 비밀 사용" 항목을 참조하세요.

추가 참고 자료

• "REST API에 대한 트래픽률 제한"