Using Resources

JFrog Pipelines Documentation

Products

JFrog Pipelines

Content Type

User Guide

ft:sourceType

Paligo

In a pipeline, steps can use resources as:

Inputs: When a resource is an input for a step, it is called an input resource. The input resource of one step can be the output resource of other steps.
Outputs: When a resource is an output of a step, it is called an output resource. The output resource of one step can be the input resource of other steps.

Input and output resources can originate from the same pipeline source as the pipeline or another pipeline source in the same project and environment.

Input Resources

Input resources enable you to create dependencies between steps and pipelines. Steps that have input resources from other pipelines trigger a run of the pipeline when the resource is updated. By default, input resources that were an output resource of another step in the same run will run whether or not the resource is updated. A resource can also be referred to by its name as an argument in the shell commands that the step executes.

Input Resource Definiton

A resource can be specified as an input for a step by adding it to the inputResources section of a step.

YAML Schema

    steps:
      - name: <step_name>
        type: <step_type>
        configuration:          
          inputResources:
            - name:         <resource name>
              trigger:      <true/false>    # default true
              newVersionOnly: <true/false>  # default false
              branch:       <string>        # see description of defaults below

Tag	Description of usage	Required/Optional
`name`	Name of the declared resource that is to be a used as an input for the step.	Required
`trigger`	`Trigger` is set as `true` by default and any change to a named resources triggers the execution of a step. This can be changed by declaring `trigger` as `false`.	Optional
`newVersionOnly`	Setting `newVersionOnly`as `true` for an input resource will cause a step to be skipped if the input resource is not updated in the current run. If there are multiple `inputResources` with `newVersionOnly: true`, the step is skipped only when none of the resources are updated. If at least one of the resources is updated, the step is not skipped.	Optional
`branch`	A `branch` is required only when using a resource from another branch of a multi-branch source. By default, the resource from a single-branch source or the same branch of a multi-branch pipeline is used. To use a multi-branch resource in a single-branch pipeline or another branch in a multi-branch pipeline, `branch` should be used to specify the branch to which the resource belongs.	Optional

Example - Input Resource Definition

    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_app_repo
              trigger: false   # optional; default true
              newVersionOnly: true  # optional; default false
              branch: master   # optional

Using Input Resources

This section provides information about the various ways in which input resources can be used to manipulate pipeline runs.

Skip Automatic Trigger for All Commits

By default, changes to an input resource triggers the execution of the dependent steps. For example, when a step specifies a GitRepo resource, any new code committed to that Git repository automatically causes that step to execute. However, this behavior can be changed by declaring trigger as false (see below). Now, even when the resource is updated, the dependent step is not triggered. This is especially useful for a production pipeline, when you do not want to deploy every new build.

Note

For a step to not be triggered automatically, trigger: false must be set for all input resources in the step.

Note

Even if trigger is set as false, the step still receives webhook updates. This ensures that when it is manually triggered, it uses the latest commit.

Example - Automatic Trigger Off

pipelines:
  - name: java_pipeline
    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_app_repo
              trigger: false
            - name: cron_trigger
              trigger: false
        execution:
           onExecute:
             - pushd $res_my_app_repo_resourcePath
             - ./execute.sh
             - popd

When trigger is set as false, the line linking the input resource and the step appears as a dashed line.

trigger: false

trigger: true

Trigger Automatically on New Version Only

Whenever a resource undergoes a change, its version is updated and the dependent step is triggered. This is the default behavior for all input resources. To skip steps in a run when input resources are not updated, add the newVersionOnly tag and set it as true. During a run, the step is triggered only when the resource is updated. If the resource is not updated, the step is skipped and all the downstream steps are skipped as well.

Example 1 - newVersionOnly

pipelines:
  - name: java_pipeline
    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_app_repo
              newVersionOnly: true
        execution:
          onExecute:
            - pushd $res_my_app_repo_resourcePath
            - ./execute.sh
            - popd

resources:
  - name: new_resource
    type: PropertyBag
    configuration:
      runNumber: 0

pipelines:
  - name: pipeline_01
    steps:
      - name: step_input
        type: Bash
        configuration:
          outputResources:
            - name: new_resource
        execution:
          onExecute:
            #- write_output new_resource runNumber=${run_number}
            - echo "test"

      - name: step1      
        type: Bash
        configuration:
          inputResources:
            - name: new_resource
              newVersionOnly: true
        execution:
          onExecute:
            - echo "test"

      - name: step2
        type: Bash
        configuration:
          inputResources:
            - name: new_resource
        execution:
          onExecute:
            - echo "test"

Trigger Manually using Specific Versions

A run can be customized by selecting a specific version for an input resource. For more information, see Triggering a Run with Custom Parameters.

Pinning Resource Versions

By default, Pipelines uses the most recent or latest version of an input resource when running a job. However, there could be cases where you want to use a specific version of an input resource for a run. This is called pinning and input versions can be pinned using the YAML configuration. When a resource version is unpinned, it switches to using the latest version for all subsequent runs.

Resource version Ids have a global sequence, which can be found on the Resource tab. For more information, see Viewing Resources.

Pinning Resource Versions in YAML

You can use the pin tag to pin a specific input version as shown below below:

Example

resources:
  - name:                       <string>
    type:                       DistributionRule
    configuration:
      pin:
        versionId:  <number>

The following resources support version pinning:

Output Resources

Output resources are resources that are either generated or changed by a step. When specified as the output of a step, the resource receives the output of the step. If required, this output resource can then be used as an input resource in a subsequent step in the same pipeline or another pipeline. The output resource can also be referred to by its name as an argument in the shell commands that the step executes.

Output Resource Definition

A resource can be specified as an output for a step by adding it in the outputResources section of a step.

YAML Schema

    steps:
      - name: <step_name>
        type: <step_type>
        configuration:          
          outputResources:
            - name:         <resource name>
              branch:       <string>        # see description of defaults below

Tag	Description of usage	Required/Optional
`name`	Name of the declared resource that is to be used as an input for the step.	Required
`branch`	A `branch`is only required for resources from another branch of a multi-branch source. By default, the resource from a single-branch source or the same branch of a multi-branch pipeline is assumed. To update a multi-branch resource in a single-branch pipeline or another branch in a multi-branch pipeline, `branch` should be used to specify the branch to which the resource belongs.	Optional

Example - Output Resource Definition

    steps:
      - name: step_2
        type: Bash
        configuration:
          outputResources:
            - name: my_repo
              branch: master