コマンドラインで GitHub リリースしたり、リリース先にファイルを添付したい

ベータ版だった GitHub CLI こと gh コマンドが 2020/09/17 に v1.0.0 になり、release コマンドが使えるようになりました！

これで、今まで hub コマンドでリリースしていたものが、gh コマンドで統一できます。助かる。ついでに、release コマンドの日本語訳も TS; DR に載せました。

TL; DR _{^{_{^{（今北産業）}}}}

リリースの基本構文

gh release create <gitタグ|SHAコミットID> [ <添付ファイル>... ] [ フラグ ]

# 例）
# $ git tag
# v1.0.0-alpha
# v1.0.0
# $ gh release create v1.0.0

リリース済みに追っかけ添付の基本構文

gh release upload <gitタグ> <添付ファイル>... [ フラグ ]

# 例）
# $ gh release upload v1.0.0 ./artifacts/my_app_win.zip ./artifacts/my_app_mac.zip

GitHub CLI 1.0 is now available @ GitHub Blog
対応プラットフォーム
- Linux/macOS/Windows

インストール方法

installation | CLI | CLI @ GitHub （brew port scoop choco etc.）
ラズパイ（Raspbian/RaspberryPi OS）
software-properties-common が使えないラズパイに gh をインストールする方法（最新情報）

Install_gh_for_raspi.sh（add-apt-repository未使用）

#!/bin/bash
# apt に ubuntu.com の GPG 公開鍵とキーサーバーを追加
sudo apt-key --keyring /usr/share/keyrings/githubcli-archive-keyring.gpg adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
# github-cli2 のリストに arm アーキテクチャを追加
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/github-cli2.list > /dev/null
# apt のアップデートとインストール
sudo apt update
sudo apt install -y gh

TS; DR _{^{_{^{（gh release の基本を理解するコマケーこと）}}}}

gh（GitHub CLI）コマンドは、コミットのリリースだけでなく、全ての GitHub API 操作もコマンドでできるなど、機能は盛りだくさんです。しかし、この記事ではコマンドで GitHub にリリースすることに注力します。全体像をつかみたい場合は、以下の記事がためになります。

GitHub CLI 1.0 主要コマンドのサブコマンド、オプションまとめ @ Qiita

認証（ログイン）

API の操作も可能になったため、使用前に gh auth login で認証が必要です。

対話式でログイン

gh auth login

ログインの仕方やスクリプトで認証する方法

CI やスクリプトなどで使う場合は、あらかじめ GITHUB_TOKEN（パーソナル・アクセストークン）を発行して、環境変数などに設定しておく必要があります。

2023/03/13 現在、GitHub のアクセス及び API 操作に 2FA（2 要素認証）が義務化されました。パーソナル・アクセス・トークンの発行前に、2FA を有効化しておいてください。

その際、スクリプト内にトークンを（コミットにトークンを）埋め込まないように注意してください。

パーソナル・アクセス・トークンをパイプ渡しで指定する例

echo $MY_GITHUB_TOKEN | gh auth login --with-token

パーソナル・アクセス・トークンをファイル渡しで指定する例

gh auth login --with-token < mytoken.txt

通常使用する（ローカルでコマンドラインで叩く）場合は、ブラウザで認証するのが楽で安全です。

その場合、gh auth login と打つと途中で one-time code がコンソールに表示されます。ブラウザが立ち上がり認証を求められるので one-time code の値を入力します。

ghコマンドの認証

$ gh auth login
? What account do you want to log into? GitHub.com
- Logging into github.com
? How would you like to authenticate? Login with a web browser

! First copy your one-time code: XXXX-XXXX  ← これを控える
- Press Enter to open github.com in your browser... ← ここで下図の認証画面に飛ばされる
✓ Authentication complete. Press Enter to continue...

? Choose default git protocol HTTPS
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as KEINOS

`gh` の基本（日本語訳ヘルプ）

[ ] は必須ではない項目です。

gh日本語訳ヘルプ

$ gh --help
コマンドラインから GitHub の操作を行います。

使い方
  gh <コアコマンド> <サブコマンド> [ フラグ ]

コアコマンド
  gist:       新規 gist を作成します。
  issue:      新規 issue を作成します。
  pr:         プルリクエストを操作します。
  release:    GitHub リリースを操作します。
  repo:       リポジトリの作成、クローン、フォーク、閲覧を行います。

サブコマンド
  alias:      コマンドのショートカット（エイリアス）作成します。
  api:        GitHub API の（認証込み）リクエストを実行します。
  auth:       ログイン／ログアウト／更新を行います。
  completion: シェルの入力補完用スクリプトの作成します。
  config:     gh コマンドの設定を変更します。
  help:       コアコマンドのヘルプを表示します。

フラグ
  --help      コマンドのヘルプを表示します。
  --version   gh のバージョンを表示します。

使用例
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

環境変数
  'gh help environment' で利用可能な環境変数一覧を表示します。

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

フィードバック／不具合報告
  'gh issue create -R cli/cli' で issue を作成してください。

`gh release` の基本

gh-release日本語訳ヘルプ

$ gh release --help
GitHub リリースを操作します。

使い方
  gh release <サブコマンド> [ フラグ ]

サブコマンド
  create:     新規リリースを作成します。
  delete:     既存のリリースを削除します。
  download:   リリース先の添付ファイル（assets）をダウンロードします。
  list:       リポジトリのリリース一覧を表示します。
  upload:     リリース先（assets）にファイルをアップロードします。
  view:       リリース情報を表示します。

フラグ
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

継続フラグ
  --help   コマンドのヘルプを表示

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release create` の基本

gh-release-create日本語訳ヘルプ

$ gh release create --help
リポジトリの新規 GitHub リリースを作成します。

複数の Asset（添付）ファイルも同時に指定できます。
添付ファイルの表示ラベルを指定する場合は、ファイル名の後に '#<ラベル名>' を指定します。

使い方
  gh release create <gitタグ> [ <ファイル>... ] [ フラグ ]

フラグ
  -d, --draft             ドラフトとして仮保存します。
  -n, --notes string      リリース・ノートを指定します。
  -F, --notes-file file   リリース・ノートをテキスト・ファイルで指定します。
  -p, --prerelease        プレ・リリース版としてリリースします。
      --target branch     リリースする対象ブランチもしくは SHA コミット ID を指定します(デフォルト: main ブランチ)
  -t, --title string      リリースのタイトルを指定します。

継続フラグ
  --help   コマンドのヘルプを表示

使い方
  # ファイルでリリース・ノートを指定する
  $ gh release create v1.2.3 -F changelog.md
  
  # リリースと同時にラベル付きでファイルを添付する
  # upload a release asset with a display label
  $ gh release create v1.2.3 '/path/to/asset.zip#My display label'

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release delete` の基本

gh-release-delete日本語訳ヘルプ

$ gh release delete --help
GitHub リリースを削除します。

使い方
  gh release delete <gitタグ名> [ フラグ ]

フラグ
  -y, --yes   確認プロンプトをスキップします。

継続フラグ
      --help              コマンドのヘルプを表示します。
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release download` の基本

gh-release-download日本語訳ヘルプ

$ gh release download --help
GitHub リリースから Asset（添付）ファイルをダウンロードします。

git タグ名が指定されていない場合は、プロジェクト内の最新リリースからダウンロードされます。
その場合は '--pattern' フラグの指定が必要です。

使い方
  gh release download [ <gitタグ> ] [ フラグ ]

フラグ
  -D, --dir string            ファイルのダウンロード先のパスを指定します。 (デフォルト ".")
  -p, --pattern stringArray   'glob' パターンにマッチした添付ファイルのみダウンロードします。

継続フラグ
      --help              コマンドのヘルプを表示します。
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

使用例
  # 特定のリリースから全ての添付ファイルをカレント・ディレクトリにダウンロードする
  $ gh release download v1.2.3
  
  # 最新リリースから Debian パッケージのみをカレント・ディレクトリにダウンロードする
  $ gh release download --pattern '*.deb'
  
  # 複数のパターンでファイルを指定する
  # specify multiple file patterns
  $ gh release download -p '*.deb' -p '*.rpm'

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release list` の基本

gh-release-list日本語訳ヘルプ

$ gh release list --help
リポジトリのリリース一覧を表示します。

使い方E
  gh release list [ フラグ ]

フラグ
  -L, --limit int   最大取得件数を指定します。 (デフォルト 30 件)

継続フラグ
      --help              コマンドのヘルプを表示します。
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release upload` の基本

gh-release-upload日本語訳ヘルプ

$ gh release upload --help
GitHub リリースに Asset（添付）ファイルをアップロードします。

表示のラベルを指定する場合は、ファイル名の後に '#<ラベル名>' を追加します。

使い方
  gh release upload <gitタグ> <ファイル>... [ フラグ ]

フラグ
  --clobber   同名の asset ファイルを上書きします。

継続フラグ
      --help              コマンドのヘルプを表示します。
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

`gh release view` の基本

gh-release-view日本語訳ヘルプ

$ gh release view --help
GitHub リリース情報を表示します。

git タグ名が指定されていない場合は、プロジェクト内の最新リリースからダウンロードされます。

使い方
  gh release view [ <gitタグ> ] [ フラグ ]

フラグ
  -w, --web   ブラウザでリリース・ページを開きます。

継続フラグ
      --help              コマンドのヘルプを表示します。
  -R, --repo OWNER/REPO   別のリポジトリを OWNER/REPO 形式で切り替えます。

もっと知る
  'gh <コマンド> <サブコマンド> --help' で、コマンドの詳しい情報が得られます。
  マニュアルを嫁 https://cli.github.com/manual

GitHub のリリースを gh コマンドで実行／操作する（GitHub CLI ^v1.0）

コマンドラインで GitHub リリースしたり、リリース先にファイルを添付したい

TL; DR （今北産業）

TS; DR （gh release の基本を理解するコマケーこと）

認証（ログイン）

gh の基本（日本語訳ヘルプ）

gh release の基本

gh release create の基本

gh release delete の基本

gh release download の基本

gh release list の基本

gh release upload の基本

gh release view の基本