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.
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.
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
}
}
}
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. Thedashify
function replaces all special characters with the-
dash symbol. For example,Build artifacts
will translate toBuild-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 theremotePath
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"
}
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 injob.host
steps. Injob.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
.
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
}
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.
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.
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.
note
This feature lets you reuse build artifacts. If you're looking for caching of project dependencies, refer to Cache Files.
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
"""
}
}
}
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.
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
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"
}
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.
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.
Thanks for your feedback!