最初にやったほうがいいこと (アカウント取ったら、プロジェクト作ったら...)

最初にやったほうがいいこと特集

GitLab Advent Calendar 2016 ももう 15 日目です。本日は、自分が GitLab を使うときにまず最初にやることを紹介したいと思います。

もちろん、最初にやることは人それぞれだと思いますので、もしよろしければコメントにここはちがうんじゃないか? とか、これはやらなくていいの? といただければ幸いです。

風邪でダウンしたり、忘年会だったりで書くのが遅れてごめんなさい。

アカウントを作って最初にやること

アイコン画像を設定しましょう!

Avatar ですね。自分の顔写真でも似顔絵でも何でも構いません。

様々なところでこの画像が表示されます。Issue の担当者や、コミットログやアクティビティなど... 設定してあると個人を識別しやすくなり、見通しが良くなります。

デフォルトでは摩訶不思議な模様になっていますが、共同作業を円滑に進める上でアイコン画像は必ず設定しましょう!

アイコン画像は右上のアイコンから Profile Settings で変更できます。

SSH 公開鍵を登録しましょう! (オプション)

GitLab は Git のアクセスで HTTP/HTTPS か SSH を利用することができます。SSH は様々なことに使えますので、できることならば SSH を使うことをおすすめします。

最近は GitHub でも SSH よりも HTTPS が推奨だそうですので、GitLab のためだけに SSH を覚えるのは面倒ですので、無視してもいいかもしれません。

SSH は様々な使い方ができます。サーバーにログインしたり、ファイルをリモートにコピーしたり、ディレクトリの同期を取ったり、ポートフォワーディングをしたり... GitLab のためだけに SSH を覚えるとすると面倒なのですが、いろんなことに使えるので、ぜひ SSH にトライしてください。

右上のアイコンから Profile Settings -> SSH Keys で登録することができます。SSH 鍵の作り方や登録方法は SSH をご覧ください。方法は GitHub とほとんど同じですので、ググったほうが分かりやすいかもりません。

プロジェクトを作って最初にやること

プロジェクト名や説明を見直す

プロジェクト名や説明は他の人にプロジェクトの内容を伝えるために非常に重要です。なかなか見なおす機会も少ないと思いますので、見なおしてみましょう。

特に、プロジェクトの Path はなるべく変えてはいけませんので本当にこれでいいのかを再度確かめて下さい。(変更は簡単ですが、URL が変わるので連絡をあちこちにしないといけなくなります)

これらはプロジェクトの右上の をクリックして Edit Project から変更ができます。でも、この ボタン、ブラウザーの幅によっては消えてしまいます... 見つからない時は幅を変えてみてください。

ここでプロジェクトのアイコン画像も登録できます。識別がしやすくなるので、こちらも合わせて設定したほうがよいでしょう。

使わない機能をオフにしたり、見せたくないものを隠す

プロジェクトで使わないと思っている機能はオフにしてしまいましょう! プロジェクトに初めて参加する人にとって、使われていない機能があると戸惑います。

• Repository
• Merge requests
• Builds
• Snippets
• Issues
• Wiki
• LFS

これらの機能は、Disabled (無効)・Only team members (チームメンバーのみ)・Everyone with access (誰でも) から選ぶことができます。

Container Registry だけは使うか使わないかだけしか選ぶことができません。

これらの設定は、プロジェクトの説明と同じく アイコンをクリックして Edito Project から変更することができます。

メンバーを追加する

プロジェクトに参加するメンバーを追加しましょう! 仲間は多いほうがいいです! 巻き込みたい人がいたら追加しちゃいましょう!

ボタンから Members を選ぶことでメンバーを追加できます。ロールは迷ったら Master でいいと思います。

でも、きちんとしたプロジェクトはロールは正しい物を選びましょう。ロールごとに何ができるかは、Permissions に書かれています。また、メンバーに期限を設けることもできます。

メンバーをたくさん追加したいときはグループの使用も検討してください。

Description Template を設定する

Description Tenplate とは、Issue や　Merge Request に対するテンプレです。よりよいバグ報告をもらうためには非常に重要です。

詳しくは GitLab Advent Calendar 2016 の二日目の記事をご覧ください

Label を作る

Issue につける Label は重要なので、最初のうちに作ってしまいましょう。

Isses -> Labels で generate a defaultsetof labels をクリックすると、ラベルを一式作ってくれます。日本語がいいとか、気に入らないという人は、自分で作っちゃいましょう!

README を書く

おそらく一番大事なことです。GitLab や GitHub では、README を書くとダッシュボードに表示されます。ここにプロジェクトの説明を書いておくと、プロジェクトの参加メンバーや関係者、アプリを使う人に分かりやすくなります。

通常、README.md というファイルを用意して、Markdown で記述します。

プロジェクトによっても異なりますが、README もしくはここから辿れるところに、うまく説明が書いてあると、利用者にとってとても役に立ちます。社内で使う場合は、お客さんの情報・責任者・組織図・資料の共有フォルダの場所・叶えなければならないこと・簡単な使い方・開発環境のセットアップなどが書かれていると非常によいでしょう。

また、常に最新の情報を反映させるようにしましょう。

README 以外に GitLab が特別扱いするドキュメントファイルは以下のとおりです。拡張子を .md にしておくと Markdown を使うことができます。

ファイル名	説明
README.md	説明書きを書く。ディレクトリに置いておくと、そのディレクトリで表示されます。ディレクトリの説明を書いておくのにも使えます。
CONTRIBUTING.md	主に開発者向けの情報を書きます。README からリンクを貼っておくとよいでしょう。Issue の作成画面にもリンクが表示されます。
CHANGELOG.md	CHANGELOG を書きます。ダッシュボードからすぐにアクセスできるようになっていますが、自分はうまく使えてません...

意外と多いですね...

やることは多いのですが、後々プロジェクトがうまく進行できるかどうかのキモになるところですので、がんばりましょう!

実は、自分はもっと手を抜いていまして...

1. プライベートで適当にプロジェクトを作る
2. 作ったものを周りの人に見せて反応が良ければメンバーに加える
3. 良さそうなら、グループを作成してプロジェクトを移動させる
4. 移動のついでに情報を再整理して公開する

ようなスタイルを取っております。特に 2 くらいまでは Repository くらいしか使わず、勢いでやるようにしています。

GitLab CE をインストールした後に最初にやること

個人リソース上限の引き上げ

GitLab CE は標準でこんな感じで制限がかかっています。

項目	制限値
最大プロジェクト数	10
最大添付ファイルサイズ	10MB
CI の最大成果物ファイルサイズ	100MB

社内で使うには少し少ないと思いますので、引き上げたほうがよいでしょう。

管理者でログインし、右上のスパナボタンをクリック後、右上の アイコンをクリックし、Settings -> Account and Limit Settings から変更できます。CI の最大成果物ファイルサイズはちょっとだけ離れていて Continuous Integration から設定できます。

もし、追加のリバースプロキシを使われている場合は、そちらの設定も見直してみて下さい。

説明の変更

GitLab のいくつかの場所の説明を変更することができます。社内向けのサービスであることや、利用規約へのリンクなど、場所に合わせて説明を変更することをおすすめします。

設定	説明
Appearance / Sign in/Sign up pages	未ログイン状態の最初の画面の左側に表示するタイトル・説明文・アイコンです。サービスの名称や目的、利用規約への誘導を書くと良いでしょう。
Appearance / Navigation bar	一番上の表示されているロゴです。GitLab.com と間違えないためにも、変更しておくことを強くおすすめします。
Settings / Sign-in Restrictions / Sigin in Text	Sign in/Sign up pages のすぐ下に表示されます。正直違いがよく分かりません...
Settings / Sign-in Restrictions / Help page text	ヘルプのトップページに表示されます。こちらも利用規約への誘導をしたほうがよいでしょう。また、ヘルプに書かれている内容の補記 (この機能は動きません) なども書いておくとよいでしょう。
Settings / Continuous Integration / Shared runners text	各プロジェクトの Runners 設定の Shared Runners に表示されます。提供している Shared Runner の仕様と使い方へ誘導するとよいでしょう。

Sign-up の禁止 (必要があれば)

社内に GitLab CE をインストールする場合、社内の LDAP サーバーを使って認証することになると思います。もしくは、好きにアカウントを作らせるのではなく、一括で社員のアカウントを作成するかもしれません。

新たにユーザーを作られるのと不都合がある場合、Settings -> Sign-up Restrictions -> Sign-up enabled のチェックを外します。

利用規約・使い方・サポートプロジェクトの作成

インストールした GitLab CE の利用者に向けたサポートページのためのプロジェクトを作成します。

そのプロジェクトの README に、利用規約・使い方・質問方法などが書いておいて、説明の変更から誘導するようにすると使いやすくなるでしょう。このプロジェクトへのリンクを「説明の変更」に書かれている場所に追加しておくと親切かと思います。

ただ、GitLab CE のメンテナンス中は読めなくなってしまいますので、可能であれば別途ウェブサイトを用意するようにして下さい。

通知メッセージを入れる

GitLab は全てのページと git push 時に表示されるメッセージを設定することができます。

こちらの方に、サポートページへのリンクを貼っておくとよいでしょう。

もちろん、サーバーメンテナンス時はその旨通知する手段として使うことができます。メッセージを変更した時は色を変えていくと分かりやすくなると思います。

スパナアイコンをクリックし、Messages から設定することができます。

終わり

書いてみると意外と多いですね!

冒頭でも書いたとおり、これが抜けてるんじゃないの? ここは違うんじゃないの? といった意見を募集しておりますので、ぜひコメントに書いていただけると!