Skip to content
shield

GitHub Action

Notation Actions

v1.2.0 Latest version

Notation Actions

shield

Notation Actions

Setup Notary Project tooling Notation for signing and verifying container images and other artifacts such as SBOM

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Notation Actions

              
  uses: notaryproject/[email protected]
Learn more about this action in notaryproject/notation-action

Choose a version

GitHub Actions for Notation

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 Notation
  • sign: Sign OCI artifacts with a specified Notation plugin
  • verify: 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.

Usage

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.

Notation Setup

- 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"

Notation Sign

- 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>
    allow_referrers_api: <boolean_flag_for_referrers_api>
See an example (Click here). 
- name: sign releasd artifact with notation-azure-kv plugin
  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:aaabbb
      myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd
    signature_format: cose
    plugin_config: |-
      ca_certs=.github/cert-bundle/cert-bundle.crt
      self_signed=false

Example of using the Referrers API in signing:

- name: sign releasd artifact with notation-azure-kv plugin
  uses: notaryproject/notation-action/sign@v1
  env:
    NOTATION_EXPERIMENTAL: 1  # this is required by Notation to use Referrers API
  with:
    allow_referrers_api: 'true'
    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:aaabbb
      myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd
    signature_format: cose
    plugin_config: |-
      ca_certs=.github/cert-bundle/cert-bundle.crt
      self_signed=false

Notation Verify

- 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>
    allow_referrers_api: <boolean_flag_for_referrers_api>
See an example (Click here). 
- name: verify released artifact
  uses: notaryproject/notation-action/verify@v1
  with:
    target_artifact_reference: |-
      myRegistry.azurecr.io/myRepo@sha256:aaabbb
      myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd
    trust_policy: .github/trustpolicy/trustpolicy.json
    trust_store: .github/truststore

[!NOTE]

  • .github/trustpolicy/trustpolicy.json MUST follow the Notation trust policy specs.
  • .github/truststore MUST 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>

Example of using the Referrers API in verification:

- name: verify released artifact
  uses: notaryproject/notation-action/verify@v1
  env:
    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
      myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd
    trust_policy: .github/trustpolicy/trustpolicy.json
    trust_store: .github/truststore

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

KMS authentication

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.