Improve this page on GitHub

Annotations in pipelines

Mark your builds and projects with extra annotations

Codefresh supports the annotations of several entities with custom annotations. You can use these annotations to store any optional information that you wish to keep associated with each entity. Examples would be storing the test coverage for a particular build, or a special settings file for a pipeline.

Currently Codefresh supports extra annotations for:

  • Projects
  • Pipelines
  • Builds
  • Docker images

You can view/edit annotations using the Codefresh CLI or directly in the Codefresh Web UI.

Notice that the syntax shown in this page is deprecated but still supported. For the new syntax, see hooks in pipelines.

Adding annotations

In the most basic scenario, you can use the post-step operations of any Codefresh step to add annotations:

codefresh.yml

version: '1.0'
steps:
  my_custom_step:
    title: Adding annotations to a project
    image: alpine:3.9
    commands:
     - echo "Hello"
    on_success: 
      annotations:
        set:
          - entity_id: annotate-examples
            entity_type: project
            annotations:
            - my_annotation_example1: 10.45
            - my_empty_annotation
            - my_string_annotation: Hello World

This pipeline adds three annotations to a project called annotate-examples. The name of each annotation can only contain letters (upper and lowercase), numbers and the underscore character. The name of each annotation must start with a letter.

For the entity_id value you can also use an actual ID instead of a name. The entity_id and entity_type are define which entity will hold the annotations. The possible entity types are:

  • project (for a project, even a different one)
  • pipeline (for a pipeline, even a different one)
  • build (for a build, even a different one)
  • image (for a docker image)

If you don’t define them, then by default the current build will be used with these values:

  • entity_id is ${{CF_BUILD_ID}} (i.e. the current build)
  • entity_type is build

Here is another example where we add annotations to another pipeline as well as another build (instead of the current one)

codefresh.yml

version: '1.0'
steps:
  my_custom_step:
    title: Adding annotations to multiple entities
    image: alpine:3.9
    commands:
     - echo "Hello"
    on_success: 
      annotations:
        set:
          - entity_id: my-project/my-basic-pipeline 
            entity_type: pipeline
            annotations:
            - my_annotation_example1: 10.45
            - my_empty_annotation
            - my_string_annotation: Hello World
          - entity_id: 5ce2a0e869e2ed0a60c1e203
            entity_type: build
            annotations:
            - my_coverage: 70
            - my_url_example: http://www.example.com

It is therefore possible to store annotations on any Codefresh entity (and not just the ones that are connected to the build that is adding annotations).

Viewing/editing annotations

You can view the annotations using the Codefresh CLI

codefresh get annotation project annotate-examples

You can also view annotations within the Codefresh UI.

For build annotations click the Annotations on the build details:

Viewing Build annotations

Viewing Build annotations

For pipeline annotations click the Annotations button in the pipeline list view:

Viewing Pipeline annotations

Viewing Pipeline annotations

For project annotations click the Annotations button in the project list view:

Viewing project annotations

Viewing project annotations

In all cases you will see a dialog with all existing annotations.

Editing annotations

Editing annotations

You can add additional annotations manually by clicking the Add annotation button and entering:

  • The name of the annotation
  • The type of the annotation (text, number, percentage, link, boolean)
  • The desired value

Click Save to apply your changes.

Complex annotation values

Apart from scalar values, you can also store more complex expressions in annotations. You have access to all Codefresh variables, text files from the build and even evaluations from the expression syntax.

codefresh.yml

version: '1.0'
steps:
  main_clone:
    title: Cloning main repository...
    type: git-clone
    repo: 'kostis-codefresh/nestjs-example'
    revision: '${{CF_REVISION}}'
  my_custom_step:
    title: Complex annotations
    image: alpine:3.9
    commands:
     - echo "Hello"
     - echo "Sample content" > /tmp/my-file.txt
    on_finish: 
      annotations:
        set:
          - entity_id: annotate-examples/simple
            entity_type: pipeline
            annotations:
              - qa: pending
              - commit_message: ${{CF_COMMIT_MESSAGE}}
              - is_main_branch: 
                  evaluate: "'${{CF_BRANCH}}' == 'main'"
              - my_json_file: "file:/tmp/my-file.txt"  
              - my_docker_file: "file:Dockerfile"

Notice that this pipeline is using dynamic git repository variables, so it must be linked to a least one Git trigger in order to work.

The last two annotations add the text of a file as a value. You can define an absolute or relative path. No processing is done on the file before being stored. If a file is not found, the annotation will still be added verbatim. We suggest you only store small text files in this manner as annotations values.

Removing annotations

You can also remove annotations by mentioning their name:

codefresh.yml

version: '1.0'
steps:
  my_custom_step:
    title: Adding annotations to a pipeline
    image: alpine:3.9
    commands:
     - echo "Hello"
    on_success: 
      annotations:
        set:
          - entity_id: my-project/my-basic-pipeline 
            entity_type: pipeline
            annotations:
            - my_annotation_example1: 10.45
            - my_empty_annotation
            - my_string_annotation: Hello World
            - my_second_annotation: This one will stay
  my_unit_tests:
    title: Removing annotations
    image: alpine:3.9
    commands:
     - echo "Tests failed"
     - exit 1
    on_fail: 
      annotations:
        unset:
          - entity_id: my-project/my-basic-pipeline 
            entity_type: pipeline
            annotations:
            - my_annotation_example1
            - my_empty_annotation
            - my_string_annotation

You can also use both unset and set block in a single annotations block. And of course, you can remove annotations from multiple entities.

The unset annotation can be used with all post-step operations (on_success, on_fail, on_finish).

Adding annotations to the current build/image

As a convenience feature:

  1. If your pipeline has a build step
  2. If you want to add annotations to the present build or image

you can also define annotations in the root level of the build step and not mention the entity id and type. Annotations will then be added in the present build.

codefresh.yml

version: '1.0'
steps:
  main_clone:
    title: Cloning main repository...
    type: git-clone
    repo: 'kostis-codefresh/nestjs-example'
    revision: 'master'
  MyAppDockerImage:
    title: Building Docker Image
    type: build
    image_name: my-app-image
    working_directory: ./
    tag: 'sample'
    dockerfile: Dockerfile
    annotations:
      set:
        - annotations:
          - my_number_annotation: 9999
          - my_empty_annotation
          - my_docker_file: "file:Dockerfile"
          - my_text_annotation: simple_text

After running this pipeline at least once, you can retrieve the annotations from any previous build by using the respective id:

codefresh get annotation build 5ce26f5ff2ed0edd561fa2fc

You can also define entity_type as image and don’t enter any entity_id. In this case the image created from the build step will be annotated.

Note that this syntax is optional. You can still define annotations for a build/image or any other entity using the post operations of any step by mentioning explicitly the target id and type.

Image annotations
Creating pipelines
Hooks in pipelines