Creating Pipeline Tasks

JFrog Pipelines Documentation

JFrog Pipelines
Content Type
User Guide

To create a Task, create three mandatory files, each serving a definite purpose:

  • task.yaml

    It contains the task definition.


    It contains the documentation for the task.


    It contains the release and version information.


All three files mentioned above must be placed in the same directory. They should have specified formats and are available in GitHub template repositories.

The task.yaml has the reusable commands under the execution block. We support two types of SDKs. Following are the SDKs and the Hello World task examples.




SDKs are useful for creating complex tasks.

Task Directory Structure

Refer to the following templates in Github repositories to understand the structure of the task repository.

Contents of Task.yaml

Below is the outline of task.yaml

name: setup-go
description: Pipelines task for installing go
  - name: version
    description: [Required] version of go to be installed
   - name: gopath
    description: returns GO binary installed location
    - echo "injecting from a task into step onSuccess"
    - echo "injecting from a task into step onFailure"
    - echo "injecting from a task into step onComplete"




The name of the task.


A short description of the task.


The input section must have all the inputs a task requires.

  - name: version
    description: [Required] provide version to be installed
  - name: skipCache
    description: [Optional] [Default false] skips cache if given true otherwise always gets from cache
  - name: failOnCacheMiss
    description: [optional] [Default false] task returns non zero exit code and fails if failOnCacheMiss is true

The following are the mandatory parameters:

  • name: The name of the input as shown below.

      version: "1.21.3"
      skipCache: false
      failOnCacheMiss: false
  • description: The description of the input. The description must include whether the input is Required or Optional and its default values.

Read Inputs

If you use SDK to write tasks, it has an option to read the input. If you write the task using Shell/PowerShell script input, add the prefix IN to read. For example, use echo ${IN_version} to read the version.


The execution block contains all the commands to be run as part of the task. It can be a single binary execution when a task is written using SDK or it can be only a set of shell/power shell commands.


The hooks parameter contains onStepSuccess, onStepFailure and onStepComplete child parameters. Each parameter is a collection of commands that is stitched to onSuccess, onFailure and onComplete parameters of the step.

As the task execution parameter is stitched to the step, the step has an execution parameter and has the following child parameters:

  • onStart

  • onExecute

  • onSuccess

  • onFailure

  • onComplete

The child parameters of the hooks from the task are onStepSuccess, onStepFailure, onStepComplete and these are hooked to step onSuccess, onFailure, onComplete parameters respectively.

If the step is not defined onSuccess and the task has defined onStepSuccess, the task can’t create onSuccess similarly for other parameters.


It describes the output variables expected from this task. These are populated after the task execution is completed.

How output variables work

When a task specifies one or more outputs in the task.yaml file, it involves special handling. Outputs are not treated as regular variables; instead, they are accessed using the unique ID of the task that generated them.

When a task, identified by a unique ID such as do_stuff, is triggered, it generates an output labelled as a message. After executing the task, you can retrieve the value of the output message by accessing the variable ${do_stuff_message}. This approach is particularly useful for managing scenarios involving multiple tasks or nested tasks to prevent conflicts.

Set output variables

If you use SDK, it provides an option to set output otherwise as mentioned in the above section taskId is used as a prefix to set output variables. If you use a shell script, the creator of the task has to export the output as an environment variable.

How does a task execute at Runtime

When task configuration is seen in pipelines.yaml, pipelines sends a request to the task engine with all the configurations given for the task.

The task engine identifies which task version to run and downloads the task zip from the artifactory, extracts the content, adds the execution and hooks accordingly to the step script that will be executed.


Publish a Task

The task must be published to an Artifactory repository as shown in the below directory structure to download the task at run time and to be run by the task engine.


To publish the task, use publish-task that bundles all required files. Checks for the right structure, performs other mandatory checks and publishes the task to the Artifactory. See the following for the sample configuration.

task: jfrog/publish-task@v0.1.0
	path: "./path_to_task"
	taskName: "org/my-task"
	taskVersion: "0.0.1"
	includePattern: "^$|^dist"
	excludePattern: "^src"
	integration: "my_artifactory"
	targetRepository: "pipelines-tasks-repo-local"

To know more about the publish task and its input parameters, refer to the Reusables section and search for publish-task from the tasks tab.

Use Files to Publish a Task

Publish the following mandatory files in the same directory.

  • task.yaml



Specimen is available in GitHub template repositories.

Any other mandatory files that are unique to the task have been included by using includePattern in the publish-task.

Use Published Tasks in Pipelines

Following is the general format to use the task in pipelines.yaml.

task: <namespace>/<taskName>@v<Version> [Mandatory]
id: a unique id for this task execution [Optional]
repository: [Optional][default pipelines-tasks-virtual] repo name where task is published
rtIntegration: integration of artifactory from where the task has to be downloaded [optional]
input: [Optional] <All defined inputs in task.yaml as key-value pair>

Test Task without Publishing

You can test the task without publishing using the gitResource. Create a new repository for the task and add it as inputResource. In the task, instead of mentioning namespace/task@version mention the inputResource name.

Refer to the following example. To learn more, click here.

    - name: test_{{.Values.taskName }}
      type: Bash
          - name: {{ .Values.primaryResource }}
          - name: {{ .Values.artifactory }}
          - echo "Starting execution on {{ .Values.taskName }}"
          - task: $res_{{ .Values.primaryResource }}_resourcePath
            id: my-awesome-task
              version: "1.21.3"
              skipCache: false
              failOnCacheMiss: false

Test Task on a Local Machine

Taskverse is a plugin for jfrog-cli to test the task on a local machine. Refer to the Taskverse README file for how to use it.