From 1ac45d00d9dcbc696432ea859f16fd8a6c57cfce Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Thu, 27 Jul 2023 17:20:33 +0800 Subject: [PATCH 1/9] update README Signed-off-by: Feynman Zhou --- README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8b39560..d294d28 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,17 @@ -# Notation Github Actions -Github Actions for [Notation](https://notaryproject.dev/). +# GitHub Actions for Notation -Supported actions: `Notation: Setup`, `Notation: Sign` and `Notation: Verify`. +This repository contains the implementation of [GitHub Actions](https://docs.github.com/en/actions) for [Notation](https://notaryproject.dev/). It provides multiple actions for signing and verifying OCI artifacts with Notation in CI/CD. This project is still in early development status. + +The following three actions are available: + +- `setup`: Install Notation +- `sign`: Sign an OCI artifact with a specified plugin +- `verify`: Verify a signature + +> **Note** The Notary Project documentation is available [here](https://notaryproject.dev/docs/). You can also find the Notary Project [README](https://github.com/notaryproject/.github/blob/main/README.md) to learn about the overall Notary Project. ## Usage + ### Notation: Setup ```yaml - name: setup Notation CLI @@ -56,6 +64,7 @@ For example, trust_policy: trust_store: ``` + For example, ```yaml - name: verify released artifact @@ -65,6 +74,7 @@ For example, trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` + where `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-store). For example, @@ -78,4 +88,5 @@ For example, └── signingAuthority └── ├── - └── \ No newline at end of file + └── +``` \ No newline at end of file From 852d845d2d8dcbe8113f2b56d993cc11c33c7fdd Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 11 Sep 2023 22:14:24 +0800 Subject: [PATCH 2/9] resolve comments Signed-off-by: Feynman Zhou --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d294d28..416a216 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # GitHub Actions for Notation -This repository contains the implementation of [GitHub Actions](https://docs.github.com/en/actions) for [Notation](https://notaryproject.dev/). It provides multiple actions for signing and verifying OCI artifacts with Notation in CI/CD. This project is still in early development status. +This repository contains the implementation of [GitHub Actions](https://docs.github.com/en/actions) for [Notation](https://github.com/notaryproject/notation). It provides actions for signing and verifying OCI artifacts with Notation in CI/CD. The following three actions are available: From 2297094cde1915766183174e12d360ad7cd6c5f1 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 11 Sep 2023 22:24:40 +0800 Subject: [PATCH 3/9] resolve comments Signed-off-by: Feynman Zhou --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index 86e6a5b..f2b3305 100644 --- a/README.md +++ b/README.md @@ -97,12 +97,7 @@ For example, trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` -<<<<<<< HEAD - -where `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#trust-store). -======= `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). ->>>>>>> 0ff5453e0b9e6665539aa949df4dab419540cc0a `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-store). For example, ``` @@ -116,8 +111,6 @@ where `.github/truststore` MUST follow the Notation [trust store specs](https:// └── ├── └── -<<<<<<< HEAD -======= ``` Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers), ```yaml @@ -130,5 +123,4 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ->>>>>>> 0ff5453e0b9e6665539aa949df4dab419540cc0a ``` \ No newline at end of file From 270aeb99e3e16d1103441d27c8ffeae150a3c5a7 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Tue, 12 Sep 2023 18:27:41 +0800 Subject: [PATCH 4/9] remove an extra line Signed-off-by: Feynman Zhou --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index f2b3305..04ac6ab 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,6 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut trust_store: allow_referrers_api: ``` - For example, ```yaml - name: verify released artifact From bb77da411bd6f800e0406e5f3bc1b1ac184e2579 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Tue, 19 Sep 2023 07:59:02 +0800 Subject: [PATCH 5/9] refine README Signed-off-by: Feynman Zhou --- README.md | 39 ++++++++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 04ac6ab..9d7288c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ The following three actions are available: ## Usage +Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push), [HashiCorp Vault plugin](https://github.com/notaryproject/notation-hashicorp-vault/pulls). Currently, [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push) has been well tested in the Notation Github Actions by the sub-project maintainers. You can submit test cases and examples for other plugins. + ### Notation: Setup ```yaml - name: setup Notation CLI @@ -21,7 +23,11 @@ The following three actions are available: url: checksum: ``` -For example, + +
+ +See an example (Click here). + ```yaml - name: setup Notation CLI uses: notaryproject/notation-action/setup@main @@ -29,6 +35,8 @@ For example, version: "1.0.0" ``` +
+ ### Notation: Sign ```yaml - name: sign releasd artifact with signing plugin @@ -43,7 +51,11 @@ For example, plugin_config: allow_referrers_api: ``` -For example, + +
+ +See an example (Click here). + ```yaml - name: sign releasd artifact with notation-azure-kv plugin uses: notaryproject/notation-action/sign@main @@ -58,7 +70,9 @@ For example, ca_certs=.github/cert-bundle/cert-bundle.crt self_signed=false ``` -Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers), + +Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers) in signing: + ```yaml - name: sign releasd artifact with notation-azure-kv plugin uses: notaryproject/notation-action/sign@main @@ -77,6 +91,8 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut self_signed=false ``` +
+ ### Notation: Verify ```yaml - name: verify released artifact @@ -87,7 +103,13 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut trust_store: allow_referrers_api: ``` -For example, + +
+ +See an example (Click here). + +`.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). + ```yaml - name: verify released artifact uses: notaryproject/notation-action/verify@main @@ -96,7 +118,6 @@ For example, trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` -`.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-store). For example, ``` @@ -111,7 +132,9 @@ For example, ├── └── ``` -Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers), + +Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers) in verification: + ```yaml - name: verify released artifact uses: notaryproject/notation-action/verify@main @@ -122,4 +145,6 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore -``` \ No newline at end of file +``` + +
From c966ea4c66770f8bd7bb7997ebb37f7492123896 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 20 Sep 2023 13:57:44 +0800 Subject: [PATCH 6/9] update README Signed-off-by: Feynman Zhou --- README.md | 60 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9d7288c..f65e490 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,15 @@ The following three actions are available: ## Usage -Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push), [HashiCorp Vault plugin](https://github.com/notaryproject/notation-hashicorp-vault/pulls). Currently, [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push) has been well tested in the Notation Github Actions by the sub-project maintainers. You can submit test cases and examples for other plugins. +Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push), [HashiCorp Vault plugin](https://github.com/notaryproject/notation-hashicorp-vault/pulls). + +Currently, [Azure Key Vault plugin for Notation](https://github.com/Azure/notation-azure-kv) has been well tested in the Notation Github Actions by the sub-project maintainers. See this [doc](https://github.com/notation-playground/notation-integration-with-ACR-and-AKV/blob/main/sign-action.md) 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. + +### Notation Setup -### Notation: Setup ```yaml - name: setup Notation CLI - uses: notaryproject/notation-action/setup@main + uses: notaryproject/notation-action/setup@v1 with: version: url: @@ -30,17 +33,18 @@ Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Not ```yaml - name: setup Notation CLI - uses: notaryproject/notation-action/setup@main + uses: notaryproject/notation-action/setup@v1 with: version: "1.0.0" ``` -### Notation: Sign +### Notation Sign + ```yaml - name: sign releasd artifact with signing plugin - uses: notaryproject/notation-action/sign@main + uses: notaryproject/notation-action/sign@v1 with: plugin_name: plugin_url: @@ -58,11 +62,11 @@ Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Not ```yaml - name: sign releasd artifact with notation-azure-kv plugin - uses: notaryproject/notation-action/sign@main + uses: notaryproject/notation-action/sign@v1 with: plugin_name: azure-kv - plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.0/notation-azure-kv_1.0.0_linux_amd64.tar.gz - plugin_checksum: 82d4fee34dfe5e9303e4340d8d7f651da0a89fa8ae03195558f83bb6fa8dd263 + plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.1/notation-azure-kv_1.0.1_linux_amd64.tar.gz + plugin_checksum: f8a75d9234db90069d9eb5660e5374820edf36d710bd063f4ef81e7063d3810b key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb signature_format: cose @@ -75,9 +79,9 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut ```yaml - name: sign releasd artifact with notation-azure-kv plugin - uses: notaryproject/notation-action/sign@main + uses: notaryproject/notation-action/sign@v1 env: - NOTATION_EXPERIMENTAL: 1 # this is requried by Notation to use Referrers API + NOTATION_EXPERIMENTAL: 1 # this is required by Notation to use Referrers API with: allow_referrers_api: 'true' plugin_name: azure-kv @@ -93,10 +97,11 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut -### Notation: Verify +### Notation Verify + ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 with: target_artifact_reference: trust_policy: @@ -108,18 +113,18 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut See an example (Click here). -`.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). - ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 with: target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` -`.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-store). For example, +> [!NOTE] +> `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-policy). + ``` .github/truststore └── x509 @@ -133,13 +138,16 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut └── ``` +> [!NOTE] +> `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store). + Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers) in verification: ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 env: - NOTATION_EXPERIMENTAL: 1 # this is requried by Notation to use Referrers API + NOTATION_EXPERIMENTAL: 1 # this is required by Notation to use Referrers API with: allow_referrers_api: 'true' target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb @@ -148,3 +156,17 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut ``` + +## Authentication + +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. + +### Registry authentication + +- Use [Docker login GitHub Action](https://github.com/marketplace/actions/docker-login). +- Use vendor-based login GitHub Action, such as [Amazon ECR "Login" Action for GitHub Actions](https://github.com/marketplace/actions/amazon-ecr-login-action-for-github-actions), [GitHub Action for Azure Login](https://github.com/marketplace/actions/azure-login) or [Azure Container Registry Login GitHub Actions](https://github.com/marketplace/actions/azure-container-registry-login). + +### KMS authentication + +If you use a signing key and certificate stored in a KMS, make sure to authenticate with the KMS before signing this image in your GitHub Actions workflow. + From 5e4ca6e4aa272f145efcd8771e5839276c6064e9 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 20 Sep 2023 14:37:11 +0800 Subject: [PATCH 7/9] resolve comments Signed-off-by: Feynman Zhou --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f65e490..ae3ed2a 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ This repository contains the implementation of [GitHub Actions](https://docs.git The following three actions are available: - `setup`: Install Notation -- `sign`: Sign an OCI artifact with a specified plugin -- `verify`: Verify a signature +- `sign`: Sign an OCI artifact with a specified Notation plugin +- `verify`: Verify a signature with Notation trust store and trust policy > **Note** The Notary Project documentation is available [here](https://notaryproject.dev/docs/). You can also find the Notary Project [README](https://github.com/notaryproject/.github/blob/main/README.md) to learn about the overall Notary Project. @@ -123,7 +123,8 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut ``` > [!NOTE] -> `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-policy). +> - `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-policy). +> - `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store). See an example of trust store below. ``` .github/truststore @@ -138,9 +139,6 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut └── ``` -> [!NOTE] -> `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store). - Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers) in verification: ```yaml From 593a79179be9fd798d98ac3d12cb02c81275b0e7 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 20 Sep 2023 14:48:14 +0800 Subject: [PATCH 8/9] resolve comments Signed-off-by: Feynman Zhou --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ae3ed2a..348902c 100644 --- a/README.md +++ b/README.md @@ -166,5 +166,5 @@ To sign and verify an image stored in the private registry with Notation GitHub ### KMS authentication -If you use a signing key and certificate stored in a KMS, make sure to authenticate with the KMS before signing this image in your GitHub Actions workflow. +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. From c54cf9d183680126248c0aa141ed683c6295d38f Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 20 Sep 2023 14:51:30 +0800 Subject: [PATCH 9/9] resolve comments Signed-off-by: Feynman Zhou --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 348902c..4adbb47 100644 --- a/README.md +++ b/README.md @@ -85,8 +85,8 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut with: allow_referrers_api: 'true' plugin_name: azure-kv - plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.0/notation-azure-kv_1.0.0_linux_amd64.tar.gz - plugin_checksum: 82d4fee34dfe5e9303e4340d8d7f651da0a89fa8ae03195558f83bb6fa8dd263 + plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.1/notation-azure-kv_1.0.1_linux_amd64.tar.gz + plugin_checksum: f8a75d9234db90069d9eb5660e5374820edf36d710bd063f4ef81e7063d3810b key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb signature_format: cose