UploadArtifact

JFrog Pipelines Documentation

ft:sourceType
Paligo

The UploadArtifact native step uploads artifacts to Artifactory. Optionally, it can also publish build information to Artifactory and trigger Xray scans.

This step utilizes the JFrog CLI to upload an artifact to Artifactory. The file(s) may be provided in a FileSpec, if already in Artifactory, or RemoteFile or GitRepo input.

YAML Schema

The YAML schema for UploadArtifact native step is as follows:

UploadArtifact

pipelines: 
  - name:   <string>
    steps:
      - name: <string>
        type: UploadArtifact
        configuration:
          targetPath:           <string>  #required
          sourcePath:           <string>  #optional
          properties:           <string>  #optional
                  regExp:                       <boolean> #optional
          flat:                 <boolean> #optional
                  module:                       <string>  #optional
                  deb:                  <string>  #optional
                  recursive:                <boolean>     #optional
                  dryRun:                       <boolean> #optional
          symlinks:                     <boolean> #optional
          explode:                      <boolean> #optional
          exclusions:               <string>      #optional
          includeDirs:              <boolean>     #optional
          syncDeletes:              <string>      #optional
          forceXrayScan:                <boolean> #optional
          failOnScan:           <boolean>   # default true
                  autoPublishBuildInfo: <boolean> #optional
          inputResources:
                        - name: myGitRepo       
                        - name: artifactoryFileSpec     
            - name: myRemoteFile        
                  outputResources:
            - name: myFileSpec
                        - name: myBuildInfo
          integrations:
                        - name: myArtifactory 
        execution:
          onStart:
            - echo "Preparing for work..."
          onSuccess:
            - echo "Job well done!"
          onFailure:
            - echo "uh oh, something went wrong"
          onComplete: #always
            - echo "Cleaning up some stuff"
Tags
name

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

type

Must be UploadArtifact for this step type.

configuration

Specifies all configuration selections for the step's execution environment. This step inherits the Bash/ PowerShell step configuration tags, including these pertinent tags:

Tag

Description of usage

Required/Optional

integrations

Must specify an Artifactory Integration.

Required

inputResources

May specify a GitRepo, FileSpec, or RemoteFile resource containing the file(s) to be uploaded. One of each type may be specified.

Optional

outputResources

Must specify a BuildInfo resource if autoPublishBuildInfo is set as true.

If JFROG_CLI_BUILD_NAME or JFROG_CLI_BUILD_NUMBER is set as an environment variable for the pipeline or the step, that name and/or number is used for the output BuildInfo. Otherwise, the default buildName and buildNumber are $pipeline_name and $run_number.

May also specify a FileSpec resource to be updated with the pattern and properties of the uploaded Artifact.

May be required

In addition, these tags can be defined to support the step's native operation:

Tag

Description of usage

Required/Optional

targetPath

Path to upload the files, including repository name.

Required

sourcePath

Files to upload. If this is a relative path pattern, it is relative to the root of a GitRepo/FileSpec/RemoteFile input.

Default is * when regExp is false and .* when regExp is true.

Optional

properties

Semi-colon separated properties for the uploaded artifact. For example: myFirstProperty=one;mySecondProperty=two.

Properties pipelines_step_name, pipelines_run_number, pipelines_step_id, pipelines_pipeline_name, pipelines_step_url, pipelines_step_type, and pipelines_step_platform will also be added.

Optional

regExp

When set as true, regular expressions are used in other parameters, such as sourcePath, instead of wildcards. Expressions must be in parentheses.

Default is false.

Optional

flat

When set as true, the uploaded files are flattened, removing the directory structure.

Default is false.

Optional

module

A module name for the Build Info.

Optional

deb

A distribution/component/architecture for Debian packages. If the distribution, component, or architecture includes a / it must be double-escaped, For example: distribution/my\\\/component/architecture for a my/component component.

Optional

recursive

When set as false, do not upload any matches in subdirectories.

Default is true.

Optional

dryRun

When set as true, nothing is uploaded.

Default is false.

Optional

symlinks

When set as true, symlinks matching the other criteria are uploaded.

Default is false.

Optional

explode

When set as true and the uploaded Artifact is an archive, the archive is expanded.

Default is false.

Optional

exclusions

Semi-colon separated patterns to exclude.

Optional

includeDirs

When set as true, empty directories matching the criteria are uploaded.

Default is false.

Optional

syncDeletes

A path under which to delete any existing files in Artifactory.

Optional

forceXrayScan

When set as true, forces an Xray scan after publishing to Artifactory.

Default is false.

Optional

failOnScan

When set as true, and when the Xray Policy Rule Fail Build checkbox is checked, a failed Xray scan will result in a failure of the step.Creating Xray Policies and Rules

Default is true.

Optional

autoPublishBuildInfo

When set as true, publishes build info to Artifactory.

Default is false.

Optional

execution

Declares collections of shell command sequences to perform for pre- and post-execution phases:

Tag

Description of usage

Required/Optional

onStart

Commands to execute in advance of the native operation

Optional

onSuccess

Commands to execute on successful completion

Optional

onFailure

Commands to execute on failed completion

Optional

onComplete

Commands to execute on any completion

Optional

The actions performed for the onExecute phase are inherent to this step type and may not be overridden.

Note

onExecuteonStartonSuccessonFailure, and onComplete are reserved keywords. Using these keywords in any other context in your execution scripts can cause unexpected behavior.

Examples

The following examples show a few ways in which a UploadArtifact step can be configured.

Uploading an Artifact to Another Repository using a FileSpec Resource

The most basic form of UploadArtifact. Uses all default values. This step will download the file matching the FileSpec and upload it to the location in targetPath. The optional output FileSpec resource will be updated with the targetPath and the default properties added to the uploaded artifact.

UploadArtifact

pipelines: 
  - name: uploadArtifactPipeline
    steps:
      - name: uploadArtifactStep
        type: UploadArtifact
        configuration:
          targetPath: my-repository/myDirectory/myFile.txt
          integrations:
            - name: myArtifactoryIntegration
          inputResources:
            - name: myInputFileSpec
          outputResources:
            - name: myOutputFileSpec
Uploading an Artifact from a RemoteFile Resource

In this example, the input is a RemoteFile resource. Otherwise, this is very similar to the previous example with an input that downloads a file that is then uploaded and an optional FileSpec output updated for the uploaded file.

UploadArtifact

pipelines: 
  - name: uploadArtifactPipeline
    steps:
      - name: uploadArtifactStep
        type: UploadArtifact
        configuration:
          targetPath: my-repository/myDirectory/myFile.txt
          integrations:
            - name: myArtifactoryIntegration
          inputResources:
            - name: myInputRemoteFile
          outputResources:
            - name: myOutputFileSpec
Publish Build Info and Trigger Xray Scan

In this example, build info is published as part of the UploadArtifact step and an Xray scan is triggered.

UploadArtifact

pipelines: 
  - name: uploadArtifactPipeline
    steps:
      - name: uploadArtifactStep
        type: UploadArtifact
        configuration:
          targetPath: my-repository/myDirectory/myFile.txt
          autoPublishBuildInfo: true
          forceXrayScan: true
          integrations:
            - name: myArtifactoryIntegration
          inputResources:
            - name: myFileSpec
          outputResources:
                        - name: myBuildInfo
How it Works

When you use the UploadArtifact native step in a pipeline, it performs the following functions in the background:

  • jfrog rt config (configure JFrog CLI with the integration listed in the yaml)

  • jfrog rt use (configure JFrog CLI to use the config for the integration listed in the yaml)

  • mkdir (create a directory to use as the root of relative paths in the following actions)

  • cp (copy the FileSpec, RemoteFile, or GitRepo files to the new directory, limit one of each input type)

  • jfrog rt upload (upload the Artifact)

  • write_output (update the FileSpec output resource with the uploaded pattern and properties)

  • add_run_variables (save information in run state for future steps to reference)

  • jfrog rt build-collect-env (collect the build environment, preparing for build publish)

  • jfrog rt build-publish (publish the build, only if autoPublishBuildInfo is true)

  • write_output (update the BuildInfo output resource with the published name/number)

  • jfrog rt build-scan (if forceXrayScan is true)

  • add_run_files (adds build info to run state)