GitLabプロジェクトをGoパッケージとして活用

(トップページはこちら) - (プロジェクトで作業を整理する)

社内ライブラリやプライベートなGoモジュールを、GitLab.com上で管理しながらgo getで直接取得できます。本記事では、GitLab.comをGoモジュールリポジトリとして活用するための設定方法と、実運用で遭遇する課題への対処法を解説します。

1. 基本的な動作確認

1.1 パブリックプロジェクトでの利用

GitLab.comのパブリックプロジェクトは、追加設定なしでGoパッケージとして利用できます。

go get gitlab.com/namespace/project

GitLab.comはgo getのリクエストに対して、以下のメタタグを自動的に返します。

• go-import: リポジトリの場所を指定
• go-source: ドキュメント生成用のソースコード情報を提供

1.2 プライベートプロジェクトの課題

プライベートプロジェクトに対して認証なしでgo getを実行すると、404エラーが返されます。

$ go get gitlab.com/namespace/private-project
go: gitlab.com/namespace/private-project: git ls-remote -q origin in /go/pkg/mod/cache/vcs/xxx: exit status 128:
fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled

この問題を解決するには、適切な認証設定が必要です。

2. プライベートプロジェクトの認証設定

2.1 認証の仕組み

Goのモジュール取得には2つの段階があります。

1. HTTPリクエスト: go getがメタタグを取得
2. Gitクローン: 実際のコードをダウンロード

それぞれに認証設定が必要です。

2.2 HTTPリクエストの認証（.netrcファイル）

パーソナルアクセストークン（read_apiスコープ）を取得し、.netrcファイルを作成します。

Linux/macOS の場合 (~/.netrc):

machine gitlab.com
login tanaka_taro
password glpat-xxxxxxxxxxxxxxxxxxxx

Windows の場合 (~/_netrc):

machine gitlab.com
login tanaka_taro
password glpat-xxxxxxxxxxxxxxxxxxxx

ファイル作成後、パーミッションを設定します。

chmod 600 ~/.netrc

2.3 Gitクローンの認証

Goがプロキシからモジュールを取得できない場合、Gitを直接使用します。以下のいずれかの方法で認証を設定します。

方法1: 認証情報をURLに埋め込む

git config --global url."https://tanaka_taro:[e-mail]".insteadOf "https://gitlab.com"

方法2: SSHを使用（推奨）

git config --global url."[e-mail]:".insteadOf "https://gitlab.com/"

SSH方式の場合、事前にSSH鍵をGitLab.comに登録しておく必要があります。

2.4 動作確認

設定後、プライベートプロジェクトを取得できることを確認します。

GOPRIVATE=gitlab.com go get gitlab.com/namespace/private-project

3. プライベートサブグループでの特殊な対応

3.1 問題の詳細

サブグループ配下のプライベートプロジェクト（例: gitlab.com/namespace/subgroup/go-module）では、セクション2の設定だけでは不十分な場合があります。

エラー例:

$ GOPRIVATE=gitlab.com/namespace/* go get gitlab.com/namespace/subgroup/go-module
go: gitlab.com/namespace/subgroup/go-module: invalid version: git ls-remote -q origin in /go/pkg/mod/cache/vcs/xxx: exit status 128

これはgo getが認証なしでリポジトリパスを検出しようとし、GitLab.comがセキュリティ上の理由から誤ったパス（gitlab.com/namespace/subgroup.git）を返すためです。

3.2 回避策: モジュール名に.gitを追加

Goの仕様では、モジュールパスに.gitなどのVCS修飾子がある場合、メタタグの取得をスキップして直接Gitクローンを実行します。

実装手順:

1. go.modを編集してモジュール名を変更

// 変更前
module gitlab.com/namespace/subgroup/go-module

// 変更後
module gitlab.com/namespace/subgroup/go-module.git

1. 変更をコミット・プッシュ

git add go.mod
git commit -m "Add .git suffix to module name for private subgroup"
git push

1. 依存プロジェクトのimport文を更新

// 変更前
import "gitlab.com/namespace/subgroup/go-module/pkg"

// 変更後
import "gitlab.com/namespace/subgroup/go-module.git/pkg"

1. モジュールを取得

GOPRIVATE=gitlab.com/namespace/* go mod tidy

3.3 注意点

• この方法はモジュール名の変更を伴うため、既存の依存プロジェクトすべてで修正が必要です
• 新規プロジェクトでは最初から.gitサフィックスを付けることを推奨します

4. プロキシとチェックサムデータベースの制御

4.1 環境変数の設定

プライベートモジュールを公開プロキシ経由で取得しようとすると、認証エラーやプライバシーの問題が発生します。以下の環境変数で制御します。

# GitLab.com全体をプライベートとして扱う
export GOPRIVATE=gitlab.com

# または特定の名前空間のみ
export GOPRIVATE=gitlab.com/namespace/*

# プロキシを使用しない
export GONOPROXY=gitlab.com

# チェックサムデータベースを使用しない
export GONOSUMDB=gitlab.com

4.2 推奨設定

.bashrcや.zshrcに以下を追加すると便利です。

# GitLab.comのプライベートプロジェクト用設定
export GOPRIVATE=gitlab.com
export GONOPROXY=gitlab.com
export GONOSUMDB=gitlab.com

4.3 動作の仕組み

• GOPRIVATE: 指定したパターンに一致するモジュールは、プロキシとチェックサムデータベースの両方をスキップ
• GONOPROXY: プロキシのみをスキップ（チェックサムデータベースは使用）
• GONOSUMDB: チェックサムデータベースのみをスキップ（プロキシは使用）

通常はGOPRIVATEのみの設定で十分です。

5. トラブルシューティング

5.1 404エラーが発生する

症状:

go: gitlab.com/namespace/project: reading https://gitlab.com/namespace/project?go-get=1: 404 Not Found

原因と対処:

• .netrcの認証情報が間違っている → トークンを再確認
• トークンのスコープが不足している → read_apiスコープを付与
• .netrcのパーミッションが緩い → chmod 600 ~/.netrcを実行

5.2 Gitクローンで認証エラー

症状:

fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled

原因と対処:

• Git認証が未設定 → セクション2.3の設定を実施
• SSH鍵が未登録（SSH方式の場合） → GitLab.comにSSH鍵を追加

5.3 サブグループで取得できない

症状:

invalid version: git ls-remote -q origin in /go/pkg/mod/cache/vcs/xxx: exit status 128

原因と対処:

• プライベートサブグループの認証問題 → セクション3.2の.gitサフィックスを追加

6. 推奨設定のまとめ

実運用では以下の設定を推奨します。

1. 環境変数の設定 (~/.bashrcまたは~/.zshrc):

export GOPRIVATE=gitlab.com
export GONOPROXY=gitlab.com
export GONOSUMDB=gitlab.com

2. 認証設定 (~/.netrc):

machine gitlab.com
login your_username
password your_personal_access_token

3. Git設定:

# SSH方式（推奨）
git config --global url."[e-mail]:".insteadOf "https://gitlab.com/"

# または HTTPS方式
git config --global url."https://username:[e-mail]".insteadOf "https://gitlab.com"

4. プライベートサブグループのプロジェクト:

• go.modのモジュール名に.gitサフィックスを追加
• 例: module gitlab.com/namespace/subgroup/project.git

これらの設定により、GitLab.com上のプライベートGoモジュールを、パブリックモジュールと同様にシームレスに利用できます。