GitLabの基礎

バージョン管理は、ファイルの変更を「いつ、誰が、何のために」と一緒に残す仕組みです。

できること	無いと困ること
前の状態に戻せる	壊した後に、どこまで戻せば動くのか分からない
何人かで同じファイルを並行して直せる	上書きし合って、誰かの直しが消える
変更の理由が残る	半年後に「なぜこの1行があるのか」を誰も説明できない
レビューしてから本線に入れられる	確かめていない変更が、そのまま本番の元になる

Gitは、この履歴を自分のPCの中に持つ道具です。GitLabは、その履歴をチームで共有する置き場に、Issue(やること)、MR(変更の提案とレビュー)、CI/CD(自動の検査と実行)を一緒にしたものです。

今日の研修では、手元のGitの操作をClaude Desktopに頼み、GitLabの画面は受講者が自分で操作します。分担と頼み方は、下の「Gitの操作とClaude Desktop」にまとめています。

GitHub	GitLab	中身
repository	project	コードと履歴の置き場
Organization	Group	projectをまとめる単位。下にサブグループも作れる
Pull Request(PR)	Merge Request(MR)	変更を本線に入れる提案。差分、議論、レビュー、パイプラインの結果が1か所に集まる
Actions(.github/workflows/*.yml)	CI/CD(ルートの.gitlab-ci.yml)	pushやMRのたびに自動で動く検査と処理
runner	GitLab Runner	ジョブを実際に動かす機械。自社のサーバーに置ける
Secrets	CI/CD variables	APIキーなどの秘密。ジョブのログでは伏せ字になる(masked)
Projectsのボード	Issue boards	ラベルを列にしてIssueを並べる

研修のGitLabはCommunity Edition(無料版)です。AIと一緒に開発する体制に要る機能の多くは入っていますが、承認の強制やAIの機能は有料版にあります。

機能	CE	研修での代わり
保護ブランチ(mainに直接pushさせない)	ある	そのまま使う
パイプラインが通らないとマージできない	ある	そのまま使う
MRのパイプライン、条件で動かすジョブ(rules)	ある	そのまま使う
スケジュールでパイプラインを動かす	ある	AIの実装サイクルに使う
CI/CD変数(masked)、プロジェクトのアクセストークン	ある	AI用のトークンをDeveloperに絞って使う
Issueのラベルとボード、Closes #番号で閉じる	ある	そのまま使う
承認が何人要るかの強制、CODEOWNERS	無い(Premium以上)	マージできる人をMaintainerに絞る
push rules(ブランチ名やコミットの決まりの強制)	無い(Premium以上)	パイプラインのジョブで確かめる(レベル3)
スコープ付きラベル(ai::のように同じキーのラベルを1つに限る)	無い(Premium以上)	普通のラベルとして並べて付け、状態の付け外しはスクリプトが行う
GitLab Duo(GitLabの中のAI)	無い(Premium以上)	Claude CodeをCIのジョブで動かす

機能	今日の使い方
Issue	やることと受け入れ条件を書く。人とAIが同じ文を読む
ラベルとボード	Issueに付ける印と、印を列にした一覧。研修ではai::approvedでAIに渡すことを承認し、AIの進み具合もラベルで表す
MR	差分、パイプライン、AIレビューを見て、人がマージを決める場所
パイプライン	pushとMRのたびに、構文、ルール、テスト、AIレビューを動かす
保護ブランチとマージの条件	mainに直接入れさせない。パイプラインが緑でないとマージできない
CI/CD変数	APIキーとAI用のトークンを、リポジトリに書かずに渡す
スケジュール	決まった時刻にパイプラインを動かす。研修ではAIの実装サイクルに使う
Runner	ジョブを自分たちで用意したサーバーで動かす(研修では研修用のサーバー)。コードが外に出るのは、AIに渡す分(AnthropicのAPI)だけ

研修のGitLab(19.3.1)では、Issueは左のメニューのPlan → Work itemsに並びます。新しく作るボタンもNew itemです。

今日のGitの操作は、最初のcloneと、プチ演習7〜9で止め金を外す操作を除いて、受講者がClaude Desktopに頼みます。Claudeが手元のPCでコマンドを打ち、受講者は確認のダイアログに出たコマンドを読んで、許可するかを決めます。

操作	何をする	いつする	今日のやり方
git clone	GitLabのリポジトリを、手元にまるごと写す	最初に1回	受講者がPowerShellで打つ(ガイドのStep 2)
git fetch	GitLabの最新を取ってくるだけ。作業中のファイルは変わらない	GitLabで作ったブランチに切り替える前。人の変更を見たいとき	Claude Desktopに頼む
git switch ブランチ名	作業するブランチを切り替える	Issueの作業を始める前	Claude Desktopに頼む
git addとgit commit	次のコミットに入れる変更を選び、手元の履歴に区切りを1つ残す。まだ自分のPCの中だけ	テストが通る単位で1歩進んだとき	実装を頼む文に「コミットまで」と書く
git push	手元のコミットをGitLabのブランチに送る。パイプラインが動く	MRで見せたい所まで来たとき。席を離れる前	Claude Desktopに頼み、ダイアログで一度だけ許可する
git pull	fetchしたうえで、今のブランチに取り込む	mainを最新にするとき	Claude Desktopに頼む
マージ(MRの画面)	ブランチの変更をmainに入れる	パイプラインが緑で、人が読んで決めたとき	講師がMRの画面で押す

• 1つのIssueに1つのブランチ、1つのMR
• ブランチはIssueの画面のCreate merge requestで作る。名前はIssue番号から始まり、題の日本語は落ちて英数字だけが残る(例29-fmt_money-8)。MRとIssueは自動でつながる
• 作業中のMRはDraftにしておく。DraftのMRはマージできない
• AIが作るブランチはai/issue-番号-… の形で、人のブランチと名前で見分けられる
• mainには直接pushできない(保護ブランチ)。mainに入るのは、マージだけ

受講者が触るのは、GitLabの画面とClaude Desktopの2つです。Issue、ラベル、MRは、受講者がGitLabの画面で操作します。手元のファイルとGitの操作は、Claude Desktopに頼みます。

作業	誰が、どこで
Issueを読み、自分の担当にする	受講者がGitLabの画面で
Create merge requestで、ブランチとMRを作る	受講者がGitLabの画面で
ブランチを切り替え、実装し、テストを流し、コミットする	Claude Desktopに頼む。受講者はダイアログで許可するかを決める
pushする	Claude Desktopに頼む。受講者はダイアログでブランチ名を確かめる
パイプラインの結果を見る	受講者がMRの画面のPipelinesタブで。赤なら、ログをClaude Desktopに貼って直させる
ラベルai::approvedを付けて、AIのサイクルに任せる	受講者がGitLabの画面で。承認は人の判断なので、Claudeには頼まない
Draftを外し、講師にマージを頼む	受講者がGitLabの画面で
マージ	講師がGitLabの画面で。受講者はDeveloperなので、マージのボタンが出ない
手元の検査を飛ばす、フックの本体の名前を変える、計画書の承認を記録する	受講者がClaude Desktopの統合ターミナルで打つ(プチ演習7〜9)。止め金を外す操作と人の承認は、Claudeに頼まない

午後のAIのサイクルで動くClaudeは、手元のClaude Desktopとは別のものです。違いは、本Projectの仕組みの「手元のClaudeとサイクルのClaude」に並べています。

Claude Desktopには、入力欄に日本語の文を送って頼みます。ハンズオンガイドの送る文は、そのまま貼れるように書いてあります。

したいこと	送る文
GitLabで作ったブランチに切り替える	git fetch してから、ブランチ 番号-… に切り替えてください。切り替えたら、今のブランチ名を教えてください。
Issueを実装して、コミットまで進める	GitLab の Issue #番号 を実装してください。本文は次のとおりです。 (ここに Issue の本文を貼る) 受け入れ条件を満たしたら、コミットまでしてください。push はまだしないでください。
手元の履歴を確かめる	git log --oneline -3 と git status を見せてください。
GitLabに送る	push してください。
パイプラインの赤を直す	ジョブのログの最後の数行を貼り、「このエラーを直して、コミットしてください」と送る。直ったら「pushしてください」と送る

• 1つの文で頼むのは1つの目的にする。コミットとpushは、必ず別の文で頼む
• ブランチ名とIssue番号を文に書く。終わったら今のブランチ名やgit logを見せてもらい、自分の目で確かめる
• Issueの本文は貼って渡す。研修のGitLabはログインしないと開けないので、手元のClaudeはIssueの画面を読めない
• 確認のダイアログは、コマンドやファイルの中身を読んでから「一度だけ許可」を押す。「常に許可」は押さない
• 権限のモードは「手動」、モデルはOpus 5.5にする。送る前に、入力欄の下の行で確かめる
• 「mainのままで構いません。」と「講師の判断で今回だけ許可します。」は、プチ演習の送る文だけに使う。CLAUDE.mdの約束を、その1回だけ外す文だから

/hooks、/permissions、/configは、Claude Desktopの入力欄では使えません。設定を見るときは、.claude/settings.jsonをVSCodeで開いて読みます。戻すときの/rewindは使えますが、戻るのはEditとWriteで変えたファイルだけです。シェルのコマンドで変えたファイルは戻らず、Escを2回押す戻し方もClaude Desktopでは効きません。

頼んだ操作がそのまま動くか、ダイアログが出るか、止まるかは、研修リポジトリの設定とフックで決めてあります。一覧は本Projectの仕組みの「Claude Desktopに頼んだ操作の行き先」にあります。

パイプラインは、段(stage)の順に、ジョブ(job)を動かします。同じ段のジョブは並んで動き、前の段が赤なら次の段は動きません。

研修のパイプラインに並ぶ段とジョブは、本Projectの仕組みの「パイプラインの3種類」にあります。

きっかけ	変数CI_PIPELINE_SOURCEの値
ブランチへのpush	push
MRの作成と、MRがあるブランチへのpush	merge_request_event
スケジュール	schedule
画面のNew pipeline	web

どのジョブをどのきっかけで動かすかは、ジョブのrulesに書きます。パイプライン全体を走らせるかどうかは、.gitlab-ci.ymlのworkflow:rulesで決めます。何も決めていないと、MRがあるブランチへのpushでブランチ用とMR用の2本が走る仕組みです。「パイプラインが通らないとマージできない」はMR用の1本しか見ないので、ブランチ用で赤のテストがあってもマージできてしまいます。研修リポジトリの決め方は、本Projectの仕組みの「パイプラインの3種類」にあります。

同じブランチに続けてpushしたとき、前のパイプラインを途中で止める設定が、ジョブのinterruptible: trueです。止まったパイプラインは、取り消し(canceled)と表示されます。最後にpushしたものだけが最後まで走るので、Runnerの順番待ちが積み上がらない仕組みです。

ジョブの名前を押すと、ログが開きます。赤のときは、下の方に何行目の何が悪いかが出ています。

用語	意味
Issue	やることを書いたチケット。受け入れ条件を書く
MR(Merge Request)	ブランチの変更をmainに入れる提案
Draft	作業中のMR。マージできない
パイプライン	pushやMRのたびに自動で動く、ジョブのまとまり
ジョブ	パイプラインの中の1つの処理
Runner	ジョブを動かす機械
保護ブランチ	直接pushできないブランチ。研修ではmain
MaintainerとDeveloper	プロジェクトでの役割。受講者はDeveloperで、マージはMaintainer(講師)
フック(Claude Code)	Claudeがツールを使う前や後に動く検査。使う前のフックは終了コード2で止め、使った後のフックは結果をClaudeに返して直させる
フック(git)	コミットやpushの前に手元で動く検査。--no-verifyで飛ばせる
Claude Desktop	受講者のPCで動くClaudeのアプリ。今日はCodeの画面で、手元のリポジトリを読み書きさせ、Gitの操作を頼む
権限のモード	Claudeがファイルを書き換える前やコマンドを打つ前に、人に聞くかどうかの設定。今日は「手動」で、毎回聞く
確認のダイアログ	Claudeが許可の要る操作をする前に出る画面。コマンドや書き換えの中身を読み、「一度だけ許可」か「拒否」を選ぶ
claude -p	画面を使わずにClaude Codeを動かす呼び方。AIのサイクルは、パイプラインの中でこれを使う