Store File Artifacts

Build artifacts are the outputs of a build process, for example, these could be files generated as a result of code compilation. If you build a CI/CD pipeline using Automation, you can pass file artifacts created by one job (a CI/CD stage) to another. If creating a file artifact is a final result of your build process, you can store this artifact in a file repository.

Default artifact repository

Projects in Space can have associated default file repositories for build artifacts.

Each project has its own default file repository with corresponding access restrictions (only for project members).
The repository is created automatically when you run the job that references the default repository (e.g., uploads a file) for the first time.
In a script, you can get the name of the default file repository from the run:file-artifacts.default-repository parameter.
Instead of the default file repository, a job can use any file repository in Packages.
The default name of the default file repository is default-automation-files. You can change this name in Jobs | Settings under File Storage | File Artifact Repository.
You can use public file repositories for distribution of your build artifacts.

Upload file artifacts

To upload a file, depending on your run environment, use either the job.container.fileArtifacts or the job.host.fileArtifacts block:

job("Generate usage report") {
    container(displayName = "Report upload", image = "ubuntu") {
        shellScript {
            content = """
                echo Here go your build activities...
                echo Suppose, the result is /build/build.zip
                ./build.sh >> ./build/build.zip
            """
        }

        // Upload build/build.zip to the default file repository
        fileArtifacts {
            // To upload to another repo, uncomment the next line
            // repository = FileRepository(name = "my-file-repo", remoteBasePath = "{{ run:number }}")

            // Local path to artifact relative to working dir
            localPath = "build/build.zip"
            // Don't fail job if build.zip is not found
            optional = true
            // Target path to artifact in file repository.
            remotePath = "{{ run:number }}/build.zip"
            // Upload condition (job run result): SUCCESS (default), ERROR, ALWAYS
            onStatus = OnStatus.SUCCESS
        }
    }
}

Default upload path

The resulting path of a file artifact in the default repository is generated in the following way: <basePath>/<fileArtifacts.remotePath>:

<basePath> is resolved to {{ run:job.repository }}/jobs/{{ dashify('{{ run:job.name }}') }}-{{ run:job.id }}/{{ run:number }}-{{ run:id }}
These are provided parameters that represent:
- {{ run:job.repository }} – the name of the Git repository.
- dashify('{{ run:job.name }} – here {{ run:job.name }} is the job name. The dashify function replaces all special characters with the - dash symbol. For example, Build artifacts will translate to Build-artifacts
- {{ run:job.id }} – the job identifier.
- {{ run:number }} – the current job run number.
- {{ run:id }} – the current job run identifier.
<fileArtifacts.remotePath> is what you specified in a job in the remotePath parameter.

For example, the following code

// suppose the Git repo name is 'my-project'
// this is job run number '5'
// job execution id is 'IQ2qy0RwyJ5' (some random number)
// job run id is '1Euwjv1V3B9f' (some random number)
job("Generate zip file") {
    container(image = "ubuntu") {
        // Here goes some code...

        fileArtifacts {
            localPath = "build/build.zip"
            remotePath = "build/build.zip"
        }
    }
}

will put the build/build.zip file to the my-project/jobs/Generate-zip-file-IQ2qy0RwyJ5/5-1Euwjv1V3B9f/build/build.zip directory in the default file repository.

You can change the default base path in Jobs | Settings under File Storage | Base Path.

To upload to a path different from the default one, use the fileArtifacts.repository parameter:

// to upload files to the 'myfiles' folder in the default file repository
// the resulting path will be 'myfiles/build.zip'
fileArtifacts {
    repository = FileRepository(name = "default-automation-files", remoteBasePath = "myfiles")
    localPath = "build/build.zip"
    remotePath = "build.zip"
}

How to specify localPath

localPath defines the location of the file or directory to be saved. You can specify it with:

An absolute path, for example, /home/root/some-dir.
A path relative to the current home directory, for example, ~/.m2. You can use it only in job.host steps. In job.container step, you can use the same workaround as described here.
A path relative to the step working directory (by default, the project root), for example, build.

Archive files and directories

Set archive = true to archive a file or a directory before uploading it to the storage. For example:

// Space will archive the 'build' directory to a .zip file
fileArtifacts {
    localPath = "build"
    remotePath = "build.tar.gz"
    archive = true
}

Overwrite files in the file repository

File repositories in Space have the Immutable files option. If it's enabled, the repository prohibits uploading a file with the same path more than once. If it's disabled, the file can be overwritten. By default, this option is enabled for the default file repository.

Upload conditions

You can additionally specify a condition for uploading a file using the fileArtifacts.onStatus parameter. The following parameter values are possible:

OnStatus.SUCCESS – (default) upload a file only if the job finishes successfully.
OnStatus.ERROR – upload a file only if the job finishes with an error.
OnStatus.ALWAYS – always upload a file.

Upload file artifacts to a non-default repository

To upload artifacts to a repository different from the default one, use the fileArtifacts.repository parameter. Note that this repository must belong to the same project where you run the job.

// to upload files to 'my-file-repo'
fileArtifacts {
    repository = FileRepository(name = "my-file-repo", remoteBasePath = "{{ run:number }}")
    localPath = "build/build.zip"
    remotePath = "build.zip"
}

To upload artifacts to a file repository created in another project, you should first attach this repository to your current project.

Download and reuse file artifacts in a job

To speed up build times and reduce infrastructure load, you can reuse build artifacts from previous job executions in a new job run. To download a build artifact from a file repository, you should use the fileInput block. If an artifact is a .tar.gz archive that you want to extract, specify extract = true:

job("Reuse file artifact") {
    host("Run script from artifact") {
        // download file from the default file repo
        fileInput {
            // we use the provided parameter to reference the default repo
            source = FileSource.FileArtifact(
                "{{ run:file-artifacts.default-repository }}",
                "myfiles/build.tar.gz",
                // unzip the build.zip file
                extract = true
            )
            localPath = "build/build.zip"
        }

        shellScript {
            content = """
                chmod +x ./build/run_script.sh
                ./build/run_script.sh
            """
        }
    }
}

Get file artifacts from a non-default repository

To download file artifacts from a repository different from the default one, specify the repository name in FileSource.FileArtifact. Note that this repository must belong to the same project where you run the job.

// to download file from 'my-file-repo'
fileInput {
    source = FileSource.FileArtifact("my-file-repo", "myfiles/build.zip")
    localPath = "build/build.zip"
}

To download artifacts from a file repository created in another project, you should first attach this repository to your current project.

Other file sources

The fileInput.FileSource parameter lets you get files not only from file repositories but from other sources as well. As for now, only one more source is supported:

FileSource.Text lets you create files from a string (plain text). The main use-case of this is creating files from project secrets. Learn more

Continue job run if artifact is missing

By default, if the file artifact specified in fileInput.source is missing, the job fails. If you want the job to continue running, specify optional = true. For example:

fileInput {
    source = FileSource.FileArtifact(
        "{{ run:file-artifacts.default-repository }}",
        "myfiles/build.zip",
        // don't fail job if 'build.zip' is not found
        optional = true
    )
    localPath = "build/build.zip"
}

View and download build artifacts

To view and download build artifacts of a job run

Open the desired project.
On the sidebar menu, choose Jobs.
Open the desired job.
Open a specific job run attempt.
Open the Artifacts tab.
Click Download next to the required file.

To view all build artifacts in the project

Open the desired project.
On the sidebar menu, choose Packages.
Open the file repository that contains file artifacts. In case of the default file repository, that would be default-automation-files.

Last modified: 15 December 2023