GitHub との連携ガイド

クラウド

このページの内容

概要

CircleCI で GitHub を使用するには、GitHub のアカウントを接続する必要があります。プロジェクトを CircleCI に追加すると、ユーザー登録時に CircleCI に与えた権限に基づいて、以下の設定がリポジトリに追加されます。

デプロイキー: GitHub からプロジェクトをチェックアウトするために使用されます。
サービスフック (またはプッシュフック): GitHub にプッシュしたときに CircleCI に通知を送信するために使用されます。

CircleCI のデフォルトでは、プッシュフックでビルドが行われます。したがって、リポジトリのすべてのプッシュフックに対してビルドがトリガーされます。また、プッシュはビルドをトリガーする最も一般的なケースです。

あまり一般的ではありませんが、CircleCI は以下の場合にもフックを使用します。

PR フック (プルリクエストフック) を処理して、CircleCI アプリの PR 情報を保存します。 CircleCI で Only build pull requests 設定が有効になっていると、PR がオープンされたとき、または既存の PR が存在するブランチへのプッシュがあったときにのみ、ビルドをトリガーします。これが設定されている場合でも、プロジェクトのデフォルトブランチへのすべてのプッシュは、常にビルドされます。
CircleCI で Build forked pull requests 設定が有効になっている場合、フォークされたリポジトリから作成された PR に応答してビルドをトリガーします。

これらの設定は、CircleCI Web アプリの各プロジェクトの Project Settings セクションでご確認いただけます。

Only Build Pull Requests 設定をオーバーライドする機能もサポートされています。具体的には、CircleCI は正規表現 (例: release.\*) で指定されたデフォルト以外のブランチからのすべてのコミットに対して検証を実行します。

現時点では、 Only Build Pull Requests 設定をオーバーライドする唯一の方法は、 https://support.circleci.com/ でサポートリクエストをオープンすることです。このリクエストには、CircleCI がすべてのコミットを検証するブランチの 許可リスト に追加したい正規表現を記載してください。組織に適用されている正規表現の削除や編集をする際もサポートリクエストを提出する必要があります。詳細については、 Ideas を参照してください。

GitHub で Webhook を編集して、ビルドをトリガーするイベントを制限できます。 Webhook の設定を編集することで、CircleCI に送信されるフックを変更できますが、ビルドをトリガーするフックの種類は変更されません。 CircleCI は常にプッシュフックでビルドを行い、設定によっては PR フックでもビルドを行います。ただし、Webhook の設定からプッシュフックを削除すると、ビルドを行いません。

詳しくは、 GitHub のフックの編集ドキュメントを参照してください。

タグプッシュでのビルド方法については、CircleCI のドキュメントでワークフローフィルターの説明を参照してください。

アクセス許可の概要

CircleCI では、 GitHub のアクセス許可モデルに定義されているように、GitHub からの次のアクセス許可をリクエストします。

読み取りアクセス許可

ユーザーのメールアドレスを取得する

書き込みアクセス許可

ユーザーのリポジトリリストを取得する
ユーザーアカウントに SSH キーを追加する

管理者アクセス許可 (プロジェクトの設定に必要)

リポジトリにデプロイキーを追加する
リポジトリにサービスフックを追加する

CircleCI は絶対に必要なアクセス許可しか要求しません。また、CircleCI が要求できるアクセス許可は GitHub が提供すると決めたアクセス許可のみに制限されます。たとえば、全ユーザーのリポジトリ (パブリックとプライベートの両方) の一覧を GitHub から取得するには、 repo スコープの権限が必要で、これは書き込みアクセス許可に相当します。 GitHub はユーザーのリポジトリの一覧に対して読み取りのみの権限は提供していないため、このような設定が必要になります。

GitHub アカウントの接続

CircleCI Web アプリで、GitHub に接続する組織を選択し、サイドバーの下部にあるユーザーアイコンをクリックして User Settings に移動します。ここで GitHub を選択できます。接続すると、既存のプロジェクトがダッシュボードに挿入され、フォローするプロジェクトを選択できるようになります。

次に、CircleCI でプロジェクトを実行するために必要なアクセス許可を設定します。

デプロイキーとユーザーキー

デプロイキーとは

新しいプロジェクトを追加すると、CircleCI は GitHub 上にそのプロジェクト用のデプロイキーを作成します。デプロイキーは SSH キーペアで、1 つはパブリック、もう 1 つはプライベートです。 GitHub がパブリックキーを格納し、CircleCI がプライベートキーを格納します。デプロイキーは、CircleCI に単一のリポジトリへのアクセス権を提供します。 CircleCI によるリポジトリへのプッシュを防止するには、このデプロイキーを読み取り専用に設定します。

ビルドからリポジトリにプッシュするには、書き込みアクセス権のあるデプロイキーが必要です。デプロイキーを作成するための GitHub 固有の方法については、次のセクションを参照してください。

ユーザーキーとは

ユーザーキーは、ユーザーに固有の SSH キーペアです。 GitHub がパブリックキーを格納し、CircleCI がプライベートキーを格納します。プライベートキーを持っていると、プロジェクトへの「Git」アクセスの目的で、そのユーザーとして行動することができます。

ユーザーキーとデプロイキーの違いとは？

GitHub がサポートするキーの種類は、デプロイキーとユーザーキーだけです。デプロイキーはグローバルに一意であり (たとえば、複数のリポジトリへのアクセス権を持つデプロイキーを作成するメカニズムはありません)、またユーザーキーには、それに関連付けられているユーザーとは別の_スコープ_の概念はありません。

複数のリポジトリへのアクセス権をきめ細かく設定するには、GitHub でマシンユーザーと呼ばれるアカウントの作成を検討してください。このユーザーにビルドが必要とする権限を正確に付与し、次にそのユーザーキーを CircleCI 上のプロジェクトに関連付けます。

GitHub SSH キーの追加作成

他のサービスにアクセスするために追加のSSHキーが必要な場合は、以下の手順で追加のキーを作成することができます。

この例では、GitHub リポジトリは https://github.com/you/test-repo で、CircleCI プロジェクトは https://app.circleci.com/pipelines/github/you/test-repo です。

GitHub の説明に従って、SSH キーペアを作成します。パスワードを入力するよう求められた場合、入力しないでください（以下はmacOSでキーを生成するコマンドの一例です）。
```
  ssh-keygen -t ed25519 -C "your_email@example.com"
```
https://github.com/you/test-repo/settings/keys に移動して Add Deploy Key をクリックします。 Title フィールドにタイトルを入力し、手順 1 で作成したパブリックキーをコピー＆ペーストします。 Allow write access をオンにし、Add key をクリックします。
CircleCI アプリのプロジェクトの設定にアクセスし、SSH Keys と Add SSH key を選択します。 Hostname のフィールドには、github.com を入力し、手順 1 で作成したプライベートキーを追加します。次に Add SSH Key をクリックします。

.circleci/config.yml ファイルで、add_ssh_keys キーを使用してジョブにフィンガープリントを追加します。

  version: 2.1

  jobs:
    deploy-job:
      steps:
        - add_ssh_keys:
            fingerprints:
              - "SO:ME:FIN:G:ER:PR:IN:T"

ジョブから GitHub リポジトリにプッシュすると、CircleCI は追加された SSH キーを使用します。

プライベートキーの使用方法

CircleCI がプロジェクトをビルドするときには、プライベートキーが .ssh ディレクトリにインストールされ、それに続いて SSH がバージョン管理プロバイダーと通信するように設定されます。したがって、プライベートキーは以下の用途で使用されます。

メインプロジェクトのチェックアウト
GitHub でホスティングされるサブモジュールのチェックアウト
GitHub でホスティングされるプライベートな依存関係のチェックアウト
Git の自動マージ、タグ付けなど

プライベートキーは、追加のプライベートリポジトリをプロジェクトでチェックアウトできるようにするためにも使用されます。

ユーザーキーのセキュリティ

CircleCI が SSH キーを公開することはありません。

CircleCI が生成するチェックアウトキーペアのプライベートキーが CircleCI システムの外に出ることはなく (パブリックキーのみ GitHub に転送されます)、ストレージ上では安全に暗号化されています。しかし、これらのキーはビルドコンテナにインストールされるため、CircleCI で実行されるすべてのコードから読み取ることができます。同様に、SSH 接続が可能な開発者は、このキーに直接アクセスできます。

SSH キーは信頼するユーザーとのみ共有してください。ユーザーキーを使用するプロジェクトの場合、すべての GitHub コラボレーターがリポジトリにアクセスできるため、ユーザーキーはソースコードを委ねられる人とのみ共有してください。

ユーザーキーの追加が必要なときに表示される一般的なエラーを示します。

Python: pip install ステップの場合:

ERROR: Repository not found.

Ruby: bundle install ステップの場合:

Permission denied (publickey).

.circleci/config.yml ファイルの追加

必要なアクセス許可のセットアップが完了したら、次のステップでは、CircleCI で使用するプロジェクトに .circleci/config.yml ファイルを追加します。 CircleCI に接続するリポジトリに .circleci ディレクトリを追加してください。そのディレクトリ内に config.yml ファイルを追加します。

.circleci/config.yml ファイルを作成し、GitHub のリポジトリに対してコミットすると、CircleCI は直ちにそのコードをチェックアウトし、設定されているテストがあればそれを含めて、最初のジョブを実行します。

CircleCI は、毎回クリーンなコンテナでテストを実行します。これにより、コードをプッシュするたびにテストが新たに実行され、他のユーザーはコードにアクセスできません。テストの更新をお客様のダッシュボードでリアルタイムに確認します。ステータス更新をメール通知で受け取ったり、GitHub に表示されるステータスバッジを確認したりできます。また、プルリクエスト画面にもすべてのテストが合格したことを示す総合的なステータスが表示されます。

順を追って設定を確認するには、設定ファイルのチュートリアルを参照してください。

プロジェクトでの追加のプライベートリポジトリのチェックアウトの有効化

テストプロセスが複数のリポジトリを参照する場合、CircleCI ではデプロイキーに加えて GitHub ユーザーキーも必要となります。デプロイキーは _1 つ_のリポジトリに対してのみ有効であるのに対して、GitHub ユーザーキーはユーザーの_すべて_の GitHub リポジトリに対してアクセス権を持つためです。

プロジェクトの Project Settings > SSH keys で、CircleCI に渡す GitHub のユーザーキーを指定します。ページの User Key までスクロールダウンし、Authorize with Github をクリックします。 CircleCI は、この新しい SSH キーを作成し、それを GitHub のユーザーアカウントに関連付けて、ユーザーのすべてのリポジトリにアクセスできるようにします。

キーのベストプラクティス

可能な限り、デプロイキーを使用します。
デプロイキーを使用できない場合は、マシンユーザーキーを使用して、必要最低限のリポジトリとアクセス許可の組み合わせになるようにアクセス権を制限する必要があります。
マシンユーザーキー以外のユーザーキーは使用しないでください (キーは特定のユーザーではなく、ビルドに関連付ける必要があります)。
リポジトリへのユーザーアクセスを取り消す場合、デプロイキーまたはユーザーキーを交換する必要があります。
1. GitHub へのユーザーアクセスを取り消した後、GitHub でキーを削除します。
2. CircleCI プロジェクトでキーを削除します。
3. CircleCI プロジェクトでキーを再生成します。
開発者に付与されている以上のアクセス権を必要とするリポジトリのビルドに、開発者がユーザーキーを使用してアクセスできないようにします。

SSH ホストの信頼性の確立

SSH キーを使用してリポジトリをチェックアウトするとき、既知のホストファイル (~/.ssh/known_hosts) に GitHub のフィンガープリントの追加が必要になる場合があります。そうすることで、Executor は接続しているホストの信頼性を検証できます。これは checkout ジョブステップによって自動的に処理されます。カスタマイズされたチェックアウトコマンドを使用する場合は、以下のコマンドを実行する必要があります。

mkdir -p ~/.ssh

echo 'github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
' >> ~/.ssh/known_hosts

対象サーバーの SSH キーは ssh-keyscan <host> を実行することで取得できます。そして、取得されたキーのうち ssh-rsa プレフィックスがついているものをジョブの known_hosts ファイルに追加します。たとえば、以下のようになります。

➜  ~ ssh-keyscan github.com
# github.com:22 SSH-2.0-babeld-2e9d163d
github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
# github.com:22 SSH-2.0-babeld-2e9d163d
# github.com:22 SSH-2.0-babeld-2e9d163d
➜  ~ ✗

以下のコマンドを実行すると、キーを known_hosts に追加できます。

ssh-keyscan github.com >> ~/.ssh/known_hosts

マシンユーザーによるアクセス制御

複数のリポジトリへのアクセス権をきめ細かく設定するには、CircleCI プロジェクト用にマシンユーザーを作成することをお勧めします。マシンユーザーとは、自動化タスクを実行するために作成する GitHub ユーザーです。マシンユーザーの SSH キーを使用すれば、リポジトリへのアクセス権を持つ任意のユーザーにプロジェクトのビルド、テスト、デプロイを許可することができます。マシンユーザーを作成することにより、単一ユーザーにリンクされた認証情報を紛失するリスクも低減できます。

マシンユーザーの SSH キーを使用するには、以下の手順で行います。

これらの手順を実行するには、マシンユーザーが管理者アクセス権を持っている必要があります。プロジェクトの追加が終了したら、マシンユーザーのアクセス権を読み取り専用に戻すとよいでしょう。

GitHub の説明に従ってマシンユーザーを作成します。
GitHub にマシンユーザーとしてログインします。
CircleCI Web アプリにログインします。 CircleCI を承認するように GitHub から要求されたら、Authorize application ボタンをクリックします。
Project ページで、マシンユーザーにアクセスを許可するすべてのプロジェクトをフォローします。
Project Settings > SSH keys ページで、User Key セクションの下にある、Authorize With GitHub** ボタンをクリックします。これで、マシンユーザーの代わりに SSH キーを作成して GitHub にアップロードする権限が CircleCI に付与されます。
認証後、再度SSH keysページに移動し、User Keyセクションに移動し、Add User Keyボタンをクリックし、Confirm Userボタンをクリックします。

これで、CircleCI はビルド中に実行されるすべての Git コマンドに対して、マシンユーザーの SSH キーを使用するようになります。

サードパーティのアプリケーション

GitHub は最近、組織単位でのサードパーティーアプリケーションへのアクセスの承認機能を追加しました。この変更が行われるまでは、組織のどのメンバーでも (GitHub のユーザーアカウントに紐づく OAuth トークンを生成して) アプリケーションを承認することが可能となっていました。また、アプリケーションはその OAuth トークンを用いることで、ユーザーが API を経由して実行するのと同じように、OAuth で認められている権限の範囲内で動作することができました。

現在のデフォルトでは、サードパーティのアクセス制限が有効になっている場合、OAuth トークンは組織のデータにアクセス_できません_。 OAuth の処理中かその後に、ユーザーは組織単位で明確にアクセス許可をリクエストしなければならず、組織の管理者はそのリクエストを承認する必要があります。

オーナーまたは管理者の場合、GitHub の Organization settings ページにアクセスし、その組織の Settings ボタンをクリックするとサードパーティのアクセス制限を有効にすることができます。サードパーティアプリケーションの制限を設定する場合は、Third-party application access policy のセクションで、Setup application access restrictions ボタンをクリックします。

これらの設定の詳細や設定方法は、 GitHub で参照できます。

CircleCI がビルドを実行している組織でこの制限を有効にすると、CircleCI は GitHub からプッシュイベントフックを受け取らなくなり、新しいプッシュをビルドしません。 API 呼び出しも拒否されます。これにより、たとえば古いビルドをリビルドしたときに、ソースのチェックアウトが失敗します。 CircleCI を再び稼働させるには、CircleCI アプリケーションへのアクセスを許可する必要があります。

GitHub 組織で CircleCI を再有効化する方法

ここでは、GitHub の組織に対するサードパーティアプリケーションのアクセス制限を有効化した後で、CircleCI の組織へのアクセスを再有効化する方法を解説します。 GitHub Settings を開くと、Organization access セクションで、管理者以外のメンバーは、アクセスをリクエストするか、管理者は、アクセスを付与するかを選択できます。

管理者以外のメンバーのワークフロー

GitHub 組織のメンバー (管理者以外) の場合、Request ボタンをクリックするとメッセージが組織の管理者に送信されます。管理者がそのリクエストを承認する必要があります。
Request approval from owners をクリックすると、組織のオーナーにメールが送信されます。
承認を待っている間は、組織名の隣に Access request pending が表示されます。
CircleCI が承認されると、組織名の隣にチェックマークが表示されます。

管理者・オーナーのワークフロー

組織のオーナー (管理者) の場合、Grant ボタンをクリックすると CircleCI にアクセス権を付与することができます。
CircleCI アプリを認証するためにパスワードを確認される場合があります。
CircleCI を承認すると、組織名の隣にチェックマークが表示されます。

アクセスが承認されると、CircleCI は元通りの挙動になるはずです。

組織名とリポジトリ名の変更

組織名やリポジトリ名を変更したい場合は、組織名およびリポジトリ名の変更ガイドに従い、変更プロセスの間に環境変数やコンテキストへのアクセスを失わないようにしてください。

次のステップ

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.