엔터프라이즈 계정 관리

GraphQL을 사용하여 엔터프라이즈 계정 관리하기 정보

조직에서 모니터링 및 변경을 수행하고 규정 준수를 유지 관리하려면, GraphQL API로서만 사용 가능한 Enterprise Accounts API 및 Audit Log API를 사용할 수 있습니다.

엔터프라이즈 계정 엔드포인트는 GitHub Enterprise Cloud 및 GitHub Enterprise Server 모두에서 작동합니다.

GraphQL을 사용하면 지정한 데이터만 요청하고 반환할 수 있습니다. 예를 들어 GraphQL 쿼리를 만들거나 정보를 요청하여 조직에 추가된 새 조직 구성원을 모두 볼 수 있습니다. 또는 관리자를 Enterprise 계정에 초대하도록 변형 또는 변경을 수행할 수 있습니다.

Audit Log API를 사용하면 누군가가 다음을 수행할 때 모니터링할 수 있습니다.

조직 또는 리포지토리 설정에 액세스
권한 변경
조직, 리포지토리 또는 팀에서 사용자 추가 또는 제거
사용자를 관리자로 승격
GitHub 앱의 사용 권한을 변경합니다.

Audit Log API를 사용하면 감사 로그 데이터의 복사본을 유지할 수 있습니다. Audit Log API를 사용하여 수행된 쿼리의 경우 GraphQL 응답에 최대 90~120일 동안의 데이터가 포함될 수 있습니다. 감사 로그 API에서 사용할 수 있는 필드 목록은 기업 관리자을(를) 참조하세요.

Enterprise Accounts API를 사용하면 다음을 수행할 수 있습니다.

엔터프라이즈 계정에 속한 모든 조직 및 리포지토리를 나열하고 검토합니다.
엔터프라이즈 계정 설정을 변경합니다.
엔터프라이즈 계정 및 해당 조직의 설정에 대한 정책을 구성합니다.
엔터프라이즈 계정에 관리자를 초대합니다.
엔터프라이즈 계정에 새 조직을 만듭니다.

Enterprise Accounts API에서 사용할 수 있는 필드 목록은 엔터프라이즈 계정 관리 참조하세요.

엔터프라이즈 계정에서 GraphQL을 사용하여 시작하기

GraphQL을 사용하여 엔터프라이즈 계정을 관리하는 방법을 시작하려면 GraphQL 클라이언트 사용를 참조하세요.

일부 예제 쿼리는 Enterprise 계정 API를 사용하는 예제 쿼리를 참조하세요.

1. 인증 방법 선택

이를 지원하는 엔터프라이즈용 GraphQL 작업에 GitHub App를 사용하는 것을 권장합니다. GitHub Apps 엔터프라이즈 소유자의 personal access token에 의존하지 않고 세분화된 권한 및 수명이 짧은 토큰을 제공합니다. 모든 엔터프라이즈 GraphQL 쿼리 및 뮤테이션이 GitHub Apps 지원되지는 않습니다. 지원하지 않는 작업에는 personal access token를 사용합니다.

GitHub App을(를) 사용하여

GitHub App을 등록하고 운영에 필요한 엔터프라이즈 권한을 선택합니다. GitHub 앱 등록을(를) 참조하세요.
관리하려는 엔터프라이즈에 앱을 설치합니다. 엔터프라이즈 소유자가 아닌 경우 엔터프라이즈 소유자에게 설치하도록 요청해야 합니다. 엔터프라이즈에 GitHub 앱 설치을(를) 참조하세요.
작업 및 앱이 사용자를 대신하여 작동해야 하는지 여부에 따라 설치 액세스 토큰 또는 사용자 액세스 토큰으로 인증합니다. 아래의 Insomnia 지침에서는 사용자 액세스 토큰을 사용합니다.

엔터프라이즈 설치는 엔터프라이즈 권한만 부여합니다. 엔터프라이즈의 조직 또는 리포지토리에 대한 액세스 권한을 부여하지 않습니다. 조직 또는 리포지토리 작업의 경우 앱은 해당 조직들에 별도로 설치되어 있어야 하며 적절한 권한이 필요합니다. 조직에 설치되면 앱이 사용자 액세스 토큰을 사용하여 GraphQL 쿼리로 조직 전반에서 작동할 수 있습니다. 설치 토큰은 단일 엔터프라이즈 또는 조직 계정에 잠겨 있으며 계정 경계를 넘어 사용할 수 없습니다.

personal access token을(를) 사용하여

personal access token는 필요한 작업이 GitHub Apps를 지원하지 않거나 단일 GraphQL 쿼리에서 여러 조직 또는 리포지토리 데이터에 액세스하기 위한 자동화를 구축하는 경우에 사용합니다.

personal access token을 사용해 GraphQL로 인증하려면 개발자 설정에서 이를 만드세요. 자세한 내용은 개인용 액세스 토큰 관리 참조하세요.
액세스하려는 엔터프라이즈 내 영역에 대해 personal access token에 관리자 권한과 전체 제어 권한을 부여합니다. 개인 리포지토리, 조직, 팀, 사용자 데이터 및 엔터프라이즈 청구 및 프로필 데이터에 대한 액세스에 대한 모든 권한을 위해 다음 범위에 대해 personal access token선택하는 것이 좋습니다.
- repo
- admin:org
- user
- admin:enterprise
엔터프라이즈 계정 특정 범위는 다음과 같습니다.
- admin:enterprise: 엔터프라이즈 전체 제어 권한(manage_runners:enterprise, manage_billing:enterprise, read:enterprise 포함)
- manage_billing:enterprise: 엔터프라이즈 청구 데이터를 읽고 씁니다.
- read:enterprise: 엔터프라이즈 프로필 데이터 읽기.
personal access token GraphQL 클라이언트에 추가할 때까지 복사하여 안전한 위치에 보관합니다.

2. GraphQL 클라이언트 선택

기본 URL을 구성할 수 있는 GraphiQL 또는 다른 독립 실행형 GraphQL 클라이언트를 사용하는 것이 좋습니다.

다음 GraphQL 클라이언트를 사용하는 것도 고려할 수 있습니다.

다음 단계에서는 Insomnia를 사용합니다.

3. Insomnia를 GitHub GraphQL API와 엔터프라이즈 계정에서 사용할 수 있도록 설정하기

기본 URL 및 POST 메서드를 GraphQL 클라이언트에 추가합니다. GraphQL을 사용하여 정보(쿼리), 변경 정보(변형) 또는 GitHub API를 사용하여 데이터를 전송하는 경우 기본 HTTP 메서드는 POST이며 기본 URL은 다음 구문을 따릅니다.
- 엔터프라이즈 인스턴스의 경우: https://<HOST>/api/graphql
- GitHub Enterprise Cloud의 경우: https://api.github.com/graphql
- Data Residency가 있는 GitHub Enterprise Cloud의 경우: https://api.SUBDOMAIN.ghe.com/graphql

GitHub App로 인증

이 절차에서는 OAuth 2.0 권한 부여 코드 흐름을 사용하여 ****GitHub App(설치 액세스 토큰이 아님)을 가져옵니다.

앱 설정에서 콜백 URL을 http://localhost로 설정합니다. 이는 Insomnia에서 사용하는 리디렉션 URL과 정확히 일치해야 합니다.
앱 ID가 아닌 앱의 클라이언트 ID를 복사합니다. 클라이언트 암호를 생성하고 복사합니다. 비밀을 안전하게 유지하고 스크린샷이나 소스 코드에 공유하지 마세요. 이 흐름은 앱의 프라이빗 키를 사용하지 않습니다.
Insomnia에서 인증 탭을 선택한 다음 OAuth 2.0을 선택합니다. 이전에 다른 인증 방법을 선택한 경우 탭에 해당 메서드로 레이블이 지정될 수 있습니다.

사용자 고유의 앱의 자격 증명을 사용하여 이러한 설정을 구성합니다.

설정	Value
활성화됨	✔️
보조금 유형	권한 부여 코드
권한 부여 URL	`https://github.com/login/oauth/authorize`
액세스 토큰 URL	`https://github.com/login/oauth/access_token`
클라이언트 ID	앱의 클라이언트 ID
클라이언트 암호	앱의 클라이언트 비밀
PKCE 사용

GitHub Enterprise Cloud를 데이터 상주와 함께 사용하는 경우 두 OAuth URL에서 SUBDOMAIN를 https://SUBDOMAIN.ghe.com로 바꾸세요. 여기서 https://github.com는 엔터프라이즈의 하위 도메인입니다. 호스트 이름이 아니라 웹 URL을 사용합니다.

토큰 가져오기를 클릭하고, 로그인하고, 필요한 엔터프라이즈 권한이 있는 사용자로 앱을 승인합니다. 사용자 액세스 토큰은 사용자와 앱이 모두 액세스할 수 있는 권한 및 리소스로 제한됩니다. Insomnia는 요청에 페치된 토큰을 사용합니다.

자세한 내용은 GitHub 앱에 대한 사용자 액세스 토큰 생성 참조하세요.

personal access token로 인증

대신 personal access token를 사용하는 경우, 전달자 인증을 구성합니다.

인증 메뉴를 선택하고 Bearer Token을 클릭합니다. 이전에 다른 인증 방법을 선택한 경우 메뉴에 "기본 인증"과 같은 해당 메서드로 레이블이 지정됩니다.
"TOKEN" 필드에 이전 단계에서 받은 personal access token을 입력합니다.

Insomnia의 "Bearer" 인증 설정 스크린샷 "토큰" 필드가 진한 주황색 윤곽선으로 표시됩니다.

콘텐츠 형식을 설정하세요

인증 방법을 구성한 후 요청의 콘텐츠 형식을 설정합니다.

머리글을 클릭합니다.

Insomnia의 설정 탭 스크린샷 "설정" 탭이 진한 주황색 윤곽선으로 표시됩니다.

머리글 탭에서 추가를 클릭합니다.
“헤더” 필드에 Content-Type을 입력합니다.
“값” 필드에 application/json을 입력합니다.

이제 쿼리 만들기를 시작할 준비가 되었습니다.

Enterprise Accounts API를 사용하는 예제 쿼리

이 GraphQL 쿼리는 Enterprise Accounts API를 사용하여 각 어플라이언스의 조직의 총 public개의 리포지토리를 쿼리합니다. 이 쿼리를 사용자 지정하려면 <enterprise-account-name>을 엔터프라이즈 계정의 핸들로 바꿉니다. 예를 들어 엔터프라이즈 계정이 https://github.com/enterprises/octo-enterprise에 있는 경우 <enterprise-account-name>을 octo-enterprise으로 대체합니다.

query publicRepositoriesByOrganization($slug: String!) {
  enterprise(slug: $slug) {
    ...enterpriseFragment
  }
}

fragment enterpriseFragment on Enterprise {
  ... on Enterprise{
    name
    organizations(first: 100){
      nodes{
        name
        ... on Organization{
          name
          repositories(privacy: PUBLIC){
            totalCount
          }
        }
      }
    }
  }
}

# Passing our Enterprise Account as a variable
variables {
  "slug": "<enterprise-account-name>"
}

다음 GraphQL 쿼리 예제에서는 Enterprise Account API를 사용하지 않고 각 조직에서 public 리포지토리의 수를 검색하는 것이 얼마나 어려운지를 보여줍니다. GraphQL Enterprise Accounts API는 엔터프라이즈용으로 이 작업을 더 간단하게 만들었습니다. 사용자가 단일 변수만 사용자 지정하면 되기 때문입니다. 이 쿼리를 사용자 지정하려면 <name-of-organization-one>, <name-of-organization-two> 등을 인스턴스의 조직 이름으로 바꿉니다.

# Each organization is queried separately
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}

## How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

각 조직을 개별적으로 쿼리

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

이 GraphQL 쿼리는 엔터프라이즈 조직에 대한 마지막 5개의 로그 항목을 요청합니다. 이 쿼리를 사용자 지정하려면 <org-name> 및 <user-name>을 바꿉니다.

{
  organization(login: "<org-name>") {
    auditLog(last: 5, query: "actor:<user-name>") {
      edges {
        node {
          ... on AuditEntry {
# Get Audit Log Entry by 'Action'
            action
            actorLogin
            createdAt
# User 'Action' was performed on
           user{
              name
                email
            }
          }
        }
      }
    }
  }
}

GraphQL을 시작하기 위한 자세한 정보는 GraphQL 소개 및 GraphQL을 사용하여 통화 구성를 참조하세요.

Enterprise Accounts API에 대한 GraphQL 필드 및 형식

Enterprise Accounts API에서 사용할 수 있는 새 쿼리, 변형, 스키마 정의 형식에 대한 자세한 내용은 GraphQL 참조 페이지의 자세한 GraphQL 정의가 포함된 사이드바를 참조하세요.

GraphQL 클라이언트 내에서 참조 문서를 access 수 있습니다. 자세한 내용은 GraphQL 클라이언트 사용 참조하세요. 인증 및 속도 제한 세부 정보와 같은 기타 정보는 guides 확인하세요.

이 기사에서