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

Search





Overview

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.

Page Contents


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

integrationsMust specify an Artifactory Integration.Required
inputResources 

May specify GitRepoFileSpec, 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
targetPathPath 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
debA 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
dryRunWhen set as true, nothing is uploaded.

Default is false.

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

Default is false.

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

Default is false.

Optional
exclusionsSemi-colon separated patterns to exclude.Optional
includeDirsWhen set as true, empty directories matching the criteria are uploaded.

Default is false.

Optional
syncDeletesA 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.

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:

TagDescription of usageRequired/Optional
onStartCommands to execute in advance of the native operationOptional
onSuccessCommands to execute on successful completionOptional
onFailureCommands to execute on failed completionOptional
onCompleteCommands to execute on any completionOptional


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


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)
  • No labels
Copyright © 2021 JFrog Ltd.