CODEFRESH.IO DOCUMENTATION

Codefresh is a Docker-native CI/CD platform.

Instantly build , test and deploy Docker images.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Image Metadata Annotations

Images built by Codefresh can be annotated with customized metadata.
This article explains how to create advanced view of your images and enrich them with custom metadata which perfectly fits your flow and image management process.

Metadata types

Images built by Codefresh can be annotated with an array of key-value metadata.
Metadata values may be of the following types:

Annotation type
Guidelines
Example

String

Use string

'Example note'

Number

use numeric value to set this kind of annotation

9999

Boolean

Use true / false value

true

Percentage bar

use 0-100 value ending with %

85%

Link

use url

'${{CF_COMMIT_URL}}'

You can also use Expression evaluations to set metadata.

Annotate your images using codefresh YAML

You can annotate an image as part of it's builds process and also on post build steps.

Build step Image Metadata Annotation

You can annotate an image as part of its build process by declaring the metadata value on the Build step:

  1. The metadata attribute
  2. The set operation
  3. An array of key-value metadata
build_step:
  type: build
  ...
  metadata: # Declare the metadata attribute
    set: # Specify the set operation
      - qa: pending
      - commit_message: ${{CF_COMMIT_MESSAGE}}
      - exit_code: 0
      - is_main: 
          evaluate: "'${{CF_BRANCH}}' == 'main'"

Adding annotations to Built images on post-build steps

Any step in the YAML workflow can annotate built images by using Post-Step Operations.
To annotate a built image, configure any step with:

  1. The post-step operation
  2. The metadata attribute
  3. The set operation
  4. A list of target images with the variable syntax of ${{build_step_name.imageId}}
  5. An array of key-value metadata
build_step:
  type: build
  ...

any_step:
  ...
  on_success: # Execute only once the step succeeded
    metadata: # Declare the metadata attribute
      set: # Specify the set operation
        - ${{build_step.imageId}}: # Select any number of target images
          - qa: pending
          
  on_fail: # Execute only once the step failed
    metadata: # Declare the metadata attribute
      set: # Specify the set operation
        - ${{build_step.imageId}}: # Select any number of target images
          - exit_code: 1

  on_finish: # Execute in any case
    metadata: # Declare the metadata attribute
      set: # Specify the set operation
        - ${{build_step.imageId}}: # Select any number of target images
          - is_main: 
              evaluate: "'${{CF_BRANCH}}' == 'main'"

Viewing Image Metadata Annotations

You can view an image's metadata annotation by:

  1. Navigating to the Images view
  2. Selecting the target image
  3. Selecting the Annotations tab

In addition, you can add selected annotations to the images table on images page. To display an annotation in the image table, click on the gear icon at the top right corner of image page and then select all annotations you want to display.

Example - Quality Image Metadata Annotation

You can set a quality indicator to images to show if they passed or failed tests. An image with the boolean annotation CF_QUALITY set to true will have a quality indicator in the 'Images' view.

version: '1.0'
steps:
  build_step:
    type: build
    image_name: myrepo/imagename
    working_directory: ./
    dockerfile: Dockerfile
    
  unit_test:
    image: '${{build_step}}'
    working_directory: IMAGE_WORK_DIR
    commands:
    	- echo test
    on_success:
      metadata:
        set:
          - '${{build_step.imageId}}':
              - CF_QUALITY: true
    on_fail:
      metadata:
        set:
          - '${{build_step.imageId}}':
              - CF_QUALITY: false

Image quality has 3 indicators:

  • true - this image is considered a quality image (ex. passed tests)
  • false - this image is not considered a quality image (ex. when tests failed but the image was already built)
  • no value (nobody set the annotation) - this image has no quality indicator

Image Metadata Annotations