GitHub Action
Notation Actions
This repository contains the implementation of GitHub Actions for Notation. It provides actions for signing and verifying OCI artifacts with Notation in CI/CD.
The following three actions are available:
setup: Install Notationsign: Sign OCI artifacts with a specified Notation pluginverify: Verify signatures with Notation trust store and trust policy
Note
The Notary Project documentation is available here. You can also find the Notary Project README to learn about the overall Notary Project.
Signing an image relies on a Notation plugin, such as AWS Signer plugin for Notation, Azure Key Vault for Notation, HashiCorp Vault plugin.
Currently, Azure Key Vault plugin for Notation has been well tested in the Notation Github Actions by the sub-project maintainers. See this doc for hands-on steps if you want to use Notation with the AKV plugin. You can submit test cases and examples for other plugins here.
- name: setup Notation CLI
uses: notaryproject/notation-action/setup@v1
with:
version: <version_of_official_Notation_CLI_release>
url: <url_of_customized_Notation_CLI>
checksum: <SHA256_of_the_customized_Notation_CLI>See an example (Click here).
- name: setup Notation CLI
uses: notaryproject/notation-action/setup@v1
with:
version: "1.2.0"- name: sign releasd artifact with signing plugin
uses: notaryproject/notation-action/sign@v1
with:
plugin_name: <notation_signing_plugin_name>
plugin_url: <plugin_download_url>
plugin_checksum: <SHA256_of_the_signing_plugin>
key_id: <key_identifier_to_sign>
target_artifact_reference: <list_of_target_artifact_references_in_remote_registry>
signature_format: <signature_envelope_format>
plugin_config: <list_of_plugin_defined_configs>
force_referrers_tag: <boolean_flag_for_referrers_tag_schema>
timestamp_url: <url_of_RFC_3161_Timestamp_Authority_server>
timestamp_root_cert: <filepath_of_RFC_3161_Timestamp_Authority_root_certificate>See an example (Click here).
- name: sign releasd artifact with notation-azure-kv plugin and timestamping
uses: notaryproject/notation-action/sign@v1
with:
plugin_name: azure-kv
plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.2.0/notation-azure-kv_1.2.0_linux_amd64.tar.gz
plugin_checksum: 06bb5198af31ce11b08c4557ae4c2cbfb09878dfa6b637b7407ebc2d57b87b34
key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd
target_artifact_reference: |-
myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa
signature_format: cose
plugin_config: |-
ca_certs=.github/cert-bundle/cert-bundle.crt
self_signed=false
timestamp_url: http://my.trusted.timestamp.authority.wabbit-networks.io
timestamp_root_cert: .github/cert-bundle/tsa-root.crtExample of using the Referrers API in signing:
- name: sign releasd artifact with notation-azure-kv plugin
uses: notaryproject/notation-action/sign@v1
with:
force_referrers_tag: 'false' # use referrers api first, if supported.
plugin_name: azure-kv
plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.2.0/notation-azure-kv_1.2.0_linux_amd64.tar.gz
plugin_checksum: 06bb5198af31ce11b08c4557ae4c2cbfb09878dfa6b637b7407ebc2d57b87b34
key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd
target_artifact_reference: |-
myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa
signature_format: cose
plugin_config: |-
ca_certs=.github/cert-bundle/cert-bundle.crt
self_signed=false- name: verify released artifact
uses: notaryproject/notation-action/verify@v1
with:
target_artifact_reference: <list_of_target_artifact_references_in_remote_registry>
trust_policy: <file_path_to_user_defined_trustpolicy.json>
trust_store: <dir_to_user_trust_store>Note
For Notation CLI v1.2.0 or later, verify always uses the Referrers API first, if Referrers API is not supported, automatically fallback to the Referrers tag schema.
See an example (Click here).
- name: verify released artifact
uses: notaryproject/notation-action/verify@v1
with:
target_artifact_reference: |-
myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa
trust_policy: .github/trustpolicy/trustpolicy.json
trust_store: .github/truststore[!NOTE]
.github/trustpolicy/trustpolicy.jsonMUST follow the Notation trust policy specs..github/truststoreMUST follow the Notation trust store specs. See an example of trust store below.
.github/truststore
└── x509
├── ca
│ └── <my_trust_store1>
│ ├── <my_certificate1>
│ └── <my_certificate2>
├── signingAuthority
| └── <my_trust_store2>
| ├── <my_certificate3>
| └── <my_certificate4>
└── tsa
└── <tsa_trust_store>
├── <tsa_certificate1>
└── <tsa_certificate2>
To sign and verify an image stored in the private registry with Notation GitHub Actions, you need to authenticate with the registry and KMS (Key Management Service). See the following authentication options for references.
- Use Docker login GitHub Action.
- Use vendor-based login GitHub Action, such as Amazon ECR "Login" Action for GitHub Actions, GitHub Action for Azure Login or Azure Container Registry Login GitHub Actions.
If your signing key and certificate are stored in a KMS, make sure to authenticate with the KMS before signing the image in your GitHub Actions workflow.