GitHub - Codespaces

概要

GitHub Codespacesは、クラウド上にホストされた開発環境を提供するGitHubの機能である。

Ubuntu Linux仮想マシン上のDockerコンテナとして動作し、ブラウザ版VS Code、デスクトップ版VS Code、またはGitHub CLIから接続して利用できる。

ローカル環境のセットアップ不要で即座に開発を開始でき、チームメンバー間で統一された開発環境を共有できることが主なメリットである。

下表に、Codespacesが提供する主な機能を示す。

GitHub Codespacesの主な機能

機能	説明
クラウド開発環境	Ubuntu Linux仮想マシン上のDockerコンテナとして動作し、Webブラウザからすぐに利用できる。
Dev Container対応	devcontainer.jsonで開発環境を定義して、チーム全体で同一の環境を再現できる。
複数の接続方法	ブラウザ版VS Code、デスクトップ版VS Code、GitHub CLI等の複数の方法で接続できる。
プリビルド機能	依存関係のインストールやビルドを事前に実行することにより、Codespace作成時間を短縮できる。
シークレット管理	環境変数としてシークレットを安全に注入して、APIキーや認証情報を管理できる。

Codespaceの作成

リポジトリからの作成

Codespaceはリポジトリのページから直接作成できる。

Web UIからの作成手順を以下に示す。

1. [リポジトリ]ページを開く。
2. 緑色の[Code]ボタンを押下する。
3. [Codespaces]タブを選択する。
4. [Create codespace on <ブランチ名>]を選択する。

VS Codeから作成する場合は、[Remote Explorer]パネルを開いて、[+]ボタンを押下する。

GitHub CLIから作成するコマンドを以下に示す。

gh codespace create -r OWNER/REPO -b BRANCH

リポジトリ名とブランチを指定しない場合は、対話形式で選択できる。

ブランチ・PR・テンプレートからの作成

特定のブランチやPull Request、テンプレートからもCodespaceを作成できる。

• ブランチからの作成

  [ブランチ]ページの[Code]ボタンから、そのブランチに対応したCodespaceを作成できる。

• Pull Requestからの作成

  [PR]ページの[Code]ボタンから、PRのブランチに対応したCodespaceを作成できる。

  PRの変更内容をレビューしながら動作確認する用途に適している。

• テンプレートからの作成

  github.com/codespaces/templates から、Node.js、Python、JavaScript等のテンプレートを選択して空のCodespaceを作成できる。

マシンタイプの選択

Codespaceのマシンタイプはコア数とメモリ容量によって異なる。

下表に、利用可能なマシンタイプを示す。

Codespacesのマシンタイプと料金

マシンタイプ	メモリ	ストレージ	料金	用途
2-core	8[GB]	32[GB]	$0.18/時間	軽量な開発、スクリプト作業
4-core	16[GB]	32[GB]	$0.36/時間	一般的なWebアプリケーション開発
8-core	32[GB]	64[GB]	$0.72/時間	中規模アプリケーション、複数サービスの並行起動
16-core	64[GB]	128[GB]	$1.44/時間	大規模プロジェクト、重いビルド作業
32-core	128[GB]	128[GB]	$2.88/時間	機械学習、大規模コンパイル作業

マシンタイプは作成後も変更できる。

• Web UIからの変更

  [Your codespaces]ページで対象のCodespaceのメニューから[Change machine type]を選択する。

• VS Codeからの変更

  コマンドパレットで Codespaces: Change Machine Type を実行する。

• CLIからの変更

  以下に示すコマンドを使用する。

  gh codespace edit --machine MACHINE_TYPE

リージョンの選択

Codespacesは複数のリージョンで利用できる。

リージョンは、[Settings] - [Codespaces] - [Region]から選択できる。

利用可能なリージョンを以下に示す。

• United States East
• United States West
• Europe West
• Southeast Asia

レイテンシを最小化するために、物理的に近いリージョンを選択することを推奨する。

Dev Container

Dev Containerとは

Dev Containerは、開発環境をコードとして定義する仕組みである。

devcontainer.jsonファイルにベースイメージ、インストールするツール、VS Code拡張機能、エディタ設定等を記述することで、チーム全員が同一の開発環境を利用できる。

Dev Containerを使用することにより、以下に示すメリットが得られる。

• 環境の再現性

  新しいメンバーが参加した際も、同一の開発環境を即座に構築できる。

• 依存関係の管理

  必要なツールやライブラリをコンテナ内に閉じ込め、ホスト環境との競合を防ぐ。

• CI/CDとの統合

  開発環境とCI環境を同一の定義で管理できる。

devcontainer.json

devcontainer.jsonはJSONC (コメント付きJSON) 形式で記述する設定ファイルである。

配置場所を以下に示す。

• .devcontainer/devcontainer.json
• .devcontainer.json (ルートディレクトリ直下)

複数のDev Container設定を持つ場合は、.devcontainer/<設定名>/devcontainer.json のようにサブディレクトリに配置できる。

主要な設定項目

下表に、devcontainer.jsonの主要な設定項目を示す。

devcontainer.jsonの設定項目一覧

設定項目	説明
image	ベースとなるDockerイメージを指定する。 例: "image": "mcr.microsoft.com/devcontainers/javascript-node:18"
features	追加する言語やツールを指定する。 Dev Container Featuresとして提供されているモジュールを使用する。 例: "features": {"ghcr.io/devcontainers/features/python:1": {"version": "3.11"}}
customizations.vscode.extensions	インストールするVS Code拡張機能のIDを配列で指定する。 例: "extensions": ["ms-python.python", "dbaeumer.vscode-eslint"]
customizations.vscode.settings	VS Codeのエディタ設定をキーと値のオブジェクトで指定する。 例: "settings": {"editor.tabSize": 2}
forwardPorts	コンテナ内のポートをホストに転送するポート番号の配列を指定する。 例: "forwardPorts": [3000, 5432]
postCreateCommand	Codespace作成後に自動実行するコマンドを指定する。 依存関係のインストール等に使用する。 例: "postCreateCommand": "npm install"
remoteEnv	コンテナ内に設定する環境変数をオブジェクトで指定する。
remoteUser	コンテナ内のデフォルトユーザを指定する。

devcontainer.jsonの記述例を以下に示す。

 {
    // Node.js開発環境の例
    "name": "Node.js Development",
    "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
    "features": {
       "ghcr.io/devcontainers/features/git:1": {}
    },
    "customizations": {
       "vscode": {
          "extensions": [
             "dbaeumer.vscode-eslint",
             "esbenp.prettier-vscode"
          ],
          "settings": {
             "editor.formatOnSave": true,
             "editor.defaultFormatter": "esbenp.prettier-vscode"
          }
       }
    },
    "forwardPorts": [3000],
    "postCreateCommand": "npm install"
 }

プリセット設定

下表に、GitHubが公式に提供するプリセットのDev Container設定を示す。

Dev Containerプリセット一覧

プリセット	イメージ	主な用途
Node.js / JavaScript	mcr.microsoft.com/devcontainers/javascript-node	フロントエンド、Node.jsバックエンド
Python	mcr.microsoft.com/devcontainers/python	Python Webアプリ、データサイエンス
Java	mcr.microsoft.com/devcontainers/java	Javaアプリケーション、Spring Boot
PHP	mcr.microsoft.com/devcontainers/php	WordPressを含むPHPアプリケーション
C# / .NET	mcr.microsoft.com/devcontainers/dotnet	ASP.NET Core等のC#アプリケーション

カスタムDockerfile

devcontainer.jsonからカスタムDockerfileを参照することにより、詳細な環境構築ができる。

.devcontainer/ ディレクトリに Dockerfile を配置し、devcontainer.jsonで参照する。

 {
    "name": "Custom Environment",
    "build": {
       "dockerfile": "Dockerfile",
       "context": ".."
    },
    "customizations": {
       "vscode": {
          "extensions": ["ms-python.python"]
       }
    }
 }

カスタムDockerfileの例を以下に示す。

FROM mcr.microsoft.com/devcontainers/python:3.11

# 追加パッケージのインストール
RUN apt-get update && apt-get install -y \
   postgresql-client \
   redis-tools \
   && rm -rf /var/lib/apt/lists/*

# Pythonパッケージのインストール
COPY requirements.txt /tmp/
RUN pip install -r /tmp/requirements.txt

Docker Composeとの連携

データベースや外部サービスを含む複数コンテナ構成には、Docker Composeと連携できる。

devcontainer.jsonで dockerComposeFile と service を指定する。

 {
    "name": "Full Stack Application",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "customizations": {
       "vscode": {
          "extensions": ["ms-python.python"]
       }
    }
 }

対応する docker-compose.yml の例を以下に示す。

 services:
    app:
       build: .
       volumes:
          - ../..:/workspace:cached
       command: sleep infinity
 
    db:
       image: postgres:15
       environment:
          POSTGRES_PASSWORD: devpassword
 
    redis:
       image: redis:7

Codespace内での開発

VS Code (ブラウザ版/デスクトップ版)

Codespaceには、Webブラウザ および デスクトップのVS Codeから接続できる。

• ブラウザ版VS Code

  セットアップ不要でブラウザから直接利用できる。

  一部の機能 (ローカルファイルへのアクセス等) に制限がある。

• デスクトップ版VS Code

  フルの機能を利用できる。

  Codespace内で[F1]キーを押下してコマンドパレットを開いて、Open in VS Code Desktop を実行することで切り替えられる。

デスクトップ版への接続にはVS Codeと GitHub Codespaces拡張機能が必要である。

ターミナル

Codespace内のターミナルはUbuntu Linux環境を提供する。

ターミナルはVS Codeのメニューから[Terminal] - [New Terminal]で開く または [Ctrl] + [`]キーで開ける。

デフォルトではbashが使用されるが、devcontainer.jsonの設定によりZshやFishに変更できる。

Git操作

CodespaceはGit操作に対応しており、GITHUB_TOKENによる自動認証が設定されている。

HTTPS経由のGit操作は追加の認証設定なしで実行できる。

VS Codeのソースコントロールビューから以下に示す操作が可能である。

• ファイルのステージング ([+]ボタン)
• コミットメッセージの入力とコミット実行
• リモートへのプッシュ
• Pull Requestの作成 (GitHub Pull Requests拡張機能使用時)

CLIからのGit操作例を以下に示す。

# ファイルのステージング
git add .

# コミット
git commit -m "<コミットメッセージ>"

# プッシュ
git push origin <ブランチ名>

ポートフォワーディング

Codespace内で起動したサービスのポートは、ポートフォワーディングによりブラウザからアクセスできる。

下表に、ポートフォワーディングの方法を示す。

ポート転送の方法一覧

方法	説明
自動転送	アプリケーションがlocalhostのポートにバインドすると、 VS Codeが自動的に検出してポートを転送する。
手動転送	VS CodeのPORTSタブで[+]ボタンを押下して、 転送するポート番号を手動で入力する。
devcontainer.jsonでの事前定義	forwardPorts フィールドに転送するポートを記述することにより、 Codespace起動時に自動的に設定される。

転送されたポートのアクセス制御設定を以下に示す。

ポートアクセス制御の設定

設定	説明	用途
Private (デフォルト)	Codespacesの認証が必要	個人開発、機密情報を含む環境
Organization	同一組織のメンバーのみアクセス可	チーム内での共有、デモ
Public	認証なしで誰でもアクセス可	外部へのデモ、一時的な公開

Live Share

VS CodeのLive Share機能を使用することにより、Codespace内での共同編集が可能である。

Live Shareを開始するには、VS CodeのLive Share拡張機能をインストールして、共有セッションを開始する。

参加者はCodespaceのURLを持っていなくても、Live ShareのリンクからCodespace内のファイルを閲覧・編集できる。

個人設定

dotfiles

dotfilesリポジトリを使用することで、全てのCodespaceに個人の設定を自動的に適用できる。

設定手順を以下に示す。

1. GitHubに dotfiles という名前のリポジトリを作成する。
2. install.sh または bootstrap.sh 等のインストールスクリプトを配置する。
3. [Settings] - [Codespaces] - [Dotfiles] - [Automatically install dotfiles from your dotfiles repository]を有効にする。

Codespaceが作成されるとdotfilesリポジトリが自動的にクローンされ、インストールスクリプトが実行される。

dotfilesに含めると便利な設定ファイルの例を以下に示す。

• .bashrc / .zshrc

  シェルの設定とエイリアス

• .gitconfig

  Gitのユーザ名、メールアドレス、エイリアス

• .vimrc

  Vimの設定

Settings Sync

VS CodeのSettings Sync機能を使用することにより、デスクトップ版VS CodeとCodespace (Webブラウザ版) 間で設定を同期できる。

同期される設定の種類を以下に示す。

• キーボードショートカット
• インストール済み拡張機能
• UIの状態 (パネルの配置等)
• スニペット
• タスクとデバッグ設定

Settings Syncを有効にするには、VS Codeのアカウントメニューから[Sign in to Sync Settings]を選択する。

デフォルトエディタ

Codespaceに接続する時のデフォルトエディタは、[Settings] - [Codespaces] - [Editor preference]から設定できる。

選択可能なエディタを以下に示す。

• Visual Studio Code (デスクトップ版)
• Visual Studio Code for the Web (Webブラウザ版)
• JetBrains Gateway (JetBrains製IDE向け)

GPGコミット署名

CodespaceではGPGを使用したコミット署名をサポートしている。

[Settings] - [SSH and GPG keys]からGPGキーを登録した後、Codespace内のgit設定でGPG署名を有効化することで署名付きコミットが可能になる。

git config --global commit.gpgsign true
git config --global user.signingkey <GPGキーID>

Codespaceの管理

起動・停止・削除

作成済みのCodespaceは、github.com/codespaces (Your codespaces) ページで一覧表示・管理できる。

各Codespaceに対して実行できる操作を以下に示す。

• 起動 (Open)

  CodespaceをWebブラウザで開く。

• 停止 (Stop codespace)

  Codespaceを停止する。

  停止中はストレージのみ課金される。

• 削除 (Delete)

  Codespaceを完全に削除する。

  保存されていない変更は失われる。

• 名前変更 (Rename)

  Codespaceに任意の名前を付ける。

CLIからの管理コマンドを以下に示す。

# Codespace一覧の表示
gh codespace list

# Codespaceの停止
gh codespace stop -c CODESPACE_NAME

# Codespaceの削除
gh codespace delete -c CODESPACE_NAME

タイムアウト設定

一定時間操作がない場合、Codespaceは自動的に停止する。

デフォルトのタイムアウト時間は30分であり、[Settings] - [Codespaces] - [Default idle timeout]から変更できる。

選択可能なタイムアウト時間を以下に示す。

• 5分
• 15分
• 30分 (デフォルト)
• 60分

組織の管理者はポリシーによってタイムアウトの最大値を制限できる。

自動削除 (リテンション)

停止状態のまま一定期間放置されたCodespaceは自動的に削除される。

デフォルトのリテンション期間は30日であり、[Settings] - [Codespaces] - [Default retention period]から変更できる。

設定可能な期間は1日から30日の範囲である。

削除前にGitHubから通知メールが送信されるが、コミット・プッシュされていない変更は失われるため注意が必要である。

リビルド

Dev Containerの設定を変更した時は、Codespaceをリビルドして変更を反映できる。

リビルドの種類を以下に示す。

• 通常リビルド

  Dockerイメージのキャッシュを使用してリビルドする。

  変更のない層はキャッシュが再利用されるため高速に完了する。

• フルリビルド

  キャッシュをクリアして最初からリビルドする。

  キャッシュ起因の問題を解決する場合に使用する。

VS Codeからリビルドするには、コマンドパレットで以下に示すコマンドを実行する。

• 通常リビルド

  Codespaces: Rebuild Container

• フルリビルド

  Codespaces: Full Rebuild Container

CLIからのリビルドコマンドを以下に示す。

# 通常リビルド
gh codespace rebuild -c CODESPACE_NAME

# フルリビルド
gh codespace rebuild --full -c CODESPACE_NAME

プリビルド

プリビルドとは

プリビルドは、大規模なリポジトリでのCodespace作成時間を短縮するための機能である。

通常、Codespace作成時にDev Containerのセットアップ (依存関係のインストール、ビルド等) が実行されるため、時間が掛かる場合がある。

プリビルドを設定すると、コードがプッシュされるたびにGitHub Actionsが自動的にDev Containerのセットアップを事前実行し、その結果をキャッシュする。

プリビルドを使用することにより、新しいCodespaceを数分ではなく数秒で作成できる。

プリビルドの設定

プリビルドはリポジトリ単位で設定する。

設定手順を以下に示す。

1. リポジトリの[Settings] - [Codespaces] - [Prebuild configuration]を開く。
2. [Set up prebuild]を選択する。
3. プリビルドを実行するブランチを選択する。
4. マシンタイプを選択する。
5. プリビルドをトリガーするイベントを選択する。(コードプッシュ時、スケジュール、手動)
6. リージョンを選択する。

プリビルドには、GitHub Actionsの実行時間が消費されることに注意する。

プリビルドが有効な場合、Codespace作成画面にプリビルドマークが表示される。

シークレット管理

Codespaces用シークレット

APIキーや認証情報等のシークレットは、環境変数としてCodespaceに安全に注入できる。

シークレットの設定方法を以下に示す。

• リポジトリレベルのシークレット

  [Settings] - [Secrets and variables] - [Codespaces] - [New repository secret]から設定する。

  そのリポジトリのCodespaceにのみ適用される。

• ユーザレベルのシークレット

  [Settings] - [Codespaces] - [Codespaces secrets] - [New secret]から設定する。

  複数のリポジトリで共有できる個人用シークレットである。

設定したシークレットはCodespace内で環境変数として自動的にエクスポートされる。

# シークレットの確認例
echo $MY_API_KEY

制限事項

シークレット管理には、以下に示す制限事項がある。

• シークレットの最大数

  1リポジトリまたはユーザあたり最大100個

• 各シークレットのサイズ

  最大48[KB]

• 名前の制限

  GITHUB_ プレフィックスは使用禁止

• Dockerfile内での使用

  Dockerfileのビルド時にはシークレットを参照できない。

  postCreateCommandやアプリケーション実行時にのみ使用できる。

組織での管理

Codespacesポリシー

組織の管理者はCodespacesのポリシーを設定して、メンバーの利用を制御できる。

設定可能なポリシーを以下に示す。

• アクセス制御

  Codespacesを使用できるメンバーを制限する。

• リポジトリ制限

  Codespacesを有効にするリポジトリを制限する。

• ネットワークポリシー

  Codespace内からのネットワークアクセスを制限する。

ポリシーは、[Organization]の[Settings] - [Codespaces]から設定できる。

マシンタイプの制限

管理者はメンバーが選択できるマシンタイプを制限できる。

例えば、コスト管理のためにメンバーが32-coreマシンを使用できないように制限することが可能である。

[Organization] - [Settings] - [Codespaces] - [Machine type policies]から設定する。

課金管理

組織のCodespaces利用費の負担先は、以下に示す2通りから選択できる。

• 組織負担

  組織のメンバーが使用したCodespacesの費用を組織が負担する。

  [Settings] - [Codespaces] - [Codespaces access] - [Enabled for all members] または 特定のメンバーを選択する。

• メンバー負担

  各メンバーが個人アカウントで費用を負担する。

  組織のCodespaces機能を有効にしない場合のデフォルト動作である。

組織の利用状況は、[Organization] - [Billing]ページで確認できる。

監査ログ (Audit Log) では、Codespaceの作成・削除・起動・停止等のイベントを追跡できる。

課金

無料枠

GitHubのプランに応じて毎月の無料枠が提供される。

GitHubプランごとの無料枠

プラン	コンピュート (コア時間)	ストレージ
Free	120コア時間/月	15[GB]/月
Pro	180コア時間/月	20[GB]/月

コア時間はCodespaceのコア数に使用時間を掛けた値である。

例えば、2-coreのCodespaceを10時間使用した場合、20コア時間を消費する。

無料枠を超えた分は従量課金となる。

コンピュート料金

下表に、無料枠を超えた場合のコンピュート料金を示す。

Codespacesのコンピュート料金

マシンタイプ	料金
2-core	$0.18/時間
4-core	$0.36/時間
8-core	$0.72/時間
16-core	$1.44/時間
32-core	$2.88/時間

コンピュート料金はCodespaceが起動している時間にのみ発生する。
停止中はコンピュート料金は発生しない。

ストレージ料金

Codespaceのストレージはコンテナの内容全体 (ソースコード、依存関係、ツール等) に対して課金される。

ストレージ料金は $0.07/[GB]-月 である。

ストレージ料金はCodespaceが停止中であっても、Codespaceが存在する限り発生する。

コストを抑えるために、使用しないCodespaceは削除することを推奨する。