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:
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. 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
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:
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 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
.
Archive files and directories
Set archive = true
to archive a file or a directory before uploading it to the storage. For example:
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 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
:
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 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:
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.