attest build provenance
v1.4.4
actions/attest-build-provenanceワークフロー アーティファクトの署名付きビルド来歴証明書を生成します。 @actions/attest パッケージによって内部的に動作します。
証明書は、in-toto 形式を使用して、一部のサブジェクト (名前付きアーティファクトとそのダイジェスト) を SLSA ビルド来歴述語にバインドします。
有効期間が短い Sigstore 発行の署名証明書を使用して、検証可能な署名が証明書に対して生成されます。 GitHub Actions ワークフローを開始するリポジトリがパブリックの場合、Sigstore のパブリックグッド インスタンスが構成証明署名の生成に使用されます。リポジトリがプライベート/内部の場合、GitHub プライベート Sigstore インスタンスが使用されます。
証明書が作成され、署名されると、GH 証明書 API にアップロードされ、ワークフローが開始されたリポジトリに関連付けられます。
証明書は、GitHub CLI のattestationコマンドを使用して検証できます。
アーティファクト証明書の詳細については、「アーティファクト証明書を使用してビルドの出所を確立する」を参照してください。
GitHub Actions ワークフロー内で、証明したいアーティファクトを構築します。
次の権限が設定されていることを確認してください。
permissions :
id-token : write
attestations : write id-token権限により、Sigstore 署名証明書を要求するために必要な OIDC トークンを作成する機能がアクションに与えられます。証明書を永続化するには、 attestations許可が必要です。
アーティファクトが構築された後、ワークフローに以下を追加します。
- uses : actions/attest-build-provenance@v1
with :
subject-path : ' <PATH TO ARTIFACT> ' subject-pathパラメーターは、証明書を生成するアーティファクトを識別する必要があります。
action.yml を参照してください。
- uses : actions/attest-build-provenance@v1
with :
# Path to the artifact serving as the subject of the attestation. Must
# specify exactly one of "subject-path" or "subject-digest". May contain a
# glob pattern or list of paths (total subject count cannot exceed 2500).
subject-path :
# SHA256 digest of the subject for the attestation. Must be in the form
# "sha256:hex_digest" (e.g. "sha256:abc123..."). Must specify exactly one
# of "subject-path" or "subject-digest".
subject-digest :
# Subject name as it should appear in the attestation. Required unless
# "subject-path" is specified, in which case it will be inferred from the
# path.
subject-name :
# Whether to push the attestation to the image registry. Requires that the
# "subject-name" parameter specify the fully-qualified image name and that
# the "subject-digest" parameter be specified. Defaults to false.
push-to-registry :
# Whether to attach a list of generated attestations to the workflow run
# summary page. Defaults to true.
show-summary :
# The GitHub token used to make authenticated API requests. Default is
# ${{ github.token }}
github-token :| 名前 | 説明 | 例 |
|---|---|---|
bundle-path | 生成された証明書を含むファイルへの絶対パス | /tmp/attestation.jsonl |
証明書は、JSON シリアル化された Sigstore バンドル形式で保存されます。
複数のサブジェクトが同時に証明される場合、各証明は出力ファイルの別の行に書き込まれます (JSON Lines 形式を使用)。
同時に証明できる被験者は 2500 人までです。サブジェクトはバッチ 50 で処理されます。最初の 50 グループの後、後続の各バッチでは、構成証明 API の過大な負荷を避けるために、指数関数的に増加する遅延 (バッチごとの遅延の上限は 1 分) が発生します。
基本的な使用例では、 attest-build-provenanceアクションをワークフローに追加し、証明書を生成するアーティファクトへのパスを指定するだけです。
name : build-attest
on :
workflow_dispatch :
jobs :
build :
permissions :
id-token : write
contents : read
attestations : write
steps :
- name : Checkout
uses : actions/checkout@v4
- name : Build artifact
run : make my-app
- name : Attest
uses : actions/attest-build-provenance@v1
with :
subject-path : ' ${{ github.workspace }}/my-app '複数のアーティファクトを生成している場合は、 subject-pathの入力でワイルドカードを使用して、それぞれの出自証明書を生成できます。
- uses : actions/attest-build-provenance@v1
with :
subject-path : ' dist/**/my-bin-* 'サポートされているワイルドカードと動作およびドキュメントについては、ファイルの検索に内部的に使用される @actions/glob を参照してください。
あるいは、カンマまたは改行で区切られたリストを使用して、複数の件名を明示的にリストすることもできます。
- uses : actions/attest-build-provenance@v1
with :
subject-path : ' dist/foo, dist/bar ' - uses : actions/attest-build-provenance@v1
with :
subject-path : |
dist/foo
dist/barコンテナー イメージを操作する場合、 subject-nameおよびsubject-digest入力を使用してアクションを呼び出すことができます。
push-to-registryオプションを使用して証明書をコンテナー レジストリに発行する場合は、 subject-name完全修飾イメージ名 (例: 「ghcr.io/user/app」または「acme.io/user/app」) を指定することが重要です。 azurecr.io/user/app」)。イメージ名の一部としてタグを含めないでください。証明される特定のイメージは、提供されたダイジェストによって識別されます。
証明バンドルは、Cosign Bundle 仕様に従って OCI レジストリに保存されます。
注: Docker Hub にプッシュする場合は、イメージ名のレジストリ部分として「index.docker.io」を使用してください。
name : build-attested-image
on :
push :
branches : [main]
jobs :
build :
runs-on : ubuntu-latest
permissions :
id-token : write
packages : write
contents : read
attestations : write
env :
REGISTRY : ghcr.io
IMAGE_NAME : ${{ github.repository }}
steps :
- name : Checkout
uses : actions/checkout@v4
- name : Login to GitHub Container Registry
uses : docker/login-action@v3
with :
registry : ${{ env.REGISTRY }}
username : ${{ github.actor }}
password : ${{ secrets.GITHUB_TOKEN }}
- name : Build and push image
id : push
uses : docker/[email protected]
with :
context : .
push : true
tags : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
- name : Attest
uses : actions/attest-build-provenance@v1
id : attest
with :
subject-name : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
subject-digest : ${{ steps.push.outputs.digest }}
push-to-registry : true
