gitlab-file

ファイルスキル

glab api の raw エンドポイント呼び出しを使用した、GitLab のリポジトリファイル操作です。

クイックリファレンス

操作	コマンドパターン	リスク
ファイル情報の取得	glab api projects/:id/repository/files/:path?ref=:branch	-
生のコンテンツの取得	glab api projects/:id/repository/files/:path/raw?ref=:branch	-
blame の取得	glab api projects/:id/repository/files/:path/blame?ref=:branch	-
ファイルの作成	glab api projects/:id/repository/files/:path -X POST -f ...	⚠️
ファイルの更新	glab api projects/:id/repository/files/:path -X PUT -f ...	⚠️
ファイルの削除	glab api projects/:id/repository/files/:path -X DELETE -f ...	⚠️⚠️

リスクの凡例：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危険

このスキルを使用する場面

必ず使用してください：

• ユーザーが GitLab のファイル内容を読み取りたい場合（ローカルではなく）
• ユーザーが GitLab API 経由でファイルを作成・更新・削除したい場合
• ユーザーがファイルの blame 情報を必要としている場合
• ユーザーがファイルの生のコンテンツをダウンロードしたい場合
• ユーザーが「リポジトリファイル」、「blob」、「raw content」と言及した場合

使用しないでください：

• ユーザーがローカルファイルを編集したい場合（ファイル編集ツールを使用してください）
• ユーザーがコードを検索したい場合（gitlab-search を使用してください）
• ユーザーがリポジトリツリーを閲覧したい場合（gitlab-repo を使用してください）
• ユーザーが複数のファイルをコミットしたい場合（ローカルで git を使用してください）

API の前提条件

必須のトークンスコープ： api

権限：

• ファイルの読み取り：Reporter 以上（プライベートリポジトリの場合）
• ファイルの作成・更新・削除：Developer 以上（プッシュ権限が必要）

URL エンコード

ファイルパスは URL エンコードする必要があります。パス内のスラッシュは %2F になります：

# src/main.py -> src%2Fmain.py
echo 'src/main.py' | jq -Rr @uri
# Output: src%2Fmain.py

利用可能なコマンド

ファイル情報の取得（Base64 エンコード）

# Get file metadata and content (base64)
glab api "projects/123/repository/files/README.md?ref=main" --method GET

# With URL-encoded path
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)?ref=main"

# From specific branch
glab api "projects/123/repository/files/config.json?ref=develop" --method GET

# From tag
glab api "projects/123/repository/files/version.txt?ref=v1.0.0" --method GET

# From commit SHA
glab api "projects/123/repository/files/app.py?ref=abc123" --method GET

レスポンスに含まれる内容：

• file_name - ファイル名
• file_path - フルパス
• size - ファイルサイズ（バイト単位）
• encoding - コンテンツのエンコード方式（base64）
• content - Base64 エンコードされたコンテンツ
• content_sha256 - SHA256 ハッシュ
• ref - ブランチ／タグ／コミット
• blob_id - Blob SHA
• commit_id - 最終コミット SHA
• last_commit_id - commit_id と同じ

Base64 コンテンツのデコード

# Get and decode file content
glab api "projects/123/repository/files/README.md?ref=main" | \
  jq -r '.content' | base64 -d

生のファイルコンテンツの取得

# Get raw file content (not base64)
glab api "projects/123/repository/files/README.md/raw?ref=main" --method GET

# With encoded path
glab api "projects/123/repository/files/$(echo 'src/app.py' | jq -Rr @uri)/raw?ref=main"

# Binary file (save to file)
glab api "projects/123/repository/files/$(echo 'images/logo.png' | jq -Rr @uri)/raw?ref=main" > logo.png

ファイルの blame の取得

# Get blame information
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" --method GET

# Parse blame output
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" | \
  jq -r '.[] | "\(.commit.author_name): lines \(.lines | length)"'

ファイルの作成

# Create new file with content
glab api "projects/123/repository/files/$(echo 'docs/new-file.md' | jq -Rr @uri)" --method POST \
  -f branch="main" \
  -f content="# New File\n\nContent here" \
  -f commit_message="Add new documentation file"

# Create with base64 content
glab api "projects/123/repository/files/$(echo 'data/config.json' | jq -Rr @uri)" --method POST \
  -f branch="main" \
  -f content="$(cat config.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Add configuration file"

# Create on new branch
glab api "projects/123/repository/files/$(echo 'feature/new.txt' | jq -Rr @uri)" --method POST \
  -f branch="feature-branch" \
  -f start_branch="main" \
  -f content="Feature content" \
  -f commit_message="Add feature file"

# Create with author info
glab api "projects/123/repository/files/script.sh" --method POST \
  -f branch="main" \
  -f content="#!/bin/bash\necho Hello" \
  -f commit_message="Add script" \
  -f author_email="[email protected]" \
  -f author_name="Developer"

ファイルの更新

# Update file content
glab api "projects/123/repository/files/README.md" --method PUT \
  -f branch="main" \
  -f content="# Updated README\n\nNew content here" \
  -f commit_message="Update README"

# Update with base64 (for binary or complex files)
glab api "projects/123/repository/files/$(echo 'config/settings.json' | jq -Rr @uri)" --method PUT \
  -f branch="main" \
  -f content="$(cat settings.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Update settings"

# Update on feature branch
glab api "projects/123/repository/files/src%2Fapp.py" --method PUT \
  -f branch="feature-update" \
  -f content="$(cat app.py | base64)" \
  -f encoding="base64" \
  -f commit_message="Refactor app module"

# Update with last known commit (for conflict detection)
glab api "projects/123/repository/files/data.json" --method PUT \
  -f branch="main" \
  -f content="{ \"updated\": true }" \
  -f commit_message="Update data" \
  -f last_commit_id="abc123def456"

ファイルの削除

# Delete file
glab api "projects/123/repository/files/$(echo 'old-file.txt' | jq -Rr @uri)" --method DELETE \
  -f branch="main" \
  -f commit_message="Remove deprecated file"

# Delete with author info
glab api "projects/123/repository/files/$(echo 'temp/test.txt' | jq -Rr @uri)" --method DELETE \
  -f branch="main" \
  -f commit_message="Clean up temp files" \
  -f author_email="[email protected]" \
  -f author_name="Developer"

ファイル操作のオプション

オプション	型	説明
branch	string	対象ブランチ（書き込み操作では必須）
start_branch	string	新規ファイルの作成元ブランチ
content	string	ファイルのコンテンツ（プレーンテキストまたは base64）
encoding	string	コンテンツのエンコード方式：text（デフォルト）または base64
commit_message	string	コミットメッセージ（書き込み操作では必須）
author_email	string	カスタムの作成者メールアドレス
author_name	string	カスタムの作成者名
last_commit_id	string	期待される最終コミット（競合検出用）

よくあるワークフロー

ワークフロー 1：ファイルのダウンロードと表示

# Get file content
glab api "projects/123/repository/files/$(echo 'config/app.yml' | jq -Rr @uri)/raw?ref=main"

ワークフロー 2：設定ファイルの更新

# 1. Download current file
glab api "projects/123/repository/files/config.json/raw?ref=main" > config.json

# 2. Edit locally
# ... make changes to config.json ...

# 3. Upload updated file
glab api "projects/123/repository/files/config.json" --method PUT \
  -f branch="main" \
  -f content="$(cat config.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Update configuration"

ワークフロー 3：フィーチャーブランチでファイルを作成

# Create new file on new branch
glab api "projects/123/repository/files/$(echo 'docs/feature.md' | jq -Rr @uri)" --method POST \
  -f branch="feature-docs" \
  -f start_branch="main" \
  -f content="# Feature Documentation\n\nDetails here..." \
  -f commit_message="Add feature documentation"

ワークフロー 4：blame でファイル履歴を確認

# Get blame info for a file
glab api "projects/123/repository/files/$(echo 'src/critical.py' | jq -Rr @uri)/blame?ref=main" | \
  jq -r '.[] | "\(.commit.short_id) \(.commit.author_name): \(.lines | length) lines"'

ワークフロー 5：複数ファイルの一括読み取り

# Read multiple files
for file in "README.md" "package.json" "Dockerfile"; do
  echo "=== $file ==="
  glab api "projects/123/repository/files/$(echo "$file" | jq -Rr @uri)/raw?ref=main"
  echo ""
done

ワークフロー 6：ブランチ間でファイルをコピー

# 1. Get file from source branch
content=$(glab api "projects/123/repository/files/config.json/raw?ref=develop")

# 2. Create/update on target branch
echo "$content" | base64 > /tmp/content.b64
glab api "projects/123/repository/files/config.json" --method PUT \
  -f branch="main" \
  -f content="$(cat /tmp/content.b64)" \
  -f encoding="base64" \
  -f commit_message="Sync config from develop"

トラブルシューティング

問題	原因	解決方法
404 Not Found	ファイルが存在しません	パスとブランチを確認してください
400 Path encoding	スラッシュがエンコードされていません	jq -Rr @uri を使用してエンコードしてください
バイナリコンテンツが文字化けする	base64 を使用していません	/raw エンドポイントを使用するか、base64 をデコードしてください
更新時に競合が発生する	ファイルが変更されています	楽観的ロックには last_commit_id を使用してください
403 Forbidden	プッシュ権限がありません	Developer 以上のロールが必要です
大きなファイルの操作に失敗する	サイズ制限	GitLab にはファイルサイズの制限があります

サイズ制限

• API 経由のデフォルトの最大ファイルサイズ：10 MB
• 大きなファイル：代わりに Git LFS を使用してください
• バイナリファイル：必ず base64 エンコードを使用してください

ベストプラクティス

1. パスをURLエンコードする：スラッシュを含むファイルパスは必ずエンコードしてください
2. バイナリにはbase64を使用する：バイナリファイルはbase64でエンコードしてください
3. 意味のあるコミット：内容が分かるコミットメッセージを記述してください
4. フィーチャーブランチを使用する：大きな変更では、mainに直接コミットしないでください
5. 競合を確認する：重要な更新にはlast_commit_idを使用してください

関連ドキュメント

• APIヘルパー
• 安全対策
• クイックリファレンス
• GitLab Repository Files API