Enterpriseアカウントの管理

GraphQLでのEnterpriseアカウントの管理について

Organizationをモニターし、変更を行ってコンプライアンスを維持しやすくするために、Enterprise Accounts API及びAudit Log APIを利用できます。これらはGraphQL APIでのみ利用できます。

エンタープライズアカウントエンドポイントは、GitHub Enterprise Cloud と GitHub Enterprise Server の両方で機能します。

GraphQL を使用すると、指定したデータのみを要求し、返すことができます。たとえば、組織に追加された新しい組織メンバーの情報をすべて表示するには、GraphQL クエリ (つまり情報の要求) を作成します。また、Enterprise アカウントに管理者を招待するための変化 (変更) を加えることもできます。

監査ログ API を使用すると、誰かが次のような操作を行ったタイミングを監視できます。

組織またはリポジトリの設定にアクセスする。
アクセス許可を変更する。
組織、リポジトリ、またはチームのユーザーを追加または削除する。
ユーザーを管理者に昇格させる。
GitHub アプリのアクセス許可を変更します。

Audit Log API を使用すると、監査ログデータのコピーを保持できます。 Audit Log APIで発行するクエリについては、GraphQLのレスポンスには最大で90から120日分のデータが含まれることがあります。 Audit Log API で使用できるフィールドの一覧については、「企業管理」を参照してください。

エンタープライズアカウントAPIを利用すると、以下のことができます。

貴社のEnterpriseアカウントに属するすべての組織とリポジトリを列挙して確認してください。
Enterpriseアカウントの設定変更。
エンタープライズアカウントおよびその組織の設定のためのポリシーを構成します。
エンタープライズアカウントに管理者を招待する。
企業アカウント内で新しい組織を作成する。

Enterprise Accounts API で使用できるフィールドの一覧については、「Enterpriseアカウントの管理」を参照してください。

エンタープライズアカウントに GraphQL を使用するGetting started

GraphQL を使用してエンタープライズアカウントを管理し始めるには、GraphQL クライアントの使用を参照してください。

クエリの例については、「Enterprise アカウント API を使ったクエリの例」を参照してください。

1. 認証方法を選択する

GitHub App をサポートするエンタープライズ GraphQL 操作には、これを使用することをお勧めします。 GitHub Apps は、エンタープライズ所有者の personal access tokenに依存することなく、きめ細かいアクセス許可と有効期間の短いトークンを提供します。すべてのエンタープライズ GraphQL クエリとミューテーションが GitHub Appsをサポートしているわけではありません。それらをサポートしていない操作には、personal access token を使用します。

GitHub App を使用する

GitHub Appを登録し、運用に必要なエンタープライズアクセス許可を選択します。「GitHub アプリの登録」を参照してください。
管理する組織にアプリをインストールします。エンタープライズ所有者でない場合は、エンタープライズ所有者にインストールを依頼する必要があります。「Enterprise に GitHub アプリをインストールする」を参照してください。
操作と、アプリがユーザーに代わって動作する必要があるかどうかに応じて、インストールアクセストークンまたはユーザーアクセストークンを使用して認証します。以下のInsomniaの手順では、ユーザーアクセストークンを使用します。

エンタープライズインストールでは、エンタープライズ権限のみが付与されます。企業内の組織またはリポジトリへのアクセス権は付与されません。組織またはリポジトリの操作を行うには、アプリを関連する組織に個別にインストールし、適切なアクセス許可が必要です。組織にインストールされたアプリは、ユーザーアクセストークンを使用して、GraphQL クエリで複数の組織にまたがって動作できます。インストールトークンは、1 つの企業または組織のアカウントにロックされ、アカウントの境界を越えて使用することはできません。

personal access token を使用する

必要な操作がpersonal access tokenをサポートしていない場合、または 1 つの GraphQL クエリで複数の組織またはリポジトリデータにアクセスする自動化を構築する場合は、GitHub Appsを使用します。

personal access tokenを使用してGraphQLで認証するには、開発者設定でそれを作成してください。詳細については、「個人用アクセストークンを管理する」を参照してください。
アクセスしたい組織内の領域に対して、personal access token に管理者権限とフルコントロール権限を付与します。プライベートリポジトリ、組織、チーム、ユーザーデータ、エンタープライズ課金データとプロファイルデータへのアクセスに対する完全なアクセス許可については、 personal access tokenに対して次のスコープを選択することをお勧めします。
- repo
- admin:org
- user
- admin:enterprise
Enterpriseアカウントに固有のスコープは以下のとおりです。
- admin:enterprise: Enterprise のフルコントロールを付与します (manage_runners:enterprise、manage_billing:enterprise、read:enterprise を含みます)
- manage_billing:enterprise: エンタープライズ課金データの読み取りと書き込み。
- read:enterprise: エンタープライズのプロファイルデータを読み取ります。
personal access tokenをコピーし、GraphQL クライアントに追加するまで安全な場所に保管します。

2. GraphQL クライアントの選択

GraphiQLもしくはベースURLの設定ができる他のスタンドアローンの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
- 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] を選択します。別の認証方法を選択したことがある場合は、タブにその方法のラベルが付いている可能性があります。

これらの設定を、独自のアプリの認証情報で設定します。

Setting	Value
Enabled	✔️
助成金の種類	認可コード
認可 URL	`https://github.com/login/oauth/authorize`
アクセストークンURL	`https://github.com/login/oauth/access_token`
クライアント ID	アプリのクライアント ID
クライアントシークレット	アプリのクライアントシークレット
PKCE を使用する

データ所在地で GitHub Enterprise Cloud を使用する場合は、両方の OAuth URL の https://github.com を https://SUBDOMAIN.ghe.comに置き換えます。ここで、 SUBDOMAIN は企業のサブドメインです。 api.SUBDOMAIN.ghe.comホスト名ではなく、Web URL を使用してください。

[ トークンのフェッチ] をクリックしてサインインし、必要なエンタープライズアクセス許可を持つユーザーとしてアプリを承認します。ユーザーアクセストークンは、ユーザーとアプリの両方がアクセスできるアクセス許可とリソースに制限されます。 Insomniaは、取得したトークンをリクエストに使用します。

詳細については、「GitHub アプリのユーザーアクセストークンの生成」を参照してください。

personal access token を使用して認証する

代わりに personal access token を使用する場合は、ベアラー認証を構成します。

[ 認証 ] メニューを選択し、[ ベアラートークン] をクリックします。以前に別の認証方法を選択した場合、メニューには代わりにその方法ののラベルが付けられています ([基本認証] など)。
[TOKEN] フィールドに、前の手順の personal access token を入力します。

Insomnia の [ベアラー] 認証設定のスクリーンショット。 [TOKEN] フィールドが濃いオレンジ色の枠線で囲まれています。

コンテンツタイプを設定する

認証方法を構成した後、リクエストのContent-Typeを設定します。

[ヘッダー] をクリックします。

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 クエリの例では、エンタープライズアカウント API を使用せずに各組織の public リポジトリの数を取得することがいかに困難であるかを示しています。単一の変数だけをカスタマイズすれば済むようになることから、Enterpriseにとって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
  }
}

各Organizationに対して個別にクエリを行う

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のフィールドと型

エンタープライズアカウント API で使用できる新しいクエリ、ミューテーション、およびスキーマ定義型の詳細については、GraphQL リファレンスページの詳細な GraphQL 定義が表示されているサイドバーを参照してください。

GraphQL クライアント内から参照ドキュメントをaccessできます。詳細については、「GraphQL クライアントの使用」を参照してください。認証やレート制限の詳細など、その他の情報については、guidesを参照してください。

この記事で