Custom Artifact Source

Updated 1 week ago by Michael Cretzman

Harness includes first-class support for all of the popular repositories. The Custom Artifact Source is provided for enterprises that use a custom repository.

To use this artifact source, you provide a script to query your artifact server via its API (for example, REST) and then Harness stores the output on the Harness Delegate in the Harness-initialized variable ${ARTIFACT_RESULT_PATH}. The output must be a JSON array, with a mandatory key for a Build Number. You then map a key from your JSON output to the Build Number.

Add a Custom Artifact Source

To use a Custom Artifact Source, do the following:

  1. In your Harness Application, open the Service where you want to use a Custom Artifact Source.
  2. Click Add Artifact Source, and then click Custom Repository.
    The Add Custom Artifact Source dialog appears.
  3. Fill out the Add Custom Artifact Source dialog fields as described below.
  • Source Type - Select Custom.
  • Display Name - Enter a name to identify this custom artifact source. You will use this name when picking the artifact builds and versions during deployment.
  • Script - Enter a shell script that pulls the artifact from the custom repo to a file path on the Harness Delegate host. See Custom Artifact Source Script.
  • Delegate Tags - Enter Delegate Tag names of one or more Harness Delegates to use when executing the script. The Delegates you identify should have network access to the custom repo in order to obtain any artifacts. See Delegate Tags.
  • Timeout - Enter a time limit for the script to execute before failing the artifact retrieval.
  • Query Result to Artifact Mapping - See Query Result to Artifact Mapping.

Custom Artifact Source Script

The shell script you enter will query the custom artifact repository for your artifact, and output the result to a file on the Harness Delegate host using the environment variable ARTIFACT_RESULT_PATH, initialized by Harness. ARTIFACT_RESULT_PATH is a random, unique file path created on the Delegate by Harness.

The script you enter should result in a JSON array, for example:

"items" : [ {
"repository" : "maven-releases",
"format" : "maven2",
"group" : "mygroup",
"name" : "myartifact",
"version" : "1.0",
"assets" : [ {
"downloadUrl" : "",
"path" : "mygroup/myartifact/1.0/myartifact-1.0.war",
"repository" : "maven-releases",
"format" : "maven2",
"checksum" : {
"sha1" : "da39a3eXXXXXXXXXXXXX95601890afd80709",
"md5" : "d41d8cdXXXXXXXXXXXXX998ecf8427e"
}, {
"downloadUrl" : "",
"path" : "mygroup/myartifact/1.0/myartifact-1.0.war.md5",
"repository" : "maven-releases",
"format" : "maven2",
"checksum" : {
"sha1" : "67a74306XXXXXXXXXXXXX570f4d093747",
"md5" : "74beXXXXXXXXXXXXX56088456"

Harness will read the file, process it, and make the artifacts available for deployment in your Workflows and Pipelines.

The following example pulls an artifact from a repo and outputs it to the ARTIFACT_RESULT_PATH:

curl -X GET "" \
-H "accept: application/json" > ${ARTIFACT_RESULT_PATH}

Here is an example using a Harness encrypted text secret for credentials:

curl -u 'harness' ${secrets.getValue("repo_password")} > ARTIFACT_RESULT_PATH

For more information, see Secrets Management.

The expected output from the shell script is a JSON structure with an array, where every element represents an artifact object. You map the array object using Query Result to Artifact Mapping.

Query Result to Artifact Mapping

Use the Query Result to Artifact Mapping section to map the JSON key from your script to the artifact Build Number.

In Artifacts Array Path, enter the root object of the array. For example, if your array object starts with {"items" : [ {...},{...} then enter $.items in Artifacts Array Path.

Next, in Build No. Path, enter the key to use as the buildNo, such as version.

Once mapped, you can reference the build number using the expression ${artifact.buildNo}.

Additional Attributes

In Additional Attributes, you can map any additional values from your JSON array.

For example, if a subsection of your array contains the download URL, such as "assets":[ {"downloadUrl"... you enter assets[0].downloadUrl in Path and URL in Name. Later in your Workflow you can reference the URL with ${artifact.URL}.

Using Custom Artifact Source in Workflows

There are two ways you can use the Custom Artifact Source in a Workflow:

  • Artifact Collection command - In a Build Workflow, you can use the Artifact Collection command to collect the artifact using the Custom Artifact Source. This is the most common use of the Custom Artifact Source.
  • Shell Script command - In all Workflow types, you can add a Shell Script command to reference the Custom Artifact Source.

Artifact Collection Command

Typically, a Build Workflow is used in a Pipeline to perform standard CI of an artifact and is followed by another Workflow to perform the deployment of the built artifact.

The way the Build Workflow performs CI is to run a Jenkins or Shell Script command to execute the build and store a variable with the build information, and then the Artifact Collection command collects the built artifact using the output variable and the Workflow deploys it. For information on the Jenkins and Shell Script commands, see Using the Jenkins Command and Using the Shell Script Command.

The following image shows the Jenkins step build and store a variable named Jenkins, and then the Artifact Collection step uses the Custom Artifact Source and the ${Jenkins.description} variable to reference the new build.

Now that the artifact is collected, a second Workflow can deploy the artifact.

Shell Script Command

For any Workflow type, you can reference the Custom Artifact Source using the Shell Script command and a variable reference to the build number, ${artifact.buildNo}:


When you deploy the Workflows with a Service that uses a Custom Artifact Source, you can select which artifact build to select.

How did we do?