GitHubは、Actions APIのパブリックベータ版のリリースを発表した。Actions APIを使えば、REST APIを通じてGitHub Actionsを管理することができる。APIの公開するエンドポイントで、アーティファクト、シークレット、ランナー、ワークフローの管理が可能だ。
GitHub Actionsは、プッシュ、イシューの生成、新リリースの作成といった、リポジトリイベントをベースとしたワークフローの自動化を可能にするものだ。ワークフローの作成はビジュアルエディタ経由か、あるいはYAMLコードを記述して行うことができる。昨年8月にリリースされたCI/CD for GitHub Actionsにより、サードパーティのサービスを使用せずに、GitHub内で直接ソフトウェアの構築やデプロイを行うことができるようになった。
ワークフローAPIでは、リポジトリに関連付けられたワークフローを見ることができる。全ワークフローを一覧したり、特定のワークフローを指定することが可能だ。例えば、次の要求に対して、
curl -u username:token \
"https://api.github.com/repos/my-org/hello-world/actions/workflows/72844"
hello-worldリポジトリ内のワークフロー72844に関する、以下のような詳細情報が返される。
{
"id": 72844,
"node_id": "MDg6V29ya2Zsb3cxNjEzMzU=",
"name": "CI",
"path": ".github/workflows/blank.yml",
"state": "active",
"created_at": "2020-01-08T23:48:37.000-08:00",
"updated_at": "2020-01-08T23:50:21.000-08:00",
"url": "https://api.github.com/repos/my-org/hello-world/actions/workflows/72844",
"html_url": "https://github.com/my-org/hello-world/blob/master/.github/workflows/72844",
"badge_url": "https://github.com/my-org/hello-world/workflows/CI/badge.svg"
}
ワークフローのラン(run)に関する詳細には、ワークフローランAPI経由でアクセスすることができる。GitHub Actionのワークフローランは、設定されたイベントに対して実行されるワークフローのインスタンスである。このAPIは、ランの視覚化、ランのログのレビュー、ワークフローの再トリガ、アクティブなランのキャンセルへのアクセスを可能にする。これらのエンドポイントでは、全体的な結果や期間など、ランに関するステータスへのアクセスが提供される。ワークフロージョブAPIでは、ログファイルを含むジョブの詳細にアクセスすることができる。
ワークフロー実行ログにアクセスするためのAPIルートは、ログファイルのアーカイブをダウンロードするためのリダイレクトURLを提供する。このリンクは、リポジトリの読み取りができれば誰でもアクセス可能だが、1分間後には無効になる。このURLはレスポンス内のロケーションヘッダとして提供される。次の例のように、CURLによるリクエストで、ヘッダを参照するために冗長出力を有効にして、ロケーション値へのリダイレクションを可能にする-Lを使用することで、ダウンロードが可能である。
curl -v -L -u username:token -o logs.zip /
"https://api.github.com/repos/my-org/my-repo/actions/runs/30209828/logs"
アーティファクトAPIでは、ワークフローアーティファクトに関する情報のダウンロード、削除、取得が可能である。アーティファクトは、ジョブ間でのデータ共有と、ワークフロー完了後のデータの永続化を行うためのものだ。
GitHub Actionsは、デフォルトではGitHubのサーバ上のDockerコンテナ内で実行されるが、ユーザ自身がホストするランナ(セルフホストランナ)もサポートされている。セルフホストランナでは、自分自身の環境にホストされたサーバ上でワークフローを実行することができる。セルフホストランナAPIでは、リポジトリ内のランナの一覧、指定したランナの取得、ランナの削除、ランナをオーソライズするために必要なトークン生成などが可能だ。これにより、ランナの生成とクリーンアップの自動化が可能になる。
新しいAPIエンドポイントの利便性を向上するために、GitHubでは、ランナのコンテキストに新たなデータを追加している。各Actionのランにrun_idとrun_numberが含まれるようになった。これらの値をワークフロースクリプトに含めることで、新たなAPIエンドポイントに、より簡単にインタラクションすることができる。
Actions APIは認証済みユーザ、OAuthアプリ、GitHubアプリで使用することができる。アクセストークンには、プライベートリポジトリにはrepoスコープ、公開リポジトリにはpubluc_repoスコープが必要だ。
GitHub Actions APIは、現在GitHub Actionsのアクセス可能なユーザであれば、誰でも使用することができる。GitHub ActionsはGitHubの価格プランのほとんどで利用可能であるが、古いper-repoプランを使用するアカウントの所持するリポジトリでは使用できない。APIはベータ版だが、GitHubでは、開発者からのフィードバックに基づいた変更について、同社のブログで公開する予定である。