Edit

Notation@0 - Notation v0 task

  • Article

Azure Pipepine Task for setting up Notation CLI, sign and verify with Notation.

Syntax

# Notation v0
# Azure Pipepine Task for setting up Notation CLI, sign and verify with Notation.
- task: Notation@0
  inputs:
    command: 'install' # 'install' | 'sign' | 'verify'. Required. Command to run. Default: install.
  # Command Configuration
    #isCustomVersion: false # boolean. Optional. Use when command = install. Custom Version. Default: false.
    #version: '1.1.0' # string. Required when command = install && isCustomVersion = false. Version. Default: 1.1.0.
    #url: # string. Required when command = install && isCustomVersion = true. Download URL. 
    #checksum: # string. Required when command = install && isCustomVersion = true. Checksum. 
    #artifactRefs: # string. Optional. Use when command = verify || command = sign. Artifact references. 
    #trustPolicy: # string. Required when command = verify. Trust Policy File Path. 
    #trustStore: # string. Required when command = verify. Trust Store Folder Path. 
  # Advanced Configuration
    #signatureFormat: 'cose' # 'cose' | 'jws'. Optional. Use when command = sign && command = sign || command = verify. Signature Format. Default: cose.
    #allowReferrersAPI: false # boolean. Optional. Use when command = sign || command = verify. [Experimental] Allow Referrers API. Default: false.
  # Plugin Configuration
    #plugin: 'azureKeyVault' # 'azureKeyVault'. Required when command = sign. Plugin. Default: azureKeyVault.
    #akvPluginVersion: '1.0.1' # string. Required when plugin = azureKeyVault && command = sign. Plugin Version. Default: 1.0.1.
    #azurekvServiceConection: # string. Optional. Use when plugin = azureKeyVault && command = sign. Azure Key Vault service connection. 
    #keyid: # string. Required when plugin = azureKeyVault && command = sign. Key ID. 
    #caCertBundle: # string. Optional. Use when plugin = azureKeyVault && command = sign. Certificate Bundle File Path. 
    #selfSigned: false # boolean. Optional. Use when plugin = azureKeyVault && command = sign. Self-signed Certificate. Default: false.

Inputs

command - Command to run
string. Required. Allowed values: install, sign, verify. Default value: install.

Specifies the command mode of the task.

  • install - The install command detects the current operating system and architecture to download the corresponding Notation CLI from GitHub releases. It also verifies the checksum of the downloaded file against the golden file in the ./data folder and adds Notation to the PATH.
  • sign - The sign command downloads the selected Notation plugin, validates its checksum, and then calls on the Notation CLI to sign.
  • verify - The verify command transfers the trust store and trust policy from the user's code repository to the Notation configuration folder, as required by Notation CLI. It then invokes the Notation CLI to perform verification.

isCustomVersion - Custom Version
boolean. Optional. Use when command = install. Default value: false.

Specify true to provide a custom version of Notation for the task by specifying a download URL to the custom version in the url property.


version - Version
string. Required when command = install && isCustomVersion = false. Default value: 1.1.0.

The version of Notation to install. Example: 1.0.0, 1, 1.0, 1.0.0.


url - Download URL
string. Required when command = install && isCustomVersion = true.

The URL to a custom version of Notation to use, for example: https://github.com/notaryproject/notation/releases/download/v1.0.0/notation_1.0.0_linux_amd64.tar.gz.


checksum - Checksum
string. Required when command = install && isCustomVersion = true.

The SHA-256 checksum of the downloaded file.


artifactRefs - Artifact references
string. Optional. Use when command = verify || command = sign.

Container artifact references for signing. If not specified, the task uses the artifact reference from the previous Docker push task. Example: <registry name>/<repository name>@<digest>. Multiple artifact references must be comma separated.


signatureFormat - Signature Format
string. Optional. Use when command = sign && command = sign || command = verify. Allowed values: cose, jws. Default value: cose.

Signature envelope format.


allowReferrersAPI - [Experimental] Allow Referrers API
boolean. Optional. Use when command = sign || command = verify. Default value: false.

Use the Referrers API to sign signatures, if not supported (returns 404), fallback to the Referrers tag schema.


plugin - Plugin
string. Required when command = sign. Allowed values: azureKeyVault (Azure Key Vault Plugin). Default value: azureKeyVault.


akvPluginVersion - Plugin Version
string. Required when plugin = azureKeyVault && command = sign. Default value: 1.0.1.

The version of the Azure Key Vault plugin to be installed. See the notation-azure-kv releases page for the available versions.


azurekvServiceConection - Azure Key Vault service connection
string. Optional. Use when plugin = azureKeyVault && command = sign.

Select the Azure subscription for the key vault if prefer to use service connection for authentication.


keyid - Key ID
string. Required when plugin = azureKeyVault && command = sign.

The Key ID is the key or certificate identifier for Azure Key Vault.


caCertBundle - Certificate Bundle File Path
string. Optional. Use when plugin = azureKeyVault && command = sign.

The certificate bundle file with root and all intermediate certificates, starting from the root certificate, following the order in the certificate chain.


selfSigned - Self-signed Certificate
boolean. Optional. Use when plugin = azureKeyVault && command = sign. Default value: false.

Whether the certificate is a self-signed certificate.


trustPolicy - Trust Policy File Path
string. Required when command = verify.

The path to the trust policy file relative to the repository. Example: ./path/to/trust-policy.json.


trustStore - Trust Store Folder Path
string. Required when command = verify.

The path to the directory containing the trust store relative to the repository. Example: ./path/to/truststore/.


Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

The Notation task calls upon the Notation CLI to execute signing and verification operations. Notation CLI is a tool used to sign and verify Docker container artifacts or images. When signing an artifact, Notation signs the artifact's unique manifest descriptor and attaches the signature to the same repository. When verifying an artifact, Notation retrieves the signature from the repository and validates it against the certificate in the trust store.

Prerequisites

  • This task requires public network access for downloading Notation CLI and Notation Azure Key Vault plugin from Github releases.
  • Supported Agent OS: Linux x64/ARM64, Windows x64, macOS x64/ARM64

Notation install command

The install command detects the current operating system and architecture to download the corresponding Notation CLI from GitHub releases. It also verifies the checksum of the downloaded file against the golden file in the ./data folder and adds Notation to the PATH.

Notation sign command

The sign command downloads the selected Notation plugin, validates its checksum, and then calls on the Notation CLI to sign.

Notation verify command

The verify command transfers the trust store and trust policy from the user's code repository to the Notation configuration folder, as required by Notation CLI. It then invokes the Notation CLI to perform verification.

Requirements

Requirement Description
Pipeline types YAML, Classic build, Classic release
Runs on Agent, DeploymentGroup
Demands None
Capabilities This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions Any
Settable variables Any
Agent version 2.144.0 or greater
Task category Utility