[GitHub Actions] Deployments APIを通してCDトラブル調査に役立つGitHub Deploymentsを使ってみた

GitHub APIのDeploymentsを手軽に使えるActionのGithub Deploymentsに触ってみました。Deployments APIを使うとWorkflowからDeploy記録に絞ったタイムラインが生成され、トラブル発生時の調査コスト削減にも繋がりそうです。
2020.07.29

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

GitHub APIにはDeploymentsという機能があり、リクエストされたデータを蓄積し、時間を追って可視化することができます。

ただ、このAPIは様々なリクエストに柔軟な対応が出来ることもあり、個人的に取っつきにくい印象がありました。今回使ったActionのGitHub Deploymentsは用途を限定することで使い方を明確にしています。

実際の使い方や注意点についてまとめました。

Deploymentsを利用するメリット

CD時に反映するコミットステータスをAPIへリクエストする事でDeploymentsデータと定義し、データをActivityLogとしてタイムライン表示してくれます。

Deploymentsデータを時間毎に可視化することによるメリットは、使い方を見るとわかりやすいと思います。

ActivityLogを利用した調査

Deploymentsデータが蓄積されると、codeタブの右側カラム下にEnvironmentsが表示されます。公式ドキュメントによるとタブメニューとなっているようですが、おそらくUI更新によるものだと思われます。

Environmentsを選択するとDeployした記録のみが表示されます。

デプロイ環境毎に表示切り替えも可能です。

この記録からデプロイされたコミットログ、及びActionsでCIが動作した時のログを直接開く事が可能です。Deploy後に環境でエラーが発生した際、反映されたコミットの調査でCIログを検索する手間が省けるわけです。

GitHub Deploymentsを設定する

このActionは受け付けるデータについて、3つのstepに絞ることで利便性を上げています。

対象step 想定するタイミング 用途
start Deploy開始 Deployの開始
finish Deploy終了 Deployの完了
deactivate-env PRクローズ PR済みブランチ削除

使い方はenvに環境名を指定し、それ以外は既定パラメータを指定するのみで、secretsへ追加設定は要りません。

jobs:
  deploy:
    steps:
    - name: start deployment
      uses: bobheadxi/deployments@master
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release
   - name: do my deploy
    # ...

    - name: update deployment status
      uses: bobheadxi/deployments@master
      if: always()
      with:
        step: finish
        token: ${{ secrets.GITHUB_TOKEN }}
        status: ${{ job.status }}
        deployment_id: ${{ steps.deployment.outputs.deployment_id }}

step:startにてwith:env:に指定した値が、ActivityLogで環境切り替えの選択肢となります。

注意点

with:に指定するパラメータが不足すると以下のようにエラーとなります。

##[error]unexpected error encounterd: Input required and not supplied: token

難点は、step:finishの時に発生すると、既に動作していないのにActivityLog上ではIn progressと表示され続けるところです。

なお、事前にset-envで環境変数を指定していた場合は以下のような警告が表示されますが、特に動作には問題ありません。

##[warning]Unexpected input(s) 'env', valid inputs are ['token', 'step', 'auto_inactive', 'logs', 'desc', 'ref']

あとがき

Deployments APIだけを見ると、何をやりたいのか正直分かり辛いという感想しかないのですが、Deployments Actionを通す事で明確になる感じでした。

ActivityLogの使い慣れてくると今回のActionでは満足し難くなるかもしれませんが、その際はDeployments APIに沿って目的に応じたstepの独自実装が必要になるかと思われます。

参考リンク