This documentation is for the Technical Preview of JFrog Pipelines, available exclusively to JFrog Enterprise+ customers
.

Skip to end of metadata
Go to start of metadata

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. Because of that they also provide the way to link pipelines. 


A key characteristic of resources is that they can be versioned. A specific version of a resource is immutable, i.e. it returns the same result every single time it is fetched. For example, a commit in a Git repository causes a new SHA to be generated and in turn creating a new version of the GitRepo Resource.

A new version is created by

  1. an external event like Git commit
  2. a step generating an output resource

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


Page Contents

YAML 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>
TagRequiredDescription of usage
name

REQUIRED

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 environment.

type

REQUIRED

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

configuration

REQUIRED

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. 


Using Resources

Resources can be inputs and outputs of steps in a pipeline. 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. 

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:

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


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>



Resource types

These are the types of resources that JFrog Pipelines supports:

  • Aql

    An Aql resource specifies an Artifactory query using Artifactory Query Language. Aql resource can be used as input resource for the CreateResleaseBundle step. It defines the query that is used to create a release bundle from. 


  • BuildInfo

    A Buildinfo resource is the metadata associated with a build in Artifactory. JFrog Pipelines automatically creates BuildInfo when any of the Build steps like MvnBuild, NpmBuild, or DockerBuild are used to generate packages. BuildInfo is published to Artifactory through the PublishBuildInfo step,, by setting a flag in Build steps or by using push steps like NpmPublish and DockerPush.    


  • DistributionRule

    DistributionRule resource is the set of Destination rules that can be applied to distributing a release bundle using JFrog Distribution. 


  • FileSpec

    FileSpec resource specifies a File Spec, which provides the details of files to upload or download to or from in 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.


  • Image

    An Image resource is used to add a reference to a Docker image to your pipeline. Image resource can be used as both input and output. Step like DockerBuild will generate it as an output and steps like DockerPublish will use it as input to publish to a Docker registry.


  • KubeCluster

    A KubeCluster is used to represent a Kubernetes container orchestration system. It is predominantly used to deploy services/apps to the specified cluster and in some cases it can also be used to run certain maintenance activities on the cluster as a whole.


  • ReleaseBundle

    ReleaseBundle resource specifies a set of artifacts in Artifactory that are distributed to Artifactory Edge nodes as a JFrog Distribution Release Bundle. This resource can be used with CreateReleaseBundle, SignReleaseBundle or DistributeReleaseBundle. This resource can be used to represent both signed and unsigned Release Bundle.  


  • RemoteFile

    A RemoteFile resource allows using a File on a remote file server in the pipeline. 


  • VmCluster

    A VmCluster is used to represent a set of virtual machines.  It is predominantly used to deploy services/apps to the specified cluster and in some cases it can also be used to run certain maintenance activities on the cluster as a whole.


  • Webhook

    Webhook resource can trigger one or more jobs in your pipeline whenever the associated URL is called using the HTTP POST method. 


  • No labels