GitHub との連携

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

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

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

これらの設定は、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 からの次のアクセス許可をリクエストします。

読み取りアクセス許可

書き込みアクセス許可

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

CircleCI が使用するアクセス許可の数をどうしても減らしたい場合は GitHub に連絡し、その旨をお伝えください。

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

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

ユーザーキーとは

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

デプロイキーとは

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

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

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

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

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

必要なアクセス許可のセットアップが完了したら、次のステップでは、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 のユーザーアカウントに関連付けて、ユーザーのすべてのリポジトリにアクセスできるようにします。

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

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

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

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

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

これで、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 で参照できます。

{: #rename-organizations-and-repositories }

組織名やリポジトリ名を変更したい場合は、[組織名およびリポジトリ名の変更](/docs/ja/rename-organizations-and-repositories) ガイドに従い、変更プロセスの途中で環境変数やコンテキストへのアクセスを失わないようにしてください。