Latchkey のステップ

Latchkey のステップの実行のしかた#

Latchkey はワークフローファイルをコンパイルするときに、ステップのコマンドをプランにコピーします。ステップはジョブの 1 ステップとして、ジョブのランナー上で、ジョブの env: とともに実行されます。プランにはステップのバージョンとダイジェストが記録されます。公開されたバージョンは変わらないため、同じコミットは再実行でも常に同じコマンドを実行します。

latchkey/setup-node は NPM_CONFIG_PREFIX を設定し、latchkey/setup-python は仮想環境の bin を PATH の末尾に加え、latchkey/setup-java は JAVA_HOME を設定します。いずれも、そのステップより前のステップも含めて、ジョブのすべてのステップに適用されます。ワークフローファイルが env: で設定した変数は、ワークフロー、ジョブ、ステップのどの env: であっても、Latchkey のステップが設定する変数より優先されます。2 つの Latchkey のステップが同じ変数を設定するときは、後のステップの値が使われます。スキップされたステップも変数は設定するため、この 3 つのステップには if: を書けません。一部の実行でだけ使うには、ステップを専用のジョブに置き、そのジョブに if: を書いてください。複数のバージョンを使うには、matrix でバージョンを選んでください。

書き方#

ステップは name:、uses:、with:、env:、if: を取り、run: か uses: のどちらか一方を実行します。両方は書けません。with: の下には、各入力をそのままの値か matrix の値で書くか、${{ needs.<job>.outputs.<name> }} 全体として書くか、ジョブの environment: と同じように、実行のブランチでそのままの値を選ぶブランチのマップで書きます (ワークフローファイル を参照)。シークレットは with: には書きません。シークレットは run: ステップと同じく、そのステップの env: から読み取ります。

バージョンは完全に固定してください。@1、@latest、バージョンなしは拒否され、拒否のメッセージに公開済みのバージョンが示されます。

latchkey/cache-restore#

Latchkey のキャッシュエントリを 1 つディレクトリに復元します。キャッシュミスのときは何も復元せず、ジョブはそのまま続きます。入力は key (必須。英字、数字、.、_、- の 1 から 200 文字)、version (必須。同じ文字で 1 から 64 文字。バージョンが違えば別のエントリです)、into (既定値 .。ワークスペース内のパス、またはホームディレクトリを表す ~) です。

バージョン 1.1.0 は hash-files も受け取ります。説明は latchkey/cache-save の項にあります。

latchkey/cache-save#

パスを Latchkey のキャッシュエントリ 1 つに保存します。同じエントリがすでにあるときはそれが保持され、ジョブはそのまま続きます。入力は key と version (必須。latchkey/cache-restore と同じ)、from (既定値 .。パスの基準になるディレクトリで、ワークスペース内またはホームディレクトリ内)、path (必須。from 内のパスを 1 つ以上、スペース区切りで) です。

どちらのステップも latchkey cache restore と latchkey cache save と同じキャッシュを使います。キャッシュはリポジトリとブランチごとに分けられ、他のブランチはデフォルトブランチのキャッシュを読み取れ、エントリは 14 日間保持されます。フォークからのプルリクエストにはキャッシュが提供されないため、そのステップは何も復元せず何も保存しませんが、ジョブはそのまま続きます。

各ステップのバージョン 1.1.0 は hash-files も受け取ります。リポジトリで追跡されているファイルのパターンを、スペース区切りで指定します。ステップはそれらのコミットされた内容のハッシュを key の末尾に追加するため、GitHub の hashFiles() をキーに使う場合と同じく、ロックファイルが変わると新しいエントリになります。追跡されているファイルに一致しないパターンでも、毎回同じキーになります。

latchkey/setup-node#

ランナーの Node と npm を、ランナーイメージにあるバージョンに切り替えます。以降のすべてのステップに適用されます。入力は node-version (必須。22、22.23、22.23.3 など。メジャーまたはメジャーとマイナーを指定すると、イメージにあるそのうち最新のバージョンになります) です。イメージにないバージョンはステップを失敗させ、ステップはイメージにあるバージョンを示します。バージョン 1.0.1 はフォークからのプルリクエストのジョブでも動作しますが、バージョン 1.0.0 はそこで失敗します。

latchkey/setup-python#

ランナーイメージにある Python のバージョンから ~/.latchkey/venv に仮想環境を作り、以降のすべてのステップで python、python3、pip、pip3 をその仮想環境のものに切り替えます。そのため、そのままの pip install は仮想環境にインストールされます。パッケージがインストールするコマンドなど、仮想環境のコマンドはイメージ自身のコマンドの後ろで PATH に入るため、同じ名前のコマンドがイメージにあればイメージのものが実行されます。入力は python-version (必須。3.12 や 3.13 などのマイナーバージョン。イメージにはそれぞれ 1 つのリリースがあります) です。イメージにないバージョンはステップを失敗させ、ステップはイメージにあるバージョンを示します。イメージ自身の Python は変更されず、仮想環境の中では pip install --user は拒否されます。

latchkey/setup-go#

ランナーの Go を、ランナーイメージにあるバージョンに切り替えます。以降のすべてのステップに適用されます。入力は go-version (必須。1.25、1.25.8 など。マイナーを指定すると、イメージにあるそのうち最新のパッチになります) です。イメージにないバージョンはステップを失敗させ、ステップはイメージにあるバージョンを示します。フォークからのプルリクエストのジョブは sudo を使えないため、そこではステップが失敗します。

latchkey/setup-java#

ランナーの Java を、ランナーイメージにある Temurin JDK に切り替えます。以降のすべてのステップに適用され、JAVA_HOME はジョブ全体でその JDK を指します。入力は java-version (必須。17 や 21 などのメジャーバージョン) です。イメージにないバージョンはステップを失敗させ、ステップはイメージにあるバージョンを示します。フォークからのプルリクエストのジョブは sudo を使えないため、そこではステップが失敗します。

latchkey/npm-publish#

directory (既定値 .) のパッケージを、NODE_AUTH_TOKEN のトークンで公開します。トークンはステップの env: でシークレットから設定し、ステップがそこから読み取ります。入力は tag (既定値 latest)、access (public または restricted)、dry-run (既定値 false)、registry (既定値 https://registry.npmjs.org/) です。トークンがないとき、dry-run が true でなければステップは失敗します。フォークからのプルリクエストのジョブにはシークレットが渡されないため、そこでは dry-run: true のときだけ実行でき、何も公開されません。

latchkey/docker-build-push#

context (既定値 .) のイメージを file (既定値はその Dockerfile) からビルドし、tags (必須。スペース区切り) のすべての参照でタグ付けします。push: true ならそれらを push し、既定値の false なら以降のステップのためにイメージをランナーの Docker に読み込みます。username を設定すると、ステップの env: の DOCKER_PASSWORD のパスワードで registry (既定値は Docker Hub) にログインします。フォークからのプルリクエストのジョブは Docker を使えないため、そこではステップが失敗します。

latchkey/aws-login#

ジョブの Latchkey の ID トークンを使って、ジョブを IAM ロールとして AWS にサインインさせます。以降のすべてのステップに適用されます。入力は role-to-assume (必須。ロールの ARN)、aws-region (必須)、role-session-name (既定値 latchkey)、role-duration-seconds (既定値 3600。900 から 43200 で、ロールの最大セッション時間以下) です。ロールは、オーディエンス sts.amazonaws.com で、リポジトリに対する Latchkey の発行者を信頼している必要があります。トライアル実行と、ジョブのパイプラインがトライアル中のときは、ジョブの ID トークンの sub が advisory: で始まるため、ライブ実行向けに書いた信頼には一致しません。以降のステップの AWS CLI と SDK はジョブの AWS 設定からロールを読み取り、古い認証情報が期限切れになる前に新しいものを取得するため、長いジョブも動き続けます。どのステップの環境にもキーは入らず、ステップは環境変数を設定しません。リージョンは AWS_REGION ではなく AWS 設定にあります。環境変数からしか AWS の認証情報を読まないツールは、このステップから認証情報を受け取りません。フォークからのプルリクエストのジョブには ID トークンがないため、そこではステップが失敗します。

latchkey/artifact-upload#

パスをこの実行のアーティファクト 1 つとしてアップロードし、このジョブを必要とするジョブに渡します。入力は name (必須。英字、数字、.、_、- の 1 から 128 文字で、. と .. は不可)、from (既定値 .。パスの基準になるディレクトリで、ワークスペース内またはホームディレクトリ内)、path (必須。from 内のパスを 1 つ以上、スペース区切りで)、include-hidden-files (既定値 false) です。アーティファクトは各パスを from の下にあるとおりに保存するため、ディレクトリの中身をアップロードするには、from をそのディレクトリに、path を . にします。名前がドットで始まるファイルとディレクトリは、include-hidden-files が true でない限り含まれません。それらを指定したアップロードと、通常のファイルが 1 つもないアップロードは失敗します。

latchkey/artifact-download#

このジョブの needs: に指定したジョブがアップロードしたアーティファクトを 1 つダウンロードし、ディレクトリに展開します。入力は name (必須) と into (既定値 .。ワークスペース内またはホームディレクトリ内のパスで、なければ作られます) です。アーティファクトは展開の前にアップロードされたものと照合され、into の外を指すパスを含むものは拒否され、何も展開されません。

どちらのステップも latchkey artifact upload と latchkey artifact download と同じアーティファクトを使い、名前と上限も同じで、アーティファクトは 7 日間保持されます (ワークフローファイル を参照)。キャッシュのステップと違い、アップロードやダウンロードが失敗するとステップが失敗します。フォークからのプルリクエストのジョブはアーティファクトを使えないため、どちらのステップもそこでは失敗します。

Latchkey が拒否するもの#

Latchkey は読めないステップを無視して実行するのではなく、ファイルを拒否して行番号を示します。拒否されるのは、latchkey/ 以外の uses:、公開されていないステップ名、完全に固定されていないか公開されていないバージョン、不足している入力・知らない入力・規則に合わない入力、1 つのステップでの run: と uses: の併記、run: ステップの with: です。拒否のメッセージは、代わりに何を書けばよいかを示します。