Content last updated 2026-06-04

GitLab におけるハンドブックの使い方

GitLab がハンドブックをどのように使っているかについて。

運用の流れ

(プロセス上の) 問題が発生します。多くの場合、Issue やチャットで浮上します。
ハンドブックへのマージリクエストという形で提案を作成します。
マージされたら、MR またはコミットの差分へのリンクを添えて変更を周知します。重大なものは #whats-happening-at-gitlab Slack チャンネルに投稿します。中程度のものは可視性を高めるため #handbook チャンネルに、変更の一行要約を添えて投稿します。元になった Issue があれば、差分へのリンクを残してクローズします。

ミーティング中に提案をリアルタイムで編集したい場合があり、その際は Google Doc を使う必要があります。その場合、Google Doc の最初の項目には、ミーティング終了後に内容を移動するハンドブックページの URL を記載してください。

なぜハンドブックファーストなのか

アクションを起こす前にハンドブックに文書化することは、最初は時間がかかるかもしれません。なぜなら、どこに変更を加えるかを考え、既存のコンテンツと統合し、そして場合によっては適切な基盤を持たせるためにハンドブックに追記したりリファクタリングしたりする必要があるからです。しかし、長い目で見れば時間を節約でき、このコミュニケーションは、私たちが組織をスケールさせ適応させ続ける能力にとって不可欠です。

このプロセスは、ソフトウェアのテストを書くことに似ています。(提案された) 変更は、ハンドブックの変更を通じてのみ伝えてください。プレゼンテーション、メール、チャットメッセージ、その他の媒体を使って変更の構成要素を伝えないでください。これら他の形式のコミュニケーションは、発表者にとっては便利かもしれませんが、聞き手が文脈や、影響を受けうる他のプロセスへの含意を理解することを難しくします。

「ハンドブックファースト」 のメンタリティを持つことで、重複が生じず、ハンドブックは常に最新の状態に保たれ、他の人がより貢献しやすくなります。

私たちは「ハンドブックファースト」であるだけでなく、「パブリックハンドブックファースト」でもあります。情報が社内限定のものである場合は、内部ハンドブックに記録すべきですが、公開できるものについてはデフォルトでパブリックハンドブックに記載します。これにより、SAFE に共有できるあらゆる情報に誰もがアクセスできるようになります。これは、透明性、効率性、結果を含む GitLab のバリューを支えます。また、本来公開すべき情報の置き場所として内部ハンドブックが使われたり、矛盾する、あるいは重複する信頼できる情報源になったりすることを防ぎます。

INSEAD のケーススタディインタビュー（上記参照）でオールリモートであることに関連する課題について尋ねられたとき、GitLab の共同創業者である Sid Sijbrandij は次のように答えました。

最大の問題は、GitLab がハンドブックファーストで動かないことです。私たちには、協働し、新しいメンバーをオンボーディングし、集団で考えることを可能にする素晴らしいハンドブックがあります。
しかし、変更をハンドブックに伝えるのは直感に反します。変更を伝えたいとき、人々のデフォルトは、Slack メッセージを送る、メールを送る、プレゼンテーションを行う、ミーティングで人に話す ── ハンドブックに変更を加えること以外の あらゆること です。
その方が彼らにとっては遅いのです。他のどんな形式を使う方が速いのです。ハンドブックに変更を加えるなら、まずハンドブックの関連部分を見つけなければならず、自分の変更が収まるようにハンドブックを調整しなければならないこともあり、技術的なプロセスと 1 〜 2 回のレビューを経なければならず、デプロイされるまで少し待たなければなりません。
それは他のどの選択肢よりも遅いのです。しかし、それによって、その後に変更をコミットする人々がその変更の上に積み上げられるようになります。その余分な時間をかけるとき、それは次のものへの基盤を築いているのです。
私はそれをレンガ積みのように捉えています。あらゆる情報の断片はレンガです。GitLab には、よく構造化された家が 1 つあり、誰もがその 1 つの家に積み上げていきます。私たちはどう積むかにかなりこだわっているので、強固な基盤を持ち、非常に高く積み上げることができます。
他のすべての会社では、レンガを人々の手に投げ込みます。誰もが日々レンガを受け取り、それを自分が社内で築いている家に加えなければなりません。彼らは物事を忘れ、物事は不明確になります。レンガをどこに置くかについての文脈がないため、多くの文脈を作り出さなければなりません。
その結果、見た目がかなり異なり、どれも少し傾いていて、上にレンガを 1 つ加えるたびに下から 1 つ飛び出すような、千の家ができあがるのです。 — GitLab 共同創業者 Sid Sijbrandij

このハンドブックの範囲

ハンドブックは、GitLab のチームメンバーが仕事をするために必要なあらゆるコンテンツに焦点を当てています。役立つかもしれない他のコンテンツについては、その情報源にリンクしてください。

より広いコミュニティからのコード貢献にも当てはまるドキュメントはすべて、ハンドブックではなく GitLab プロジェクト内（例えば Contributing やコードレビューガイドライン）に置くべきです。ハンドブックはチームメンバー専用です。
ユーザー向けの企業情報については、メインのマーケティングウェブサイトとブログがあります。
ハンドブックは、現在および将来の GitLab チームメンバーに関わる事項のみを対象とします。GitLab のユーザーに関わる事項であれば、GitLab ドキュメント、GitLab Development Kit (GDK)、CONTRIBUTING ファイル、または PROCESS ファイルに文書化すべきです。

ハンドブックのガイドライン

これらのガイドラインに従い、他の人にも思い出させてください。

日常的なガイドの使い方

このハンドブックのほとんどのガイドラインは助けになることを意図しており、特に明記されていない限り、絶対的なルールというよりは助けとなることを意図しています。ハンドブック全体を知らないからといって何かをするのを恐れないでください。誰もハンドブック全体を知りません。これらのガイドラインについて人に思い出させるときは、穏やかにしてください。例えば、「問題ではないのですが、次回はハンドブックの次のガイドラインを検討してみてください」と言いましょう。
質問をして誰かがハンドブックへのリンクで答えた場合、それはより多くの情報を提供して助けたいからです。また、答えが文書化されていることを誇りに思っているのかもしれません。それは、あなたがハンドブック全体を読んでおくべきだったという意味ではありません。誰もハンドブック全体を知りません。
チームメンバーに助けを求める必要がある場合は、コミュニティの大多数も答えを知らない可能性が高いことを認識してください。この情報をコミュニティ全体に広めるために、必ず答えを 文書化 してください。質問が回答された後、それをどこに文書化すべきか、誰がやるかを話し合いましょう。「これは誰が文書化しますか?」と尋ねることで、他の人にこの依頼を思い出させることができます。
チャットで何かを議論するときは、関連する場合は常に URL に リンク するようにしましょう。例えば、質問のあるドキュメントや、あなたの質問に答えたページです。「リンクしてもらえますか?」と尋ねることで、他の人にこれを思い出させることができます。
覚えておいてください、ハンドブックは私たちがやりたいと願っていること、形式上やるべきこと、数ヶ月前にやったことではありません。それは私たちが今この瞬間にやっていることです。 本当にプロセスを変えるためには、必ずハンドブックを変更してください。プロセスの変更を提案するには、ハンドブックを変更するマージリクエストを作成します。ハンドブックの変更を提案するのに別のチャンネル（メール、Google Doc など）を使わないでください。
ハンドブックがプロセスです。「process」「policies」「best practices」「standard operating procedures」といった名前のセクションは、より深い問題の兆候です。これは、あるプロセスについての散文的な説明と、同じプロセスについての番号付きリストの説明とが重複していて、1 つのプロセスの説明にまとめるべきであることを示しているかもしれません。
何かを伝えるときは、テキストをメール/チャット等に含める代わりに、常に ハンドブック の関連する（かつ最新の）部分へのリンクを含めてください。「ハンドブックの関連部分にリンクしてもらえますか?」と尋ねることで、他の人にこれを思い出させることができます。
ハンドブックの変更を把握しておくために、誰でも #handbook チャンネルに参加できます。

プレゼンテーションを作るのではなく、ハンドブックをスクリーンショットする

プレゼンテーションは、取締役会向けプレゼンのような一時的なコンテンツには最適です。リーダーシップトレーニングのようなエバーグリーンコンテンツは、ハンドブックに基づくべきです。これはハンドブックファーストで働くことの重要な要素です。

エバーグリーンコンテンツ向けのプレゼンテーションを作成する際は、コンテンツをコピー＆ペーストする（あるいはハンドブックの情報をそのまま映すようにスライドを整形する）のではなく、ハンドブックのスクリーンショットを撮り、表示しているページへのリンクを提供してください。このアプローチは非同期コミュニケーションを優先する姿勢を示すものであり、その根拠は以下のとおりです。

ハンドブックの更新とプレゼンテーション用コンテンツの作成の両方を行う手間が省けます。準備の一環としてハンドブックがチェックされ改善されるので、余分な作業になりません
ハンドブックは最新の状態に保たれるので、人々がプレゼンテーション内の古い情報を見ることがなくなります
スクリーンショットを見ることで、そのコンテンツがハンドブックにあり、そこで最新であることを人々に確認してもらえます
人々がハンドブックの構造に慣れ、後で関連するハンドブックのセクションをより簡単に見つけられるようになります
コンテンツがハンドブックにあると、誰もが貢献できるよう開かれた状態になります
コンテンツが私たちの他のプロセスと統合され、文脈の中で示されます
ウェブページの方が検索やリンクが容易なため、プレゼンテーションよりも多くの人がそのコンテンツを利用します
私たちがどうやっているかの例を示すことで、世界中の他の組織や学生を助けることになります
私たちのハンドブックを使うことの利点のいくつかも参照してください

プレゼンテーションの見た目は洗練されていないものになりますが、利点がその懸念を上回ります。

同期的なプレゼンテーションが必要な場合は、スライドプレゼンテーションよりも、画面を共有してライブのハンドブックページを見せることをデフォルトにしてください。

ハンドブックを検索する

すべての GitLab ハンドブックページには、ページ上部付近に検索用の検索フィールドがあります。ハンドブックをより速く効率的に検索するためのヒントについては、プロのように GitLab を検索するページを参照してください。

プロセスを変更または定義する方法

ガイドラインやプロセスを変更するには、マージリクエストの形で 編集を提案 してください。
変更を迅速にマージしてもらうには、マージ権限を持つ適切なチームメンバーに依頼していることを確認してください。誰が責任者か分からない場合は、関連するプロジェクトの CODEOWNERS ファイルを参照（し、追記）してください。
- 例えば、CMO（Chief Marketing Officer）スタッフメンバーは自分の職能に固有のマージリクエストを承認でき、CMO はマーケティング横断的なマージリクエストを承認します。Chief of Staff to the CEO/CEO は、GitLab のバリューページのような全社横断的な影響を持つマージリクエストを承認します。
マージ後、該当する場合は #whats-happening-at-gitlab Slack チャンネルにこれを投稿できます。「ハンドブックのマージリクエストを送ってもらえますか?」と尋ねることで、他の人にこれを思い出させることができます。
ハンドブックのレイアウトを大幅に変更する場合は、この MR が直接影響を与える レビューアプリの該当ページへのリンクを残してください。リンクとともに、MR の説明にできるだけ多くの情報を含めてください。これにより、差分を見なくても MR の目的を誰もが理解できるようになります。
ハンドブックの変更を把握し続けるのは難しい場合があります。誰かが MR の内容をすばやく理解できるよう、特にマージリクエストのタイトルに重点を置いてコミットの件名のガイドラインに従ってください。
プロセスの変更は、マージされた差分（変更前後を示すコミット）へのリンクで伝えてください。議論やフィードバックを目的として変更を伝える場合は、マージされていない差分 にリンクしても構いません。先にプロセスを変更してから、ドキュメントを優先度の低いタスクとして扱わないでください。後でドキュメント化しようと計画すると、必ず変更を伝える作業が重複し、ドキュメントが古くなってしまいます。「先にハンドブックを更新してもらえますか?」と尋ねることで、他の人にこれを思い出させることができます。
可能な場合は、プロセスの変更をイテレーティブに導入してください。小さなマージリクエストを作成することでハンドブックに貢献することが重要です。これにより、そのプロセスの対象オーディエンスの間で採用が進みやすくなります。不必要に大きく、トップダウンで、破壊的なプロセス変更は避けたいのです。こうした種類のプロセス変更は、DRI の権限を奪い、人々を結果ではなくプロセスに集中させてしまう可能性があります。
他のすべてのものと同様に、私たちのプロセスは常に流動的です。すべては常にドラフトであり、最初のバージョンもハンドブックにあるべきです。ハンドブックへの変更を提案する場合は、可能な限り Issue を飛ばしてマージリクエストを提出してください。（Issue の説明よりも、マージリクエストでの変更提案が望ましいです）。変更によって影響を受ける人々をマージリクエストでメンションしてください。多くの場合、提案された変更を見られるため、マージリクエストの方が協働しやすいです。
何かが一部のユーザーグループ向けの限定的なテストである場合、それをハンドブックに追加し、その旨を注記してください。そして、テストが終わったら注記を削除し、すべてのケースで新しいプロセスを使うようにします。
GitLab の内外を問わず、誰かが良い提案をしたら、それをハンドブックに追加するよう招いてください。その人に該当するページとセクションの URL を送り、もし彼らができないなら代わりにやってあげると申し出てください。彼ら自身に提案を作成して送ってもらうことで、変更が実現し、彼らの知識が反映されます。
マージリクエストを提出するときは、それがすばやくマージされるようにしてください。単一の小さな変更をすばやく行うことで、あなたのブランチが master から大きく遅れてマージコンフリクトを起こすのを防げます。更新を同日中に作成しマージすることを目指してください。マージリクエストで人々をメンションするか、Slack で連絡してください。既存のものに加えて大きな改善の提案をもらった場合は、それを別途行うことを検討してください。Issue を作成し、既存の MR をマージしてもらってから、新しいマージリクエストを作成します。
コンテンツを移動しなければならない場合は、それを移動するだけで他には何もしないマージリクエストにしてください。整理したり、要約したり、拡張したりしたい場合は、移動の MR がマージされた後に行ってください。この方がレビューがずっと簡単です。
ハンドブックのプロセスの「なぜ」を追加する よう心がけてください。ビジネス上の目標は何か、このセクションのきっかけは何かを記しましょう。「なぜ」を追加することで、「なぜ」が変わったかどうかを評価できるため、将来プロセスを変更しやすくなります。
エンジニアリングワークフローでプロセスを追加または変更する際は、X ヶ月後にレトロを予定することを検討してください。レトロは、新しいプロセスの影響を検討し、さらなるイテレーションが必要か、それとも削除できるかを判断する機会です。

プロセスを追加する際の考慮事項

必須ではありませんが、新しいプロセスの導入後 X ヶ月先に非同期のレトロ MR/issue を予定すると役立ちます。

何が成功なのかを判断するために、改善目標と期間を特定することを検討してください。レトロ MR/issue を使って期待を透明性をもって伝えるとともに、新しいプロセスをイテレーションしたり削除したりする手段を提供できます。

レトロ MR/issue の作成は、次のことをじっくり考える機会です:

この新しいプロセスで何を達成したいと願っているか?
新しいプロセスの効果を測定するために使える指標はあるか?
新しいプロセスのうち、ロールバックを促すような結果はあるか?

レトロそのものは、次のことを文書化する機会です:

プロセスの参加者は、物事がどう進んでいると考えているか?
新しいプロセスにはどんな追加コストが伴うか?
新しいプロセスに予期しない副作用はあったか?
参加者は、新しいプロセスで生じたコストを軽減する方法や、より一般的な改善について提案を持っているか?

情報アーキテクチャ

単一の情報源 (Single Source of Truth)

情報アーキテクチャについて考え、繰り返しをなくし、信頼できる唯一の情報源 (SSoT) を持つようにしましょう。コンテンツを繰り返す代わりに、相互リンクしてください（各テキストが他方の断片へのハイパーリンクを持つ）。コンテンツをコピーする場合は、元の場所からは削除し、新しいコンテンツへのリンクに置き換えてください。重複したコンテンツは、複数の場所でコンテンツを更新しなければならない上、古いコンテンツがすべてどこにあるかを覚えておく必要があるため、より多くの作業につながります。信頼できる唯一の情報源があれば、それは単一のシステムにのみ保存されます。関連する項目（ハンドブックの他の場所、ドキュメント、Issue 内）がある場合は、常に項目同士を相互リンクするようにしてください。

記録システム (System of Record)

記録のシステム (SoR) は、特定のデータ要素や情報の権威ある情報源です。記録のシステムが信頼できる唯一の情報源でもあることはありえますが、単に記録のシステムであるというだけでは、それが信頼できる唯一の情報源であることを直接意味しないことに注意してください。

機能と結果による組織化

ハンドブックは、その中のすべての項目が、最新の状態に保つための場所と所有者を持つように、職能と結果によって整理 されています。

この階層構造を守り、企業のトレーニング教材（オンボーディング教材、ハウツーなど）、ビデオ、その他のドキュメントのために別個の構造を維持しないことが不可欠です。
この階層構造を守ることは、ときに直感に反することがあります。私たちは長年にわたり、コンテンツを文脈の中に保つことが、将来の更新を行う際の一貫性を確保するのに役立つと学んできました。
ときには、視点の変化が望まれることもあります。そうした場合は、ハンドブックの関連セクションにリンクし、コンテンツ自体は含めないでください。例としてオンボーディングテンプレート（社内）を参照してください。あるいは、例えば、定義を重複させずにパフォーマンス指標にリンクする主要業績評価指標 (KPI) のリストもそうです。

スタイルガイド

ハンドブックを編集する前に、以下のスタイルガイダンスと文章スタイルガイドラインを読んでください。

ハンドブックページ

ハンドブックのページは短く簡潔に保ってください。冗長な表現を排除し、できるだけ短い言葉で要点に入りましょう。新入社員が挙げる最大の課題は、オンボーディング中に取り込むべき膨大な量の情報であることを念頭に置いてください。

構造のないコンテンツを避ける

Learning Playbook、FAQ、リンクのリスト（クイックリンクなど）、リソースページ、用語集、コース、ビデオ、テスト、process、standard operating procedure、トレーニング、ハウツーといった形式に基づく構造化されていないコンテンツは避けてください。これらは最新の状態に保つのが非常に難しく、職能と結果による整理と相性が良くありません。例: Contract Negotiation Playbook ではなく Contract Negotiation Handbook と呼ぶ
代わりに、答え、リンク、定義、コース、ビデオ、テストを、最も関連性の高い場所に置いてください。人々がコンテンツを簡単に検索できるよう、説明的な見出しを使ってください。
とはいえ、ハンドブックでは、適切な場所とタイミングで、単一のページ内であっても、形式を組み合わせてください。複数の形式を活用することは価値があり、人によって特定の形式を好むことがあります。
異なる種類や形式のコンテンツを埋め込んだ場合にページがどう見えるかではなく、職能と結果による 整理についてのみ気にかけてください。

見出しを積極的に使う

ページに 3 つ以上の見出しが含まれる場合（特に単一の「画面」より大きい場合）は、この MR の 6 〜 10 行目をコピーして、自動生成される目次 (ToC) を追加してください。見出しは通常の大文字小文字を使用すべきです。ALL CAPS や TitleCase は使わないでください。見出しの後には空行を 1 行残してください。これは標準では必須ではありませんが、私たちの慣習です。

貢献可能な図を使う

画像のアップロードや、貢献しにくい図よりも、貢献可能な図を優先してください。これにより、他の人が変更を提案したり貢献したりしやすくなります。Markdown における図の選択肢には Mermaid や PlantUML があります。

ハンドブックファーストのコンピテンシー

オールリモートで非同期な組織では、各チームメンバーがハンドブックファーストを実践すべきです。ハンドブックファーストであることの意味について詳しくは、このページのなぜハンドブックファーストなのかのセクションを参照してください。

チームメンバーとしてのハンドブックファーストのスキルと行動:

ハンドブックに積極的に貢献する。
マージリクエストから始める
質問に答えるときにハンドブックからの情報へのリンクを提供し、その情報がハンドブックに存在しない場合は、チームメンバーがそれを追加する。
どの情報が社内限定かを理解しつつ、すべての公開情報をパブリックハンドブックに置く。

ピープルリーダーとしてのハンドブックファーストのスキルと行動:

自分のチームや他の人にハンドブックファーストであることの責任を持たせる。
社内限定でないすべての情報について、パブリックハンドブックファーストであることでリーダーシップを示す。
新しいチームメンバーやマネージャーが、ハンドブックをリソースとしてどう活用するかを身につけられるようにする。
ハンドブックファーストであることの意味のロールモデルとして振る舞う。

管理

ハンドブック（パブリックハンドブックおよび内部ハンドブック）を最新の状態に保つことは、各部門と各チームメンバーの責任です。ハンドブックのコンテンツは正確であり、ガイドラインで概説されているのと同じ形式に従うべきです。誰にマージリクエストを提出すべきかについての質問や、ハンドブックに関する支援については、#handbook Slack チャンネルで連絡してください。

ハンドブックへの変更を直接コミットする権限が必要な場合は、New Access Request issue を提出し、アクセス承認のプロセスに従ってください。該当するハンドブックの「Maintainer」ロールをリクエストしてください。

マージ権限ガイドライン

MR をマージするには、該当するハンドブックプロジェクトへの developer アクセスが必要です。すべてのチームメンバーは、デフォルトで developer アクセスを持っているはずです。このページには、マージする際に念頭に置くべきいくつかのヒントとガイドラインが含まれています。

自信を持ってマージする

ハンドブックを壊してしまう心配をすることなく、パイプラインを通過する変更なら何でも自信を持ってマージできるはずです。パイプラインのテストは、大きな問題を検出するように設計されています。ハンドブックプロジェクトは、パイプラインが通過しない限り変更をマージできないように構成されています。万が一、ハンドブックを何らかの形で壊すコードがマージされた場合は、ハンドブックチームへの問題報告の手順に従ってください。

Merge Immediately は使わない

merge immediately 機能を 使わないでください! あなたの MR が重要で時間に敏感なものであっても、この機能を使うと他のみんなに多大な苦痛をもたらします。この機能は、重要な公開情報をできるだけ早く公開する必要がある場合にのみ使用すべきで、PR または Legal の承認を得るべきです。PR または Legal の承認がない場合は、この機能を使わないでください。

この背後にある技術的な理由についての詳しい文脈:

私たちは、デフォルトブランチに対して高速なパイプラインを持ちたいと考えています。これにより、変更がデプロイされ本番サイトで公開されるまでに必要な時間が最小化されます。
これを実現するために、デフォルトブランチではテストやリンターを一切実行しません。これらは長時間実行されるジョブであり、高速なデプロイをブロックしてしまうためです。
代わりに、Merge Train に頼って、すべてのマージリクエストの変更が、マージを許可される前に必要なすべてのテスト/リントジョブを正常に通過していることを保証します。
したがって、「merge immediately」を使うと、テスト/リントジョブが一切実行されず、問題が混入していた場合にデフォルトブランチが壊れる結果になります。
これは、この時点以降にデフォルトブランチから新しい MR を作成するすべての人が、自分のせいではない混乱を招くパイプラインの失敗を経験することになることを意味し、この状況が発見されてデフォルトブランチに修正がマージされるまで続きます。

いつ承認を得るか

自分のページへのあらゆる小さな変更を承認するよう毎回 ping されるのは煩わしいかもしれませんが、適切な承認なしにハンドブックのポリシーや手順を変更する人がいると、強い悪影響を及ぼす可能性があります。いつ承認を求めるべきかは、最善の判断を使ってください。

合理的な限り、硬直性よりも責任を実践してください。ページのオーナーがあなたの変更を喜ぶと予想される場合は、承認なしにそのままマージしてください。変更を知らせるために、常にコードオーナーに @mention コメントで ping してください。彼らは、自分のページが良くなり、変更をレビューして承認する時間を無駄にしなくて済んだことを喜ぶでしょう。万が一、何かが改善になっていなかった場合は、私たちはサインオフよりもクリーンアップを実践します。

以前は社内限定だったドキュメントを公開する場合など、適切なときは常に、変更をマージする前に承認機能を使ってコードオーナーから承認を得てください。

誰が承認できるか

ハンドブックページのオーナーは、ハンドブックのウェブ版でそのページを訪れ、編集中のページの Maintainers セクション（ページの右側にあり、ブラウザウィンドウが小さいと隠れていることがあります）に誰がいるかを見ることで特定できます。

一部のページでは、Maintainers セクションが空です。これは、そのページが個人ではなくグループによって維持されているためです。どのグループや個人がページを維持しているかを見るには、該当するリポジトリの CODEOWNERS ファイル（例えばハンドブックの CODEOWNERS）を参照してください。

ページのコードオーナーは、マージリクエストの承認セクションを見るときにも表示されます。

ページのコードオーナーはそのページの DRI であり、ハンドブックに何を載せるかについて最終決定権を持ちます。迷ったときは、彼らのページを変更する前に DRI の許可を得てください。DRI が C レベルの人であっても心配しないでください。あなたが個人コントリビューターであっても、自分の MR を彼らにアサインできます。

同僚に変更をレビューしてもらう

タイポのような小さな変更でない限り、マージする前に必ず別のチームメンバーに変更をレビューしてもらってください。

広範な権限

メンテナーであることは、単にマージできる能力だけよりもはるかに多くのアクセスを与えます。権限の完全なリストはドキュメントで確認できます。プロジェクトの広範な設定や構成にアクセスできることを念頭に置いてください。設定を調整したり、構造的な変更を加えたりしないでください。

他者に Maintainer アクセスを付与する

Access Request なしに、人々にメンテナーアクセスを付与しないでください。メンテナーとして、あなたは他の人にメンテナーアクセスを付与する能力を持っています。適切な承認を得て必要なドキュメントを作成するために、Access Request のプロセスに従わずにそれを行わないでください。

Issue とマージリクエスト用の説明テンプレート

さまざまなプロジェクトにおける Issue とマージリクエストの説明テンプレートは、それぞれ .gitlab/issue_templates ディレクトリと .gitlab/merge_request_templates ディレクトリにあり、新しいマージリクエストで編集・変更できます。

現在の承認者のリストについては、.gitlab/CODEOWNERS を参照してください。

社内ハンドブック

どこにあるのか?

なぜ社内ハンドブックがあるのか?

会社として、私たちはデフォルトで公開ですが、公に議論できないこともあります。内部ハンドブックは、チームメンバーが社内情報を共有できる場です。社内限定とみなされないものはすべて、GitLab のパブリックハンドブックにあるべきです。限定アクセスのものは、内部ハンドブックがすべてのチームメンバーからアクセス可能であるため、内部ハンドブックに追加すべきではありません。

このハンドブックを使うプロセス

非公開カテゴリに該当する項目のみを内部ハンドブックに追加してください。それ以外はすべて、私たちのパブリックな会社ハンドブックに追加すべきです。

社内ハンドブックグループへのアクセス

すべてのチームメンバーは、オンボーディング中のベースラインアクセスとして、Okta を通じて内部ハンドブックにアクセスできます。Okta のダッシュボードにログインし、GitLab Internal Handbook タイルをクリックしてください。まず Okta で認証する必要があります。

社内ハンドブックの使い方に関する質問

何を内部ハンドブックに置くべきか、パブリックハンドブックに置くべきかについての質問は? safe framework を参照するか、#safe で尋ねてください。
改善を手伝うことに興味がある? #internal-handbook チャンネルに参加してください。

KPI

エンジニアリングチームとすべてのサブチームは、ハンドブック更新頻度を KPI として追跡しており、チームごとに異なる目標を設定しています。現在、ハンドブック更新頻度を追跡している唯一の Division はエンジニアリングであり、この KPI の有効性を分析・観察するためです。

ハンドブックの外部での利用

私たちがやることのほぼすべてと同様に、私たちのハンドブックはオープンソースであり、他の会社が自社のドキュメントや慣行のインスピレーションとして使うかもしれないと考えています。とはいえ、ハンドブックは常に、私たちが何者になりたいか ではなく 私たちが何をするか について具体的であるべきで、すべての会社は時間をかけて自社のハンドブックを埋めていく必要があります。私たちのハンドブックは Attribution-ShareAlike 4.0 International ライセンスの下にあります。

GitLab に触発されて

もしあなたの会社が GitLab のハンドブックに触発されたなら、何に触発されたのかをぜひ知りたいです。私たちの Inspired by GitLab ページを参照してください。

価値あるものにする

別の会社が、自社ではうまくいかなかったため、私たちがどうやってハンドブックで運用しているのか尋ねてきました: 「ナレッジベースに何かが文書化されているのに、人々が読んだり検索したりする手間をかけないために、それを知らないことが多々あります。一部の人々は、自分が『大量の文章の壁』と感じるものに対して強い拒否感を持っています。」

私たちはこれを GitLab のハンドブックファーストなドキュメントアプローチを取り入れるためのガイドでカバーしようとしています。

人々がハンドブックを見る時間が有効に使われるようにするため、上記の「ハンドブックガイドライン」に従い、さらに次のことを行うべきです:

文章スタイルガイドに従う。
優れた検索機能を持ち、さらに公開して Google 検索できるようにする。
オンボーディング中に人々の知識をテストする。
実際の例を示す。
企業的な言い回しを避け、友達に話すように物事を説明する。詳しくは、シンプルな言葉についてのコミュニケーションガイドを参照してください。

Wiki 形式のハンドブックはスケールしない

会社のハンドブックはしばしば wiki として始まります。この形式は、GitLab のマージリクエストや GitLab Pages を使った静的ウェブサイトよりも、人々が作業しやすいものです。しかし、wiki は時間とともに古くなりがちで、整理が悪く最新でない状態になります。

wiki では、ページの複数の部分や複数のページにまたがる提案を行うことが不可能です。したがって、ハンドブックを再編成するのは困難です。GitLab のマージリクエストと GitLab Pages は分散バージョン管理に基づいているため、提出者と承認者の役割を分けられます。これにより、ハンドブックを最新の状態に保つ作業の分担が可能になります:

ハンドブックを読める人なら誰でも提案を行える
リーダー（時間が不足しがち）は、そうした提案を承認するだけでよい

wiki はまた、マージリクエストのように提案された変更を議論する方法がないため、変更に関する協働を促しません。

一部の wiki では、決定を伝えるために必要な、変更の差分を見たりリンクしたりするのが困難です。

Markdown ハンドブックの利点と wiki の限界に関する Sid と Paul の議論

最終更新 June 14, 2026: Merge pull request #403 from kyama0/claude/cool-turing-ls6eck (bfd74782)

ページのソースコードを見る - ページの編集 - please contribute.