FileSpec

JFrog Pipelines Documentation
ft:sourceType
Paligo

A FileSpec resource specifies a File Spec, which provides the details of files to upload or download from Artifactory.Using File Specs

Specifying a FileSpec in a step's inputResources downloads matching files and makes them available to that step.

Specifying a FileSpec in a step's outputResources signals a subsequent step that is dependent on that FileSpec to trigger. No file upload occurs.

Remote Repositories

FileSpecs will not currently download artifacts from remote repositories in Artifactory. To do so, you must use the API in a step. The recommended way to do this is to use curl command in the JFrog CLI in a step. For example:

jfrog rt curl "my-github-remote-repo/mikefarah/yq/releases/download/v4.24.4/yq_linux_amd64.tar.gz" -O
YAML Schema
resources:
  - name:               <string>
    type:               FileSpec
    configuration:      
      sourceArtifactory:        artifactoryIntegration
      pattern:                          <string>   # required, either this or aql
      aql:                                      <string>   # required, either this or pattern
      target:                           <string>   # optional
      props:                            <string>   # optional
      recursive:                        <boolean>  # optional
      flat:                             <boolean>  # optional
      excludePatterns:          <string>   # optional
      archiveEntries:           <string>   # optional
      buildName:                        <string>   # optional
      buildNumber:                      <integer>  # optional
      sortBy:                           <string>   # optional
      sortOrder:                        <string>   # optional
      limit:                            <integer>  # optional
      offset:                           <integer>  # optional
Tags
name

An alphanumeric string (underscores are permitted) that identifies the resource.

type

Must be FileSpec for this resource type.

configuration

Specifies all configuration selections for the resource.

Tag

Description

Required/Optional

sourceArtifactory

The name of the Artifactory Integration integration.

Required

pattern

Specifies the source path in Artifactory, from which the artifacts should be downloaded, in the following format: [repository name]/[repository path]. You can use wildcards to specify multiple artifacts.

Required if aql is not specified

aql

An AQL query that specified the artifacts to be downloaded.

Required if pattern is not specified

target

Specifies the local file system path to which artifacts should be downloaded.

For flexibility in specifying the target path, you can include placeholders in the form of {1}, {2}, {3}....These are replaced by corresponding tokens in the pattern property that are enclosed in parenthesis. For more information, see Using Placeholders.Using File Specs

Optional

props

List of "key=value" pairs separated by a semi-colon. (For example, "key1=value1;key2=value2;key3= value3"). Only artifacts with all the specified properties and values will be downloaded.

Optional

flat

[Default: false]

If true, artifacts are downloaded to the exact target path specified and their hierarchy in the source repository is ignored.

If false, artifacts are downloaded to the target path in the file system while maintaining their hierarchy in the source repository.

Optional

recursive

[Default: true]

If true, artifacts are also downloaded from sub-paths under the specified path in the source repository.

If false, only artifacts in the specified source path directory are downloaded.

Optional

excludePatterns

[Applicable only when 'pattern' is specified]

An array (enclosed with square brackets) of patterns to be excluded from downloading. Unlike the "pattern" property, "excludePatterns" must NOT include the repository as part of the pattern's path. You can use wildcards to specify multiple artifacts.

For example: ["*.sha1","*.md5"]

Optional

archiveEntries

If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.

Optional

buildName

The name of the build to associate with this BuildInfo. Recommend using the environment variable available from the step that generated the build.

Optional

buildNumber

The number of the build to associate with this BuildInfo. Recommend using the environment variable available from the step that generated the build.

Optional

sortBy

A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation.Artifactory Query Language

Optional

sortOrder

[Default: asc]

The order by which fields in the sortBy option should be sorted. Accepts asc or desc.

Optional

limit

The maximum number of items to fetch. Usually used with the sortBy option.

Optional

offset

The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the sortBy option.

Optional

For the remaining values, see the Artifactory topic Using File Specs.Using File Specs

Environment Variables

Whenever FileSpec is used in a step, a set of environment variables is automatically made available that you can use in your step.

Environment Variable

Description

res_<resource_name>_resourcePath

Path to where the File Spec is downloaded to

res_<resource_name>_name

Name of the resource

res_<resource_name>_sourceArtifactory

The name of the Artifactory integration

Examples

Example 1

This example uses the following tags:

  • sourceArtifactory

  • pattern

  • recursive

  • offset

resources:
  - name: FileSpec_0014
    type: FileSpec
    configuration:
      sourceArtifactory: s_artifactory
      pattern: "test-local/setup/"
      recursive: false
      offset: 1@3

pipelines:
  - name: pipelines_FLSPEC_0014
    steps:
      - name: step_FLSPEC_0014
        type: PowerShell
        configuration:
          nodePool: win_2019
          inputResources:
            - name: FileSpec_0014
        execution:
          onExecute:
            - write-output "executing step..."

Example 2

This example uses the following tags:

  • sourceArtifactory

  • pattern

  • recursive

  • limit

  • sortBy

  • sortOrder

  • target

resources:
  - name: FileSpec_0013
    type: FileSpec
    configuration:
      sourceArtifactory: s_artifactory
      pattern: "test-local/setup/"
      recursive: false
      limit: 1@3
      sortBy:
        - created
      sortOrder: invalid
      target: 'C:\Users\pipelines\Desktop\'

pipelines:

  - name: pipelines_FLSPEC_0013
    steps:
      - name: step_FLSPEC_0013
        type: PowerShell
        configuration:
          nodePool: win_2019
          inputResources:
            - name: FileSpec_0013
        execution:
          onExecute:
            - write-output "executing step..."

Example 3

This example uses the following tags:

  • sourceArtifactory

  • pattern

  • recursive

  • buildName

  • buildNumber

resources:
  - name: FileSpec_0010
    type: FileSpec
    configuration:
      sourceArtifactory: s_artifactory
      pattern: "test-local/setup/"
      recursive: false
          buildName: pipelines_api
      buildNumber: 1@3

pipelines:
  - name: pipelines_FLSPEC_0010
    steps:
      - name: step_FLSPEC_0010
        type: PowerShell
        configuration:
          nodePool: win_2019
          inputResources:
            - name: FileSpec_0010
        execution:
          onExecute:
            - write-output "executing step..."

Example 4

This example uses the following tags:

  • sourceArtifactory

  • pattern

  • recursive

  • archiveEntries

resources:
  - name: FileSpec_0007
    type: FileSpec
    configuration:
      sourceArtifactory: s_artifactory
      pattern: "test-local/setup/"
      recursive: false
      archiveEntries: "#/artifactory"

pipelines:
  - name: pipelines_FLSPEC_0007
    steps:
      - name: step_FLSPEC_0007
        type: PowerShell
        configuration:
          nodePool: win_2019
          inputResources:
            - name: FileSpec_0007
        execution:
          onExecute:
            - write-output "executing step..."

Example 5

This example uses the following tags:

  • sourceArtifactory

  • aql

resources:
  - name: Get_Files
    type: FileSpec
    configuration:
      sourceArtifactory: s_artifactory
      aql: "{'repo': 'docker-local'}"
    
pipelines:
  - name: PropertyDemo
    steps:
      - name: ArtifactoryFiles
        type: Bash
        configuration:
          inputResources:
            - name: Get_Files
        execution:
          onExecute:
            - cat $HOME/.jfrog/logs/jfrog-cli*
            - ls