GitHub API에 인증

GitHub API에 인증하여 GitHub과(와) 함께 Actions Runner Controller을(를) 사용하는 방법을 알아봅니다.

이 문서의 내용

법적 고지 사항

개요

GitHub App을(를) 사용하거나 personal access token (classic)을(를) 사용하여 GitHub API에 대한 Actions Runner Controller(ARC)을(를) 인증할 수 있습니다.

참고 항목

엔터프라이즈 수준의 실행기용 GitHub App을 사용하여 인증할 수 없습니다. 자세한 내용은 그룹을 사용하여 자체 호스트형 실행기에 대한 액세스 관리을(를) 참조하세요.

GitHub App(으)로 ARC 인증

  1. 조직이 소유한 GitHub App 만들기 자세한 내용은 GitHub 앱 등록을(를) 참조하세요. 다음과 같이 GitHub App을(를) 구성합니다.

    1. "홈페이지 URL"에 https://github.com/actions/actions-runner-controller를 입력합니다.

    2. "사용 권한"에서 리포지토리 권한을 클릭합니다. 그런 다음 드롭다운 메뉴를 사용하여 다음 액세스 권한을 선택합니다.

      • 관리: 읽기 및 쓰기

        참고 항목

        Administration: Read and write는 리포지토리 범위에서 등록할 Actions Runner Controller를 구성할 때만 필요합니다. 조직 범위에 등록할 때는 필요하지 않습니다.

      • 메타데이터: 읽기 전용

    3. "사용 권한"에서 조직 권한을 클릭합니다. 그런 다음 드롭다운 메뉴를 사용하여 다음 액세스 권한을 선택합니다.

      • 자체 호스트형 실행기: 읽기 및 쓰기

  2. GitHub App을(를) 만든 후 GitHub App의 페이지에서 "앱 ID" 값을 메모합니다. 해당 값은 이후에 사용합니다.

  3. "프라이빗 키"에서 프라이빗 키 생성을 클릭하고, .pem 파일을 저장합니다. 해당 키는 이후에 사용합니다.

  4. 페이지의 왼쪽 위 모서리에 있는 메뉴에서 앱 설치를 클릭하고 조직 옆에 있는 설치를 클릭하여 조직에 앱을 설치합니다.

  5. 조직에 대한 설치 권한을 확인한 후 앱 설치 ID를 기록해 둡니다. 나중에 필요합니다. 다음 URL 형식의 앱 설치 페이지에서 앱 설치 ID를 찾을 수 있습니다.

    https://github.com/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

  6. 이전 단계에서 다운로드한 앱 ID, 설치 ID 및 다운로드한 .pem 프라이빗 키 파일을 Kubernetes에 비밀로 등록합니다.

    GitHub App의 값을 Kubernetes에 비밀로 만들려면 다음 명령을 실행합니다.

    참고 항목

    gha-runner-scale-set 차트가 설치된 동일한 네임스페이스에 비밀을 만듭니다. 이 예제에서 네임스페이스는 빠른 시작 설명서와 일치하기 위해 arc-runners입니다. 자세한 내용은 Actions Runner Controller에 대한 빠른 시작을(를) 참조하세요.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_app_id=123456 \
   --from-literal=github_app_installation_id=654321 \
   --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

    다음으로 values.yaml 파일 복사본의 githubConfigSecret 속성을 비밀 이름에 참조로 전달합니다.

    githubConfigSecret: pre-defined-secret

추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

personal access token (classic)을(를) 사용하여 ARC 인증

ARC는 personal access tokens (classic)을(를) 사용하여 자체 호스트형 실행기를 등록할 수 있습니다.

참고 항목

personal access token (classic)을 사용하여 ARC를 인증하는 것이 엔터프라이즈 수준에서 실행기를 등록하는 유일한 인증 방법입니다.

  1. 필요한 범위가 있는 personal access token (classic)을(를) 만듭니다. 필요한 범위는 리포지토리, 조직 또는 조직 수준에서 실행기를 등록하는지 여부에 따라 다릅니다. personal access token (classic)를 만드는 방법에 대한 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.

    다음은 ARC 실행기의 필수 personal access token 범위 목록입니다.

    • 리포지토리 실행기: repo
    • 조직 실행기: admin:org
    • 엔터프라이즈 실행기: manage_runners:enterprise

  2. personal access token (classic)의 값으로 Kubernetes 비밀을 만들려면 다음 명령을 사용합니다.

    참고 항목

    gha-runner-scale-set 차트가 설치된 동일한 네임스페이스에 비밀을 만듭니다. 이 예제에서 네임스페이스는 빠른 시작 설명서와 일치하기 위해 arc-runners입니다. 자세한 내용은 Actions Runner Controller에 대한 빠른 시작을(를) 참조하세요.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. values.yaml 파일 복사본에서 비밀 이름을 참조로 전달합니다.

    githubConfigSecret: pre-defined-secret

    추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

fine-grained personal access token을 사용하여 ARC 인증

ARC는 fine-grained personal access tokens을 사용하여 자체 호스팅 러너를 등록할 수 있습니다.

참고 항목

personal access token (classic)을 사용하여 ARC를 인증하는 것이 엔터프라이즈 수준에서 실행기를 등록하는 유일한 인증 방법입니다.

  1. 필요한 범위가 있는 fine-grained personal access token을 만듭니다. 필요한 범위는 리포지토리 또는 조직 수준에서 러너를 등록하는지 여부에 따라 다릅니다. fine-grained personal access token을 만드는 방법에 대한 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.

    다음은 ARC 실행기의 필수 personal access token 범위 목록입니다.

    • 리포지토리 러너:

      • 관리: 읽기 및 쓰기

    • 조직 러너:

      • 관리: 읽기
      • 자체 호스트형 실행기: 읽기 및 쓰기

  2. fine-grained personal access token의 값으로 Kubernetes 비밀을 만들려면 다음 명령을 사용합니다.

    참고 항목

    gha-runner-scale-set 차트가 설치된 동일한 네임스페이스에 비밀을 만듭니다. 이 예제에서 네임스페이스는 빠른 시작 설명서와 일치하기 위해 arc-runners입니다. 자세한 내용은 Actions Runner Controller에 대한 빠른 시작을(를) 참조하세요.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. values.yaml 파일 복사본에서 비밀 이름을 참조로 전달합니다.

    githubConfigSecret: pre-defined-secret

    추가 Helm 구성 옵션은 ARC 리포지토리의 values.yaml을(를) 참조하세요.

자격 증명 모음 비밀을 사용하여 ARC 인증

참고 항목

자격 증명 모음 통합은 현재 Azure Key Vault를 지원하는 공개 미리 보기로 제공됩니다.

gha-runner-scale-set 버전 0.12.0부터 ARC는 외부 자격 증명 모음에서 GitHub 자격 증명 검색 기능을 지원합니다. 자격 증명 모음 통합은 실행기 확장 집합별로 구성됩니다. 즉, 보안 및 운영 요구 사항에 따라 일부 확장 집합은 Kubernetes 비밀을 사용하여 실행하고 다른 확장 집합은 자격 증명 모음 기반 비밀을 사용하여 실행할 수 있습니다.

자격 증명 모음 통합 사용

실행기 확장 집합에 자격 증명 모음 통합을 사용하도록 설정하려면 다음을 수행합니다.

  1. values.yaml 파일의 githubConfigSecret 필드를 자격 증명 모음에 저장된 비밀 키의 이름으로 설정합니다. 이 값은 문자열이어야 합니다.
  2. 적절한 공급자와 액세스 세부 정보를 이용하여 values.yaml 파일에서 keyVault 섹션의 주석 처리를 제거하고 구성하세요.
  3. 컨트롤러와 수신기 모두에필요한 인증서(.pfx)를 제공합니다. 다음을 수행하여 이 작업을 수행할 수 있습니다. *인증서가 포함된 컨트롤러 이미지를 다시 빌드하거나 *listenerTemplate 및 controllerManager 필드를 사용하여 인증서를 컨트롤러와 수신기 모두의 볼륨으로 마운트합니다.

비밀 형식

Azure Key Vault에 저장된 비밀은 JSON 형식이어야 합니다. 구조는 사용 중인 인증 유형에 따라 달라집니다.

예: GitHub 토큰

{
  "github_token": "TOKEN"
}

예: GitHub 앱

{
  "github_app_id": "APP_ID_OR_CLIENT_ID",
  "github_app_installation_id": "INSTALLATION_ID",
  "github_app_private_key": "PRIVATE_KEY"
}

자격 증명 모음 통합을 위한 values.yaml 구성

인증서는 .pfx 파일로 저장되고 /akv/cert.pfx의 컨테이너에 마운트됩니다. 다음은 인증에 이 인증서를 사용하도록 keyVault 섹션을 구성하는 방법의 예입니다.

keyVault:
  type: "azure_key_vault"
  proxy:
    https:
      url: "PROXY_URL"
      credentialSecretRef: "PROXY_CREDENTIALS_SECRET_NAME"
    http: {}
    noProxy: []
  azureKeyVault:
    clientId: <AZURE_CLIENT_ID>
    tenantId: <AZURE_TENANT_ID>
    url: <AZURE_VAULT_URL>
    certificatePath: "/akv/cert.pfx"

컨트롤러 및 수신기에 인증서 제공

ARC를 사용하려면 자격 증명 모음을 인증하기 위해 .pfx 인증서가 필요합니다. 이 인증서는 컨트롤러 설치 중에 컨트롤러와 수신기 구성 요소 모두에서 사용할 수 있어야 합니다. values.yaml 파일에서 controllerManager 및 listenerTemplate 필드를 사용하여 인증서를 볼륨으로 마운트하여 이 작업을 수행할 수 있습니다.

volumes:
  - name: cert-volume
    secret:
      secretName: my-cert-secret
volumeMounts:
  - mountPath: /akv
    name: cert-volume
    readOnly: true

listenerTemplate:
  volumeMounts:
    - name: cert-volume
      mountPath: /akv/certs
      readOnly: true
  volumes:
    - name: cert-volume
      secret:
        secretName: my-cert-secret

아래 코드는 확장 집합 values.yml 파일의 예입니다.

listenerTemplate:
  spec:
    containers:
      - name: listener
        volumeMounts:
          - name: cert-volume
            mountPath: /akv
            readOnly: true
    volumes:
      - name: cert-volume
        secret:
          secretName: my-cert-secret

다음은 Apache-2.0 라이선스에서 https://github.com/actions/actions-runner-controller/로부터 일부 조정되었습니다.

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.