gitea

Gitea

extea を使って Gitea インスタンスを操作します。extea は tea のドロップイン置き換えで、プロジェクトボード（カンバン）管理機能が追加されています。

認証

• すべてのコマンドで --login <name>（または -l <name>）を指定して、ログインプロファイルを選択します。
• ボードのパスワードは、ログイン情報とともに ~/.config/tea/config.yml に保存されます。GITEA_PASSWORD 環境変数でも設定できます。
• HTTP 経由で git の push/pull を行う場合は、URL にトークンを埋め込みます：http://user:TOKEN@<host>/owner/repo.git
• extea login add を実行してログインを作成します（API トークンと任意のボードパスワード）。

リポジトリ

extea repos list -l <login>
extea repos create --name <name> --description "<desc>" -l <login>
extea repos delete --name <name> --owner <owner> --force -l <login>

既存のローカルリポジトリを push する予定のリポジトリを作成する場合は、--init を使用しないでください。

イシュー

extea issues list -l <login> -r owner/repo
extea issues list -l <login> -r owner/repo --state all    # open + closed
extea issues create -l <login> -r owner/repo \
  --title "<title>" --description "<desc>" \
  --labels "<label1>,<label2>" --milestone "<milestone title>" --assignees "<user>"
extea issues close   -l <login> -r owner/repo <number>
extea issues reopen  -l <login> -r owner/repo <number>

プルリクエスト

extea pulls list -l <login> -r owner/repo
extea pulls list -l <login> -r owner/repo --state all     # open + merged + closed
extea pulls create -l <login> -r owner/repo \
  --title "<title>" --description "<desc>" \
  --head <branch> --base main \
  --labels "<labels>" --milestone "<ms>"
extea pulls close -l <login> -r owner/repo <number>

PR のマージ

PR がすでにマージされている場合、extea pulls merge は何も知らせずに失敗することがあります。代わりに API を使用してください。

extea api -l <login> -X POST "/repos/owner/repo/pulls/<number>/merge" \
  -f Do=merge \
  -f MergeMessageField="<commit message>"
# Do= options: merge | rebase | squash | manually-merged

ラベル

extea labels list   -l <login> -r owner/repo
extea labels create -l <login> -r owner/repo --name "<name>" --color "#hexcolor" --description "<desc>"
extea labels delete -l <login> -r owner/repo <id>

マイルストーン

extea milestones list   -l <login> -r owner/repo
extea milestones list   -l <login> -r owner/repo --state all
extea milestones create -l <login> -r owner/repo --title "<title>" --description "<desc>" --deadline "<YYYY-MM-DD>"
extea milestones close  -l <login> -r owner/repo "<title>"   # close by title string

リリース

extea releases list   -l <login> -r owner/repo
extea releases create -l <login> -r owner/repo --tag <tag> --title "<title>" --note "<body>"

リリースを作成する前に、タグがリポジトリに存在している必要があります。

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
extea releases create -l <login> -r owner/repo --tag v1.0.0 --title "v1.0.0" --note "..."

コメント

extea comment -l <login> -r owner/repo <issue-or-pr-number> "<comment text>"

PR とイシューは同じ番号を共有しているため、PR 番号にコメントする場合も同じように操作できます。

通知

extea notifications -l <login> -r owner/repo

extea notifications は git ディレクトリから実行する場合でもリポジトリのコンテキストが必要なため、常に -r owner/repo を指定してください。

API（エンドポイントへの直接アクセス）

名前付きコマンドで対応していない操作（PR のマージ、Wiki など）には、これを使用します。

extea api -l <login> <endpoint>                            # GET
extea api -l <login> -X POST <endpoint> -f key=value       # POST with form fields
extea api -l <login> -X PATCH <endpoint> -f key=value      # PATCH
extea api -l <login> -X DELETE <endpoint>                  # DELETE

JSON 出力を python3 -c "import sys,json; d=json.load(sys.stdin); print(...)" にパイプして、フィールドを抽出します。

プロジェクトボード

Gitea にはプロジェクトボード用の REST API がないため、ボードコマンドではウェブセッション認証（設定ファイルに保存されたパスワード、または GITEA_PASSWORD 環境変数）を使用します。

プロジェクト（projects、project、p）

# List projects
extea projects ls -l <login> -r owner/repo
extea projects ls --state all -l <login> -r owner/repo    # open + closed

# View kanban board (shows all columns and their issues)
extea projects view <id> -l <login> -r owner/repo

# Create (templates: kanban, triage, none)
extea projects create -t "<title>" --template kanban -l <login> -r owner/repo

# Edit title
extea projects edit <id> -t "<new title>" -l <login> -r owner/repo

# Close / reopen / delete
extea projects close  <id> -l <login> -r owner/repo
extea projects open   <id> -l <login> -r owner/repo
extea projects delete <id> -l <login> -r owner/repo

# Assign issues to a project (can pass multiple -i flags)
extea projects assign <project-id> -i <issue-num> -i <issue-num> -l <login> -r owner/repo

# Remove issues from a project
extea projects unassign -i <issue-num> -l <login> -r owner/repo

# Move issues between columns
extea projects move <project-id> --column <col-id> -i <issue-num> -l <login> -r owner/repo

列（columns、column、col）

# List columns in a project
extea columns ls -p <project-id> -l <login> -r owner/repo

# Create a column (--color is optional)
extea columns create -p <project-id> -t "<title>" --color "#hexcolor" -l <login> -r owner/repo

# Edit a column title
extea columns edit -p <project-id> -c <col-id> -t "<new title>" -l <login> -r owner/repo

# Delete a column (issues move to default column)
extea columns delete -p <project-id> -c <col-id> -l <login> -r owner/repo

# Set default column (new issues land here)
extea columns default -p <project-id> -c <col-id> -l <login> -r owner/repo

# Reorder columns (pass all column IDs in desired order)
extea columns move -p <project-id> --order <id1>,<id2>,<id3> -l <login> -r owner/repo

JSON 出力

projects list、projects view、または columns list に --output json / -o json を追加すると、機械可読な出力を取得できます。ID の抽出に便利です。

extea projects ls -l <login> -r owner/repo -o json | python3 -c "import sys,json; [print(p['id'], p['title']) for p in json.load(sys.stdin)]"
extea columns ls -p <id> -l <login> -r owner/repo -o json | python3 -c "import sys,json; [print(c['id'], c['title']) for c in json.load(sys.stdin)]"

Wiki

Wiki は http://<host>/owner/repo.wiki.git にある独立した git リポジトリです。

最初のページが作成されるまで、Wiki リポジトリは存在しません。 クローンする前に、API 経由で初期化してください。

# Initialize wiki with a Home page (required before git clone works)
extea api -l <login> -X POST "/repos/owner/repo/wiki/new" \
  -f title="Home" \
  -f content_base64="$(echo '# Home page content' | base64)" \
  -f message="init: create wiki home page"

# Create additional pages
extea api -l <login> -X POST "/repos/owner/repo/wiki/new" \
  -f title="Page Title" \
  -f content_base64="$(printf '%s' "$CONTENT" | base64)" \
  -f message="docs: add page"

# List all wiki pages
extea api -l <login> "/repos/owner/repo/wiki/pages"

現在の作業ディレクトリを汚さないよう、Wiki は必ず /tmp で操作してください。

# Clone wiki (only works after at least one page has been created)
if [ ! -d /tmp/repo-wiki ]; then
  git clone "http://user:${TOKEN}@<host>/owner/repo.wiki.git" /tmp/repo-wiki
fi

cd /tmp/repo-wiki
git config user.name "yourname"
git config user.email "you@host"   # Must match the Gitea account's registered email or history links won't be clickable
                                    # Check with: extea api -l <login> "/users/<username>" | python3 -c "import sys,json; print(json.load(sys.stdin)['email'])"

# Pages are markdown files: Home.md, Page-Name.md (hyphens for spaces)
# Edit files, then:
git add -A && git commit -m "Update wiki"
git push

典型的なワークフロー

# 1. Create repo and push code
extea repos create --name myrepo --description "..." -l mylogin
cd /tmp/myrepo && git init && git remote add origin "http://user:TOKEN@host/user/myrepo.git"
git push -u origin main

# 2. Set up labels and milestones
extea labels create -l mylogin -r user/myrepo --name "bug" --color "#d73a4a"
extea milestones create -l mylogin -r user/myrepo --title "v1.0" --deadline "2026-06-01"

# 3. File issues
extea issues create -l mylogin -r user/myrepo --title "Fix the thing" --labels "bug" --milestone "v1.0"

# 4. Branch, commit, PR
git checkout -b fix/the-thing && git commit -m "fix: the thing" && git push origin fix/the-thing
extea pulls create -l mylogin -r user/myrepo --title "fix: the thing" --head fix/the-thing --base main

# 5. Comment, merge
extea comment -l mylogin -r user/myrepo 1 "LGTM"
extea api -l mylogin -X POST "/repos/user/myrepo/pulls/1/merge" -f Do=merge -f MergeMessageField="fix: the thing"

# 6. Project board
extea projects create -t "Sprint 1" --template kanban -l mylogin -r user/myrepo
PROJECT_ID=$(extea projects ls -l mylogin -r user/myrepo -o json | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")
extea projects assign $PROJECT_ID -i 1 -l mylogin -r user/myrepo
# Get column IDs, then move issues
extea columns ls -p $PROJECT_ID -l mylogin -r user/myrepo -o json
extea projects move $PROJECT_ID --column <col-id> -i 1 -l mylogin -r user/myrepo

# 7. Release
git tag -a v1.0.0 -m "Release v1.0.0" && git push origin v1.0.0
extea releases create -l mylogin -r user/myrepo --tag v1.0.0 --title "v1.0.0" --note "..."

# 8. Wiki
extea api -l mylogin -X POST "/repos/user/myrepo/wiki/new" \
  -f title="Home" -f content_base64="$(echo '# Docs' | base64)" -f message="init wiki"
git clone "http://user:TOKEN@host/user/myrepo.wiki.git" /tmp/myrepo-wiki

PR のレビューと行内コメント

extea pulls review は対話型でのみ使用できます。スクリプトから行内コメントを投稿するには、API と curl を使用してください。

# Get the head commit SHA first
HEAD_SHA=$(extea api -l <login> "/repos/owner/repo/pulls/<number>" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# Post a review with inline comments
curl -s -X POST "http://<host>/api/v1/repos/owner/repo/pulls/<number>/reviews" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"COMMENT\",
    \"body\": \"Overall review comment\",
    \"comments\": [
      { \"path\": \"main.py\", \"new_position\": 4,  \"body\": \"Comment on new file line 4\" },
      { \"path\": \"main.py\", \"old_position\": 3, \"body\": \"Comment on a deleted line\" }
    ]
  }"

• new_position — ファイルの新しいバージョンでの行番号（1 始まり）
• old_position — 古いバージョンでの行番号（削除された行にコメントする場合）
• event の選択肢：COMMENT | APPROVE | REQUEST_CHANGES（自分自身の PR では REQUEST_CHANGES を使用できません）
• extea api -f はネストされた JSON 配列に対応していないため、レビューの作成には必ず curl を使用してください。
• レスポンスの original_position フィールドは常に 0 です（Gitea のバグ）。アンカーが正しく設定されたことを確認するには、レスポンスの diff_hunk を確認してください。

レビューの行内コメントを取得します。

extea api -l <login> "/repos/owner/repo/pulls/<number>/reviews/<review-id>/comments"

その他のレビュー操作：

extea pulls approve -l <login> -r owner/repo <number>           # approve
extea pulls reject  -l <login> -r owner/repo <number>           # request changes (not your own PR)
extea api -l <login> "/repos/owner/repo/pulls/<number>/reviews" # list all reviews

画像

イシュー／PR の添付ファイル

ファイルをアップロードし、返された URL を Markdown に埋め込みます。

# Upload attachment to an issue
curl -s -X POST "http://<host>/api/v1/repos/owner/repo/issues/<number>/assets" \
  -H "Authorization: token $TOKEN" \
  -F "attachment=@/path/to/image.jpg" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['browser_download_url'])"
# Returns: http://<host>/attachments/<uuid>

# Embed in a comment
extea comment -l <login> -r owner/repo <number> "![alt](http://<host>/attachments/<uuid>)"

Wiki の画像

画像ファイルを .md ファイルと一緒に Wiki の git リポジトリへ直接コミットします。Markdown では相対パスで参照してください。Gitea が自動的に解決します。

cd /tmp/repo-wiki
cp /path/to/image.jpg ./image.jpg
echo '![caption](image.jpg)' >> Page.md
git add image.jpg Page.md
git commit -m "docs: add image"
git push

画像は次の場所で配信されます。

http://<host>/owner/repo/wiki/raw/branch/master/<filename>

画像は Wiki リポジトリ内で .md ファイルと同じ階層にあるフラットなファイルとして保存され、Wiki ページとしては一覧表示されません。見つけやすい場所（例：Home.md）から、画像を含むページにリンクしてください。

コミットとファイルの行へのリンク

これらは、課題／PR の本文やコメントに埋め込む Markdown リンクです。CLI コマンドではありません。

コミット参照 — 短い SHA または完全な SHA を貼り付けると、Gitea が自動的にリンクします：

cdc9af8
owner/repo@cdc9af8    ← cross-repo form

ファイル＋行（ブランチ参照） — ファイルの変更に伴ってリンク先がずれます：

http://<host>/owner/repo/src/branch/main/file.py#L10
http://<host>/owner/repo/src/branch/main/file.py#L10-L15   ← line range

ファイル＋行（コミットのパーマリンク） — 安定しており、リファクタリング後もリンク先はずれません：

http://<host>/owner/repo/src/commit/<sha>/file.py#L10
http://<host>/owner/repo/src/commit/<sha>/file.py#L10-L15

コミットの差分ページ：

http://<host>/owner/repo/commit/<sha>

バグ報告では、コミットのパーマリンク形式（/src/commit/<sha>/）を優先してください。ブランチベースのリンクは、ファイルの移動やリファクタリング後に誤ったリンク先になることがあります。

注意事項

• extea は $PWD にある Git リモートからリポジトリを自動検出しますが、曖昧さを避けるため、必ず -l <login> と -r owner/repo を明示的に指定してください。
• ボードコマンドにはパスワードが必要です（extea login add で設定に保存するか、GITEA_PASSWORD 環境変数で指定します）。標準の tea コマンドでは API トークンのみを使用します。
• リポジトリ内では PR と課題で同じ番号の連番が使われます。#6 として作成された PR には、extea comment ... 6 でコメントできます。
• extea milestones close には、ID ではなく文字列としてマイルストーンのタイトルを指定します。
• extea pulls merge はマージ済みの PR で失敗しても何も表示しないことがあります。確実性を高めるため、必ず API 形式を使用してください。