UploadArtifact

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

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

onExecute, onStart, onSuccess, onFailure, 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)