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

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

ベータ版だった `GitHub CLI` こと <code>[gh](https://github.com/cli/cli)</code> コマンドが [2020/09/17 に v1.0.0](https://github.blog/2020-09-17-github-cli-1-0-is-now-available/) になり、**`release` コマンドが使える**ようになりました！ :tada:

これで、今まで <code>[hub](https://github.com/github/hub)</code> コマンドでリリースしていたものが、`gh` コマンドで統一できます。助かる。ついでに、`release` コマンドの日本語訳も TS; DR に載せました。

## TL; DR <sub><sup><sub><sup>（今北産業）</sup></sub></sup></sub>

```bash:リリースの基本構文
gh release create <gitタグ|SHAコミットID> [ <添付ファイル>... ] [ フラグ ]

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

```bash:リリース済みに追っかけ添付の基本構文
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](https://github.blog/2020-09-17-github-cli-1-0-is-now-available/) @ GitHub Blog
- 対応プラットフォーム
    - Linux/macOS/Windows
- インストール方法
    - [installation](https://github.com/cli/cli#installation) | CLI | CLI @ GitHub （`brew` `port` `scoop` `choco` etc.）
    - ラズパイ（Raspbian/RaspberryPi OS）<br>`software-properties-common` が使えないラズパイに `gh` をインストールする方法（[最新情報](https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian-ubuntu-linux-apt)）

    ```bash: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 <sub><sup><sub><sup>（`gh release` の基本を理解するコマケーこと）</sup></sub></sup></sub>

`gh`（GitHub CLI）コマンドは、コミットのリリースだけでなく、[全ての GitHub API 操作もコマンドでできる](https://github.blog/2020-09-17-github-cli-1-0-is-now-available/#make-github-cli-your-own-with-aliases-and-gh-api)など、機能は盛りだくさんです。しかし、この記事では**コマンドで GitHub にリリースする**ことに注力します。全体像をつかみたい場合は、以下の記事がためになります。

- [GitHub CLI 1.0 主要コマンドのサブコマンド、オプションまとめ](https://qiita.com/JIIO/items/06f8a1f6c7458e8a476c) @ Qiita

### 認証（ログイン）

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

```bash:対話式でログイン
gh auth login
```

<details><summary>ログインの仕方やスクリプトで認証する方法</summary><div><br>

CI やスクリプトなどで使う場合は、あらかじめ `GITHUB_TOKEN`（[パーソナル・アクセストークン](https://docs.github.com/ja/github/authenticating-to-github/creating-a-personal-access-token)） を発行して、環境変数などに設定しておく必要があります。

:::note info
2023/03/13 現在、GitHub のアクセス及び API 操作に [2FA（2 要素認証）が義務化されました](https://github.blog/2023-03-09-raising-the-bar-for-software-security-github-2fa-begins-march-13/)。パーソナル・アクセス・トークンの発行前に、2FA を有効化しておいてください。
:::

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

```bash:パーソナル・アクセス・トークンをパイプ渡しで指定する例
echo $MY_GITHUB_TOKEN | gh auth login --with-token
```
```bash:パーソナル・アクセス・トークンをファイル渡しで指定する例
gh auth login --with-token < mytoken.txt
```

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

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

```shell-session: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
```

![スクリーンショット 2020-09-18 11.26.40.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/78776/5803fcce-a65a-7a73-026a-3ef07f2f7a34.png)

</div></details>

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

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

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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` の基本

```shell-session: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

```