Semaphore provides a persistent artifact store for all projects. Artifacts are ideal for:
- Collecting debug data from your jobs (ex. screenshots, screencasts, build logs)
- Passing data and executables between jobs in a single workflow (ex. building an executable in the first job and passing it to upstream jobs for testing)
- Long-term storage of final deliverables (ex. storing release v1.0.12 of a CLI application)
Types of artifacts#
Semaphore has three levels of artifact stores: job, workflow, and project.
Each job and workflow has its own namespaced artifact store, while on the project level there is a single artifact store for the whole project.
Each artifact type has its primary use case:
- Job artifacts are suitable for collecting debug data
- Workflow artifacts are ideal for passing data from one job to another
- Project artifacts are ideal for storing final deliverables.
The primary use case for job artifacts is storing logs, screenshots, and other files that make debugging easier.
To upload files to the job artifacts store, use the built-in artifact CLI.
artifact push job <my_file_or_dir>
Here is a complete example that uploads test logs and screenshots produced by your tests.
blocks: - name: Build app task: jobs: - name: Tests commands: - make test epilogue: always: commands: - artifact push job logs/test.log - artifact push job screenshots
In the previous example, we use epilogue always commands to ensure that artifacts are uploaded for both passed and failed jobs.
You can view the stored files from a job's page. Go to the job page and click on the "Artifacts" tab to see artifacts uploaded by this job.
The primary use case for workflow artifacts is storing various build and test reports and passing data and executables between jobs in a single workflow.
To upload files to the workflow artifacts store, use the built-in artifact CLI:
artifact push workflow <my_file_or_dir>
To download files from the workflow artifacts store:
artifact pull workflow <my_file_or_dir>
Here is a complete example that shows how to build a release in the first block and use it in the upstream blocks of the workflow.
blocks: - name: Build app task: jobs: - name: Make commands: - make - artifact push workflow app - name: Test task: jobs: - name: Unit tests commands: - artifact pull workflow app - make test - name: Integration tests commands: - artifact pull workflow app - make integration-tests
In the above example, we build the application in the "Build app" block and then pull that application in the "Test" block for unit and integration tests.
You can view the stored files from a workflow page. Go to the workflow page and click on the "Artifacts" tab to see artifacts uploaded in this workflow.
The primary use case for project artifacts is storing the final deliverables of the CI/CD process.
To upload project artifacts from any job of any workflow use:
artifact push project myapp-v1.25.tar.gz
Similarly, use the
pull command if you want to download a file from
the project-level artifact store.
artifact pull project myapp-v1.25.tar.gz
To access them in the UI, click the "Artifacts" button on the project page.
Artifact retention policies#
By default, artifacts are persisted and never automatically deleted. If you want to limit the lifetime of the artifacts in your project, you can set up artifact retention policies in your project.
For example, if you want to delete every job and workflow artifact after a week, go to your project settings and set up retention policies for job and workflow artifacts.
Applying different retention policies to different folders#
Some artifacts have higher values, and you might want to extend their lifetime.
For example, test screenshots saved on the job level typically lose their value after a couple of days, while the test logs can offer a high value for several months.
We can set up a retention policy that matches that matches our previous needs. One week for screenshots and three months for test logs. We can also go ahead and set one months for any other file:
To do this, we will use the following configuration for job level artifacts:
/screenshots/**/*.png 1 week /logs/**/*.txt 3 months /**/* 1 month
The format of the selector patterns and the available options are further described in the Artifact Retention Policy Reference.
Artifacts are a paid feature and users are charged on the basis of two parameters:
- Storage - The amount of data stored in your artifact buckets. This is charged in GB per month, where one "unit" represents 1 GB of data stored for one month.
- Traffic - Network traffic generated by downloading artifacts within jobs or to an external location. This is charged in GB, where one "unit" represents 1 GB of transferred data.