Pipelines Resources

Resource Definition

Resources are defined in a pipeline config under the resources tag, as shown below. Not all sections are required by all resources.

resources:
  - name:               <string>
    type:               <resource type name>
	configuration:
      <as required by type>

Using Resources

Resources can be inputs and outputs of steps in a pipeline. Resources may be from the same pipeline source as the pipeline or another pipeline source in the same project and environment. If the resource is from a multi-branch pipeline source, either the same as the pipeline or a different source, and a different branch than the pipeline, branch must included in the resource in inputResources or outputResources. To use a resource from a single-branch pipeline, branch should not be specified. 

They can be used by steps in these ways:

Inputs

When specified in a step in the inputResources section, the resource is an input for a step. The resource can also be referred to by its name as an argument in shell commands that the step executes.

A resource version will automatically initiate the execution of that step that has that resource as input resource. 

For example, when a Step specifies a GitRepo resource,  any new code commit to that Git repository will automatically cause that step to execute.

If a step that specifies an image resource and trigger is set to false, the step is executed, it will use the latest version of the resource during the execution. 

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. To skip steps in the same run when input resources are not updated, newVersionOnly may be added to the input resource.

Outputs

When specified as the output of a step in an outputResources tag, the resource receives the output of the native step. The resource can also be referred to by its name as an argument in shell commands that the step executes. 

Environment Variables

A step that specifies a resource in inputresources can access the resource and its attributes through environment variables. The form of the environment variable is:

res_<resource name>_<tag>

You can also access an integration that is specified in the resource through an environment variable, whose form is:

res_<resource_name>_<integration tag name>_<tag>

For example, if the definition of a GitRepo resource named app_gitrepo is:

resources:
  - name: app_gitRepo
    type: GitRepo
    configuration:
      path: user1/repo1
      gitProvider: myGitProvider

Then the following environment variables will be available to a step that uses the app_gitRepo as an input:

The example step shows how these environment variables might be used to send notifications:

steps:
  - name: build_app
    type: MvnBuild
    configuration:
      sourceLocation: .
      mvnCommand: clean install
      configFileLocation: .
      inputResources:
        - name: app_gitRepo	            # Use the app_gitRepo resource
   execution:
     onSuccess:
       - send_notification notifySlack --text "Maven build completed for $res_app_gitRepo_path at $res_app_gitRepo_gitProvider_url"
     onFailure:
       - send_notification notifySlack --text "Maven build FAILED for $res_app_gitRepo_path at $res_app_gitRepo_gitProvider_url"

Arrays

For arrays within resources (e.g. VmCluster):

res_<resource name>_<array heading>_len     (this tells you how many entries in array)
res_<resource name>_<array heading>_0
res_<resource name>_<array heading>_1
res_<resource name>_<array heading>_2

For object arrays within resources (e.g. DistributionRule):

res_<resource name>_<array heading>_len     (this tells you how many entries in array)
res_<resource name>_<array heading>_0_<tag>
res_<resource name>_<array heading>_1_<tag>

State Information

Steps can store any key-value pair data in a resource using the write_output utility function. Those values held by the resource can then be referenced as environment variables by any subsequently executing step that uses that resource as an input. In this way, a step can pass information to another step in the run of the pipeline.

The environment variable for the stored value will be of the form res_<resource name>_<key name>.  

For example, the following write_output command:

will store the string value of description in the resource. Any step can then access that value stored in myResource through the environment variable $res_myResource_description.

For more information, see Creating Stateful Pipelines.

Resource types

These are the types of resources that JFrog Pipelines supports:

• Aql — An Aql resource specifies an Artifactory query using Artifactory Query Language. 
• BuildInfo — A BuildInfo resource is the metadata associated with a build in Artifactory.
• CronTrigger — A CronTrigger is used as an inputResource to a step to trigger execution of the step at a scheduled time.
• DistributionRule — A DistributionRule resource is the set of Destination rules that can be applied to distributing a release bundle using JFrog Distribution. 
• FileSpec — A FileSpec resource specifies a File Spec, which provides the details of files to upload or download from Artifactory.
• GitRepo — A GitRepo is used to connect JFrog Pipelines to a source control repository. Adding it creates a webhook to the repo so that future commits will automatically create a new version with the webhook payload.
• HelmChart — The HelmChart resource maps to a specific chart in an Artifactory Helm Repository. 
• Image — An Image resource is used to add a reference to a Docker image to your pipeline.
• IncomingWebhook — An IncomingWebhook resource can trigger one or more jobs in your pipeline whenever the associated URL is called using the HTTP POST method. 
• OutgoingWebhook — An OutgoingWebhook resource sends information by HTTP from a step to an external API endpoint through an Outgoing Webhook Integration.
• PropertyBag — A PropertyBag resource is used to pass information from one pipeline to another and to provide environment variables to a step in the format of a resource.
• ReleaseBundle — A ReleaseBundle resource specifies a set of artifacts in Artifactory that are distributed to Artifactory Edge nodes as a JFrog Distribution Release Bundle.
• RemoteFile — A RemoteFile resource enables using a file on a remote file server. 
• VmCluster — A VmCluster is used to represent a set of virtual machines.  It is predominantly used to deploy services/apps to the specified cluster(s) and in some cases it can also be used to run certain maintenance activities on the cluster(s) as a whole.