古いバージョンのGitLabでGitLab Workflowを使う方法

はじめに

　GitLab上でチーム開発をするにあたり、GitLab Workflowという便利なVSCode拡張機能があります。GitLabのIssueやMerge Request(以下MR)をVSCode上で確認できるようにする拡張機能なのですが、GitLab自体のバージョンが古いと動かないことがあります。
　今回の記事では、GitLabのバージョンが古くてもGitLab Workflowを使えるようにするためのトラブルシューティングをご紹介します。

前置き：GitLab Workflowを使うメリット

　IssueやMRはGitLabのWeb IDE上でも確認できますが、このWeb IDEが正直あまり使い心地が良くありません。個人的には、以下の点が微妙に感じています。

• インデントの差が分かりにくい(HTMLが特に読みづらい)
• 他のファイルを参照したくなった場合に、検索速度が遅すぎる

　GitLab Workflowを導入すると、使い慣れたVSCodeのdiffエディタでコミット内容を確認できるようになり、上記のような不便さがなくなるのでお勧めです。私自身、GitLab Workflowを導入してMRのレビューをしていますが、Web IDEでレビューしていた時と比べて明らかに体験が良いです。

※ApproveやMergeはGitLab上でしか実施できません。あくまでDescriptionやdiffの確認のみVSCode上で可能になります。

GitLabのバージョンとGitLab Workflowについて

　GitLabは、(GitHubと異なり)自社サーバにインストールして利用するケースがあることから、GitLabのバージョンが更新されないまま運用されているケースがあると思います。
　また、GitLab Workflowは、2018年のリリースから現在(2025年10月)に至るまでこまめにアップデートが続けられており、拡張機能側が要求するGitLabのバージョンも年々上がってきています。
　そのため、GitLab WorkflowをVSCodeにインストールしても、GitLabのバージョンが古く拡張機能側で弾かれてしまうことがあります。
　GitLabのバージョンを上げられるのであればよいですが、そうもいかない場合もあると思います。その場合の対処方法が以下になります。

古いバージョンのGitLabとGitLab Workflowを連携する方法

結論：古いバージョンのGitLabには、古いバージョンのGitLab Workflowを使用する。

以下の手順で、インストールから連携まで完了します。

1. VSCodeにGitLab Workflowをインストールする

2. GitLabとGitLab Workflowを連携する
   　GitLab Workflowのバージョンによって文言に違いはありますが、
   「GitLab上でアクセストークンを発行」→「アクセストークンをVSCode上で登録」
   という大まかな流れは変わりありません。
   以下、一例です。

   1. GitLabのUser Settings > Access Tokensページで、NameとExpires atを指定し、Scopesにapiとread_userを設定します。
   2. Create personal access tokenをクリックし、発行されたアクセストークンをコピーします。
   3. VSCodeの拡張機能タブでGitLab Workflowを開き、Add Accountボタンをクリックします。
   4. GitLabのドメイン入力を求められます。末尾に/が入っていると失敗するので注意してください。
   5. アクセストークンの入力を求められるので、先ほどコピーしたものをペーストします。

3. エラーが出なければ連携完了です。以下のエラーが出ている場合はGitLabのバージョンが古いので、次の手順に進みます。

   This extension requires GitLab version XX.X.X or later, but you're using YY.Y.Y.
   Source: GitLab Workflow

4. GitLabのバージョンに応じて、GitLab Workflowのバージョンを下げる
   　VSCodeの拡張機能タブからGitLab Workflowを開き、歯車マークをクリック→特定のバージョンをインストール...をクリックします。
   

   　するとインストールできるバージョンの一覧が表示されるので、利用しているGitLabのバージョンをサポートしている拡張機能のバージョンを選択してインストールします。
   

   　GitLab WorkflowのどのバージョンがどのGitLabのバージョンをサポートしているのかについてですが、おそらく一覧でまとまっているものは無いと思います。
   　なので、私はそのGitLabと同じころにリリースされたGitLab Workflowのバージョンをインストールしています。GitLab Workflowのバージョンは、割と適当に選んでも大差無いのではないかと思います。(最低限、セキュリティ的な懸念が無いことは見ておくとよいと思います)
   

   • GitLab Workflowの各バージョンのリリース日は、拡張機能ページの「変更ログ」タブで確認できます。
     
   • GitLabの各バージョンのリリース日は、公式で一覧になっているものは恐らく無いので、バージョン名で検索する方が速いと思います。

5. 以上で連携が完了です。VSCodeの拡張機能タブから、IssueやMRを確認できるようになります。