Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >

Search





Overview

Resources typically contain information needed for a step in a pipeline to execute and can also be used to store information produced by a step. Resources defined should be unique across all the pipelines in a Project, which also provides a way to link pipelines. 


Commonly used examples of a resource are:

  • A repository in your source code control system (e.g., GitHub)
  • A file on a remote file server
  • A Docker image
  • A release bundle for JFrog Distribution
  • A cluster for container orchestration



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>
TagDescription of usageRequired/Optional
name

An alphanumeric string (underscores are permitted) that makes it easy to infer what the resource represents, e.g., aws_creds to represent AWS keys. This name is used to refer to the resource in steps, and must be unique across all repositories in your JFrog Pipelines Project.

Required
type

Name of the resource type that this resource is an instance of. A list of all types is below.

Required
configuration

Specifies configuration settings, which vary for each type of resource.

Commonly included in this block is a setting that assigns by its name an integration through which the resource will be accessed. The integration must be compatible with the type of the resource. The name of the integration field will vary by the resource. 

Required

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 be included in the resource in inputResources or outputResources.
  • To use a resource from a single-branch pipeline, branch should not be specified. 

Resources can be used by steps in these ways:

Inputs

When specified in a step in the inputResources section of a Pipeline or Step, 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 as false, the step is executed, and 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 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>

Example

If the definition of a GitRepo resource named app_gitrepo is as follows:

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:

Environment VariableResultDescription
res_app_gitRepo_pathuser1/repo1Returns the path attribute of the app_gitRepo resource
res_app_gitRepo_gitProvider_url
Returns url of the Git Provider of the app_gitRepo resource

Example

This 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 is 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:

write_output myResource "description=\"hello world\""

For more information, see Creating Stateful Pipelines.


Resource types

These are the types of resources that JFrog Pipelines supports:

  • AqlAn Aql resource specifies an Artifactory query using Artifactory Query Language. 
  • BuildInfoA BuildInfo resource is the metadata associated with a build in Artifactory.
  • CronTriggerA CronTrigger is used as an inputResource to a step to trigger execution of the step at a scheduled time or at a recurring interval. 
  • DistributionRuleA DistributionRule resource is the set of Destination rules that can be applied to distributing a release bundle using JFrog Distribution. 
  • FileSpecA FileSpec resource specifies a File Spec, which provides the details of files to upload or download from Artifactory.
  • GitRepoA 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.
  • HelmChartThe HelmChart resource maps to a specific chart in an Artifactory Helm Repository.
  • ImageAn Image resource is used to add a reference to a Docker image to your pipeline.
  • IncomingWebhookAn IncomingWebhook resource can trigger one or more jobs in your pipeline whenever the associated URL is called using the HTTP POST method. 
  • OutgoingWebhookAn OutgoingWebhook resource uses HTTP to send information from a step to an external API endpoint through an Outgoing Webhook Integration.
  • PropertyBagA PropertyBag resource is used to pass information from one pipeline to another and provide environment variables to a step in the format of a resource.
  • ReleaseBundleA ReleaseBundle resource specifies a set of artifacts in Artifactory that are distributed to Artifactory Edge nodes as a JFrog Distribution Release Bundle.
  • RemoteFileA RemoteFile resource enables using a file on a remote file server. 
  • VmClusterA VmCluster is used to represent a set of virtual machines.  It is mainly used to deploy services/apps to the specified clusters and in some cases, it can be used to run certain maintenance activities on the clusters as a whole.

  • No labels
Copyright © 2021 JFrog Ltd.