ghコマンドにより、開発者はPull Request、Issue、Gistなどを管理するために、コマンドラインでGitHubが使えるようになりました。1.9.0では、GitHubのさらに多くの機能をターミナルで利用できます。それが、GitHub Actionsです。

Mislav氏が最近のブログで紹介したとおり、GitHub Actions内でghを使うことは既にできるようにになっています。さらに、今回新たに追加された2つのトップレベルのコマンド、gh runとgh workflowにより、ローカルターミナルからワークフローの実行やファイルに関する情報を簡単に取得できるようになりました。

ワークフローの実行状況を把握する

正しいコードを書こうと努めても、ビルドがエラーになることはあります。オープンなPull Requestに対するエラーを把握するにはgh pr checksが有効ですが、リポジトリ全体のワークフローの実行状況を把握するには役立ちません。新しいgh run listでは、Push、Pull Request、webhook、あるいはマニュアルでのイベント実行のどちらでトリガーされたかにかかわらず、あらゆる種類のワークフロー実行の概要を把握できます。

また、進行中のワークフローをより簡単に把握できるよう、gh run watchを作成しました。この機能では、ワークフローの実行を追跡したり、他のツールと組み合わせて実行の終了を通知したりすることができます。gh run watchをUbuntuのnotify-sendのようなコマンドと組み合わせれば、キーボードから離れて他の作業に時間を費やすことができます。

実行が終了すると、このように知らせてくれます。

1件の実行を詳しく調べるにはgh run viewを使います。任意でジョブの個々のステップについても詳しく調べることができます。たとえば、あるコードで文法チェッカーが失敗した理由を把握するには以下のようにします。

それでもわからないエラーの場合は、grepなどのツールとgh run view --logを組み合わせて、実行のログ出力全体を検索します。これはビルドマトリックス全体のエラーをデバッグするのに役立ちます。たとえば以下の場合、UbuntuとmacOSでパニックが起きていますが、Windowsでは起きていないことがわかります。

また、--logでは情報が多すぎる場合、gh run --log-failedを使うと、エラーになった各ステップのログ行のみが出力されます。自分でgrepを実行しなくても、エラーになったステップのログにすぐにアクセスできるためとても便利です。たとえば、ここでは--log-failedを使って、すべてのステップのログ出力ではなく、エラーになったステップのログ出力のみを見ています。

gh runは、ワークフローの実行中に生成されたアーティファクトについても把握しており、その発見や取得に役立ちます。

アーティファクトをダウンロードするには、gh run download -n tps-reportで名前を指定するか、インタラクティブなセレクターを使用します。

最後に、実行の断続的なエラーが疑われる場合やエラーが発生する箇所を確認したい場合は、gh run rerunを使ってターミナルから退出せずに再実行できるようになりました。

ワークフローファイルの管理も簡単に

GitHub Actionsでの実行は、リポジトリの.github/workflowsにあるYAML形式のワークフローファイルで定義します。ワークフローファイルには、ワークフローの名前、動作、ワークフローを実行させるイベントの種類などを記述します。

gh workflow viewを使うと、最近実行されたワークフローの概要を確認し、ワークフローを期待どおりに動作させることができます。gh workflow view --yamlを使うと、ワークフローの処理内容を色付きで表示できます。

時には、ワークフローが中断したり、処理中であったりする場合があります。そのようなワークフローをリポジトリから完全に削除しなくても管理できるようにするため、gh workflow enableとgh workflow disableが使えるようになりました。

多くのワークフローは、Pull RequestやPushされたブランチによって実行がトリガーされますが、workflow_dispatchイベントを使うと、コマンドでワークフローファイルを実行できます。

コマンドでワークフローを実行してリポジトリのクリーンアップタスクを行ったり、作業がまだ進行中の段階でワークフローの手動Dispatchを設定したりすることもできます。gh workflow runを使って、このイベントに対応したワークフローをコマンドラインから起動できるようになったため、workflow_dispatchワークフローの操作やスクリプト作成がより簡単になりました。

gh workflow runがワークフローファイルの開発にどのように役立つかについて、ツールチェーンに組み込む例をご紹介します。受信したPull Requestが特定の条件を満たしていることを確認する自動化を実行したいと思います。ここではpr-check.ymlというワークフローファイルを使って、受信したPull Requestに本文があるかどうかをチェックします。

name: Pull Request Check

on:
  workflow_dispatch:
    inputs:
      body:
        default: ""
      test:
        default: "false"
  pull_request_target:

jobs:
  check-body-length:
    runs-on: ubuntu-latest
    steps:
      - name: check
        env:
          PRNUM: ${{ github.event.pull_request.number }}
          PRBODY: ${{ github.event.pull_request.body }}
          TESTBODY: ${{ github.event.inputs.body }}
          TEST: ${{ github.event.inputs.test }}
        run: |
          if [ "$TEST" = "true" ]
          then
            PRBODY=$TESTBODY
          fi

          commentPR () {
            if [ "$TEST" = "true" ]
            then
              echo "would comment: '${1}'"
            else
              gh pr comment $PRNUM -b "${1}"
            fi
          }

          if [ "$PRBODY" = "" ]
          then
            commentPR "Thanks! Please add a body so we can better review your contribution."
          fi

(このファイルをGistで見る)

これはpull_request_targetとworkflow_dispatchの両方に応答します。つまり、リポジトリでPull Requestがオープンされたり、手動で起動されたりすると、常に実行されます。

手動で起動された場合は、モックPull Requestの本文をチェックするテスト入力を受け取ります。以下のように実行します。

gh run view --logの出力を見て、コードが期待どおりの動作をしているかどうかを確認できます。コマンドラインを使っているため、このプロセスをさらにスクリプト化したり、エイリアスを使って効率化したりすることができます。

仕事をしながらターミナルからプログラムでこのワークフローを実行できるため、if [ $PRBODY = true ]条件を変更してもっと複雑なことができるようにしたいと考えています。

ご意見をお寄せください

gh runやgh workflowを使ってどんなことができるか、ディスカッションフォーラムでお知らせください！皆さんからのフィードバックをお待ちしています。GitHub CLIをまだお使いでない方は、ぜひインストールしてください。

将来的には、ワークフローファイルの作成やデプロイをより簡単にできるようにしたいと考えています。今のところは、GitHub 1.9.0のすべての新機能をお楽しみいただければと思います。