Creating Pipeline Tasks

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

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.

Node

GO

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
source: https://github.com/jfrog/jfrog-pipelines-task
input:
  - name: version
    description: [Required] version of go to be installed
output:
   - name: gopath
    description: returns GO binary installed location
execution:
  - bin/taskName-${JFROG_OPERATING_SYSTEM_FAMILY}-${JFROG_ARCHITECTURE}
hooks:
  onStepSuccess:
    - echo "injecting from a task into step onSuccess"
  onStepFailure:
    - echo "injecting from a task into step onFailure"
  onstepComplete:
    - echo "injecting from a task into step onComplete"

input:
  - 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

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
  input:
	path: "./path_to_task"
	taskName: "org/my-task"
	taskVersion: "0.0.1"
	includePattern: "^README.md$|^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.

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.

steps:
    - name: test_{{.Values.taskName }}
      type: Bash
      configuration:
        inputResources:
          - name: {{ .Values.primaryResource }}
        integrations:
          - name: {{ .Values.artifactory }}
      execution:
        onStart:
          - echo "Starting execution on {{ .Values.taskName }}"
        onExecute:
          - task: $res_{{ .Values.primaryResource }}_resourcePath
            id: my-awesome-task
            input:
              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.