2026.11.13 開発

VSCodeとGitLabの連携：公式拡張の導入と認証・MRレビュー・パイプライン操作の手順【2026年11月】

Q: GitLab WorkflowとGitLab for VS Codeは別の拡張機能ですか？

同じ拡張機能です。表示名が変わっただけで、MarketplaceのIDは GitLab.gitlab-workflow のままです。古い記事の「GitLab Workflowを入れる」は現行版を入れる操作と読み替えられますが、画面名やコマンド名は版ごとに変わっています。

Q: クローンせずにGitLabのリポジトリをVS Codeで見られますか？

読み取り専用であれば可能です。コマンドパレットで GitLab: Open Remote Repository を実行し、プロジェクトとブランチを選ぶと、クローンなしでファイルを閲覧できます。URLで指定する場合は リモートURLの公式ページ にある gitlab-remote:// 形式を使います。編集やcommitはできません。

Q: CursorやVSCodiumでもGitLab for VS Codeは使えますか？

VSCodiumのようにOpen VSX Registryを使うエディタでは、 GitLab/gitlab-workflow として入れられます。社内GitLabでOAuthを使うなら、管理者が登録したOAuthアプリのRedirect URIに、そのエディタ用のURIを改行区切りで追加しておく必要があります。トークン認証であれば、追加の登録は要りません。

Q: アクセストークンの期限が切れたらどう再設定しますか？

新しいトークンを発行し、コマンドパレットの GitLab: Authenticate で登録し直します。古いアカウント情報が残って混乱する場合は、先に GitLab: Remove Account from VS Code で削除してください。個人アクセストークンの既定の期限は365日なので、発行日を手元に記録しておくと切れる前に気づけます。

Q: VS CodeからGitLabのIssueを作成できますか？

GitLab: Create New Issue on Current Project で作成画面を開けますが、実際の入力はブラウザのNew issue画面で行います。一覧の表示とコメントの書き込みはVS Code内でできます。

VSCodeとGitLabの連携：公式拡張の導入と認証・MRレビュー・パイプライン操作の手順【2026年11月】

VS CodeとGitLabの連携は、GitLab社の公式拡張「GitLab for VS Code」（旧名GitLab Workflow）を入れて認証するところから始まります。この記事では、インストールと認証、Self-Managed（自社運用）のGitLabにつなぐ設定を手順で示し、マージリクエスト（MR）のレビュー、パイプラインの再実行、.gitlab-ci.ymlの検証をVS Code内で行う方法を説明します。後半は社内GitLabで接続できない場合の対処と、導入を見送ってよい場面の判断です。版番号とコマンド名は2026年11月時点の公式ドキュメントと拡張機能のソースで確認しました。

まとめ：VSCodeとGitLabの連携は公式拡張で認証しMRとパイプラインをエディタに寄せる

Gitのcommitやpushだけなら、VS Code標準のソース管理機能でGitLabのリポジトリをそのまま扱えます。拡張機能が必要になるのは、MRのレビュー、パイプラインの状態確認、Issueの一覧といった「GitLab側の機能」をブラウザに切り替えずに使いたいときです。入れるのはMarketplace IDがGitLab.gitlab-workflowの公式拡張1本で、2026年11月11日公開の7.6.0系はVS Code 1.106以降に対応します。

認証はコマンドパレットのGitLab: Authenticateで行い、GitLab.comならOAuth、社内GitLabならapiスコープの個人アクセストークンが最短です。社内GitLabで止まる原因の多くは証明書とSSHの別名にあります。MRのレビュー往復とパイプライン待ちが毎日あるチームなら入れる価値があり、GitLabを月に数回しか開かない体制なら標準機能とブラウザで足ります。

VSCodeとGitLabを連携させる2つの層と公式拡張で増える操作の範囲

Git操作はVS Code標準でMRとパイプラインは拡張が担う分担

VS CodeのGit機能はGitコマンドを画面から呼ぶもので、リモートがGitLabでもGitHubでも操作は変わりません。VS Codeのソース管理の公式ドキュメントにあるとおり、clone・commit・push・ブランチ切り替えは拡張なしで完結します。

拡張機能が加えるのは、GitLabのAPIを呼ぶ層です。MRの差分とコメント、パイプラインとジョブ、IssueといったGitの外にあるデータをVS Codeのタブとサイドバーに出します。コミット履歴をグラフで追いたいだけなら、Git Graphの使い方（VS Codeでコミット履歴・ブランチを可視化する拡張機能）のほうが目的に合う選択肢です。GitLab自体の構成やCEとEEの違いを先に押さえたい場合は、GitLabとは（構成要素・CEとEEの違い・3つの提供形態）が前提になります。

拡張機能7.6.0系の対応VS Code版とMarketplace・Open VSX

拡張機能の表示名はGitLab for VS Codeの公式ドキュメントで「GitLab for VS Code」に変わりましたが、IDは旧名時代と同じGitLab.gitlab-workflowです。

項目	2026年11月13日時点の値
最新版	7.6.0（2026-11-11公開）
対応するVS Code	1.106以降
Marketplaceのインストール数	約352万
Open VSXのID	GitLab/gitlab-workflow
ソースコード	GitLab上で公開

版と公開日は拡張機能のリリース一覧で、対応するVS Codeの版はVisual Studio Marketplaceの配布ページで確認しました。7.4.3から7.6.0まで1週間で5回公開されており、画面名は変わりやすい状況です。VSCodiumなどMicrosoftのMarketplaceを使えないエディタでは、Open VSX Registryの配布ページから入れます。

GitLab for VS Codeをインストールして認証を通すまでの作業手順

インストールとGitLab.comでのOAuth・トークン認証の選び方

拡張機能ビューで「GitLab」を検索して入れるか、VS CodeのCLIから次のように入れます。

# 拡張機能をインストールして版を確認する
code --install-extension GitLab.gitlab-workflow
code --list-extensions --show-versions | grep -i gitlab

インストール後、コマンドパレットでGitLab: Authenticateを実行し、インスタンスURLと認証方式を選びます。GitLab.comはOAuthを選べばブラウザで承認するだけで終わります。トークンを使う場合は導入手順の公式ページのとおりapiスコープが必要で、read_apiでは足りません。個人アクセストークンの既定の有効期限は個人アクセストークンの公式ページのとおり作成日から365日です。トークンの種類とスコープの考え方はGitLabのアクセストークン（種類の選び方とスコープ・有効期限の設定）に譲ります。

Self-ManagedでOAuthアプリを登録しClient IDを渡す手順

社内GitLabでOAuthを使えるのは拡張機能6.47.0以降で、GitLab側にVS Code用のアプリケーションを登録しておく必要があります。エディタ拡張の管理者向け設定ページの手順は次の順です。

管理者がインスタンス全体のOAuthアプリケーションを作成する
Redirect URIにvscode://gitlab.gitlab-workflow/authenticationを入れる
スコープはapiだけを選び、Submitする
表示されたApplication IDを利用者に配る
利用者はVS Codeの設定で、インスタンスURLをキー、Application IDを値として登録する

5の設定キーはgitlab.authentication.oauthClientIdsです。Code InsidersやCursorも併用するなら、それぞれのRedirect URIを改行で区切って同じアプリに足します。管理者権限が取れないうちは、トークン認証で始めても支障はありません。

環境変数GITLAB_WORKFLOW_TOKENで渡すDev Container構成

トークンは起動前の環境変数でも渡せます。拡張機能に同じインスタンスのトークンが保存済みなら、そちらが優先です。

# VS Codeを起動する前に設定する（値は社内GitLabのURLと発行したトークン）
export GITLAB_WORKFLOW_INSTANCE_URL=https://gitlab.example.com
export GITLAB_WORKFLOW_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
code .

開発環境をコンテナで配る場合は、.devcontainer/devcontainer.jsonに拡張機能のIDを書いておくと、コンテナを開いた時点で全員に同じ拡張が入ります。

{
  "name": "app",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "customizations": {
    "vscode": {
      "extensions": ["GitLab.gitlab-workflow"]
    }
  }
}

トークンをこのファイルに直書きすると、リポジトリにcommitされて漏えいします。devcontainer.json全体の書き方はVS Codeで開発コンテナを作る手順とdevcontainer.jsonの書き方で扱っています。

git remote -vでリモートとGitLabプロジェクトの対応を確かめる

拡張機能はリモートURLのホストを認証済みアカウントと照合し、パスからプロジェクトを特定します。ここで判定できないと、認証が通ってもサイドバーは空のままです。

git remote -v
# origin  https://gitlab.example.com/group/app.git (fetch)
# origin  https://gitlab.example.com/group/app.git (push)

リモートが無い場合や複数ある場合は、ソース管理ビューのメニューからRemote、Add Remoteへ進み、Add remote from GitLabを選ぶと候補から追加できます。ステータスバーに「(multiple projects)」と出たときは、サイドバーのIssues and merge requestsから対象のプロジェクトを1つ選びます。

VSCodeの中でマージリクエストを作成しレビューしチェックアウトする操作

ステータスバーのCreate MRとブラウザで開く作成画面の関係

ブランチをpushしたあと、ステータスバーのCreate MRか、コマンドパレットのGitLab: Create New Merge Request on Current ProjectでMRを作ります。どちらもブラウザでNew merge request画面を開く動作で、タイトルやレビュアーの入力はブラウザ側です。

作成済みのMRを開くときはGitLab: Open Merge Request for Current Branchを使います。承認ルールやマージ方式の設定は画面側の作業になるので、GitLabのマージリクエストの承認ルールとマージ方式の設定を参照してください。

サイドバーでMRの差分を開き行にスレッドを付けるレビューの流れ

VS Code内で完結するのはレビューのほうです。プロジェクト操作の公式ページに沿うと、手順は4段階です。

左サイドバーのGitLab（タヌキのアイコン）を選ぶ
Issues and merge requestsを開き、プロジェクトを選ぶ
レビューするMRを選び、Overviewで説明とステータスを確認する
変更ファイルを選ぶと、VS Codeのタブに差分が開く

差分の行にはスレッドを作れて、解決と再開、コメントの編集と削除もその場で行えます。コメント欄では/label bugのようなクイックアクションも効きます。差分がエディタのタブで開き、手元のソースと並べて読めるのがブラウザでのレビューとの違いです。

同じプロジェクトのMRを手元にチェックアウトして動作を確かめる手順

実際に動かして確かめたいときは、サイドバーのMRを右クリックしてCheck out Merge Request Branchを選びます。拡張機能のソース（desktop.package.json）では、このコマンドはコマンドパレットに出ず、同じプロジェクト内のMRの右クリックメニューにだけ表示される定義です。フォークから来たMRには出ないので、その場合はgit fetchでフォーク側のブランチを取得します。

gitlab.customQueriesでレビュー待ちのMRだけを並べる設定例

サイドバーの一覧は、既定で「自分に割り当てられたIssue」「自分がレビュアーのMR」など6つの検索条件で作られています。カスタムクエリの公式ページの項目で、運用に合わせて組み替えられます。次はsettings.jsonに書く例です。

{
  "gitlab.customQueries": [
    {
      "name": "レビュー待ち（ドラフト除く）",
      "type": "merge_requests",
      "reviewer": "<current_user>",
      "draft": "no",
      "state": "opened",
      "orderBy": "updated_at",
      "maxResults": 30,
      "noItemText": "レビュー待ちのMRはありません"
    },
    {
      "name": "自分担当の不具合Issue",
      "type": "issues",
      "scope": "assigned_to_me",
      "labels": ["bug"],
      "state": "opened"
    }
  ]
}

この設定は既定の6条件を置き換えるため、既定の一覧も残すなら拡張機能のソースにある既定値を写して並べます。maxResultsの既定は20件で、typeにepicsを指定できるのはPremiumとUltimateに限られます。

パイプラインの状態確認と.gitlab-ci.ymlの検証をVSCodeで回す

ステータスバーからパイプラインの再実行・キャンセル・新規作成を操作する

パイプラインの状態は、ステータスバーにpassed・failed・running・pendingなどの7種類で表示されます。ただしCI/CDパイプライン操作の公式ページが前提条件に挙げるのは、現在のブランチにMRがあり、最新コミットにパイプラインがある状態です。MRを作る前のブランチでは「No pipeline」のままになる場合があります。

表示を選ぶと、次の5つの操作が出ます。

Create New Pipeline from Current Branch
Retry Last Pipeline
Cancel Last Pipeline
Download Artifacts from Latest Pipeline
View Latest Pipeline on GitLab

実務で使う頻度はRetryが群を抜きます。完了時に通知を出したい場合はgitlab.showPipelineUpdateNotificationsをtrueにします（既定はfalse）。

For current branchからジョブログを開き失敗箇所を追う方法

失敗したジョブのログは、サイドバーのGitLabでFor current branchを開き、ジョブを選ぶとVS Codeの新しいタブに表示されます。ダウンストリームパイプラインのジョブも同じ一覧から展開できます。

pendingのまま進まない場合は、ログではなくRunner側の問題であることが多いです。タグの不一致やRunnerの停止を疑う手順はGitLab Runnerのexecutorの選び方と登録手順で確認できます。

GitLabのCI/CD設定を検証しincludeのマージ済み内容を確認する

pushしてから構文エラーに気づく往復は、エディタ上の検証で減らせます。.gitlab-ci.ymlを開いた状態でコマンドパレットからGitLab: Validate GitLab CI/CD Configurationを実行すると、設定に問題がある箇所は拡張機能の警告で確認可能です。includeで別ファイルを読み込んでいる構成では、エディタ右上のShow Merged GitLab CI/CD Configurationを押すと、展開後の内容が.gitlab-ci (Merged).ymlというタブで開きます。

ファイル名が.gitlab-ciで始まり.ymlか.yamlで終わるファイルでは、CI/CD変数名の入力補完も利用可能です。rulesやneedsの書き方そのものはGitLab CI/CDの.gitlab-ci.ymlの書き方とrules・needs・変数の設定例で扱っています。リモートが複数あり、パイプラインを見る先を固定したいときはgitlab.pipelineGitRemoteNameにリモート名を入れます。

社内GitLabで接続できないときの証明書・SSH別名・複数アカウント対処

自己署名証明書はgitlab.caでCAバンドルを指定する設定例

社内CAが発行した証明書を使うGitLabでは、認証の段階で証明書エラーになります。OSの証明書ストアに社内CAが入っていれば、拡張機能6.51.1以降とVS Code 1.101.2以降の組み合わせで、VS Codeのhttp.systemCertificates（既定true）経由で通ります。ストアに入れられない端末での接続方法は、PEM形式のCAバンドルを絶対パスで指定する設定です。

{
  "gitlab.ca": "C:\\certs\\ca-bundle.pem",
  "gitlab.showPipelineUpdateNotifications": true
}

macOSとLinuxでは/etc/ssl/certs/ca-bundle.pemのような形式です。gitlab.ignoreCertificateErrorsで検証を止める設定も残っていますが、証明書設定の公式ページは検証の無効化をセキュリティ上のリスクと明記しています。トラブルシューティングの公式ページでも、サポート対象はgitlab.caだけで、gitlab.cert・gitlab.certKey・gitlab.ignoreCertificateErrorsは非サポートとされています。本番の端末では使わない設定と考えてください。

SSHのHost別名でプロジェクトを検出できない場合の直し方

~/.ssh/configにHost別名を定義し、リモートURLのホスト部分に別名を書いている場合、拡張機能はホストを認証済みアカウントと照合できません。仕事用と個人用のアカウントを別名で分けている環境で起きやすく、対処は手軽な順に次の3通りです。

サイドバーの(no GitLab project)からManually assign GitLab projectで手動で割り当てる
リモートURLを、別名を使わない実ホスト名のSSH形式に直す
リモートURLをHTTPS形式に切り替える

HTTPSへ切り替える場合のコマンドは次のとおりです。

git remote set-url origin https://gitlab.example.com/group/app.git
git remote -v

Git操作をSSHのまま続けたいなら、1つ目の手動割り当てがリポジトリ側の設定を変えずに済みます。

GitLab: Diagnosticsと拡張機能ログで原因を切り分ける順番

原因が分からないときは、最初にコマンドパレットでGitLab: Diagnosticsを実行し、失敗した確認項目を見ます。次にGitLab: Validate GitLab Accountsで確かめるのは、保存済みトークンが現在も有効かどうかです。それでも分からなければ、設定のgitlab.debugをtrueにしてDeveloper: Reload Windowで再読み込みし、出力パネルのGitLabとGitLab Language Serverのログを読みます。

認証付きプロキシで「407 Access Denied」が出る場合は、GitLab Language Server側でプロキシ認証を有効にします。複数アカウントをワークスペースごとに使い分けるにはGitLab: Select Account for this Workspaceを使います。

VSCodeとGitLabの拡張機能を入れるチームと見送るチームの判断

MRのレビュー往復とパイプライン待ちが毎日あるチームは入れる

拡張機能の効果は、ブラウザとエディタの往復回数に比例します。1日に数件以上のMRをレビューし、pushのたびにパイプラインの結果を待つチームなら、差分をエディタで読めることとRetryをステータスバーから押せることだけで導入の手間を回収できます。

MRやIssueをAIエージェントから扱いたい場合は、拡張機能ではなくGitLab MCPサーバーの接続設定とツール一覧の方法でつなぎます。

証明書検証を止めないと社内GitLabに接続できない環境では導入を見送る

見送るべきなのは、gitlab.ignoreCertificateErrorsをtrueにしないと接続できない環境です。公式が非サポートとしている設定に頼ると、拡張機能の更新で突然つながらなくなっても直す手段がありません。社内CAのバンドルを配れるまでは、ブラウザでのレビューに留めるほうが安全です。

GitLabを月に数回しか開かない担当者も、画面名の変化を追う手間のほうが大きくなるので入れなくて構いません。

エディタ統合より先に遅延や失敗の多いパイプライン設計を直すべきパターン

よくある失敗は、パイプラインが遅い・頻繁に落ちる状態のまま拡張機能を入れ、Retryを押す回数が増えるだけで終わるケースです。1回の実行に20分かかる、同じテストが不定期に落ちる、といった症状は、ジョブの並列化やキャッシュ、rulesによる実行条件の絞り込みで直す問題です。

構成やRunnerの配置から見直すなら、設計段階から外部に相談する選択肢もあります。一創のDevOps・CI/CD導入支援では、既存のGitLab CI/CDの診断から改善までを受託しています。

よくある質問

VS CodeとGitLabの連携を始める段階で出やすい質問を5つ取り上げます。

GitLab WorkflowとGitLab for VS Codeは別の拡張機能ですか？

同じ拡張機能です。表示名が変わっただけで、MarketplaceのIDはGitLab.gitlab-workflowのままです。古い記事の「GitLab Workflowを入れる」は現行版を入れる操作と読み替えられますが、画面名やコマンド名は版ごとに変わっています。

クローンせずにGitLabのリポジトリをVS Codeで見られますか？

読み取り専用であれば可能です。コマンドパレットでGitLab: Open Remote Repositoryを実行し、プロジェクトとブランチを選ぶと、クローンなしでファイルを閲覧できます。URLで指定する場合はリモートURLの公式ページにあるgitlab-remote://形式を使います。編集やcommitはできません。

CursorやVSCodiumでもGitLab for VS Codeは使えますか？

VSCodiumのようにOpen VSX Registryを使うエディタでは、GitLab/gitlab-workflowとして入れられます。社内GitLabでOAuthを使うなら、管理者が登録したOAuthアプリのRedirect URIに、そのエディタ用のURIを改行区切りで追加しておく必要があります。トークン認証であれば、追加の登録は要りません。

アクセストークンの期限が切れたらどう再設定しますか？

新しいトークンを発行し、コマンドパレットのGitLab: Authenticateで登録し直します。古いアカウント情報が残って混乱する場合は、先にGitLab: Remove Account from VS Codeで削除してください。個人アクセストークンの既定の期限は365日なので、発行日を手元に記録しておくと切れる前に気づけます。