Use Workspaces
Workspaces #
Workspaces allow jobs within a build to share files. They are useful when you want to use build artifacts from a previous job; for example, you create a cache that can be used in multiple jobs later.
So you can clearly see when a workspace is created and used, we recommend using workspaces with build stages, as shown in the following examples.
Note that it is best to create a workspace in one stage and then use it in subsequent stages.
Configuration #
A minimal workspace configuration looks like this:
Each workspace has a unique name within a build.
It is specified by the name
key when it is created with
workspaces.create
, and by the value when it is used with
workspaces.use
.
In the example above, the workspace named ws1
is created by the only
job in the warm_cache
stage.
The workspace is subsequently consumed in the use_cache
stage.
Workspace examples #
The following section shows different workspace examples.
Multiple Workspaces example #
You can use multiple workspaces in a build.
In this example:
- we run two jobs in the “Build binaries” stage, each producing uploading binaries.
- in the subsequent “Deploy” stage, we fetch the workspaces produced by the jobs in the previous stage, and deploy it using a custom script.
A more explicit example below:
In the above example:
- Build stage “Build and Test” consists of 3 jobs, each of them producing output to a separate workspace
- Build stage “Deploy” consists of one job, which
- Marks usage of all 3 previosuly created workspaces
- pulls data out of each previously created workspace and echoes it to standard output to demonstrate ability to access workspace
Workspaces and Concurrency #
Note that workspaces work best if there is no race condition set while uploading them. Since there is no guarantee in the execution order of jobs within a build stage, it is a good idea to assign different workspace names to jobs within a build stage.
Pre-determined Workspace names #
Due to technical reasons, workspace names will be escaped for shell. In other words, given:
it will have to be consumed by
and not by
even if the consumer is running on a Linux VM.
How Workspaces differ from caches #
It is worth reiterating that the workspaces are meant for sharing files within the same build. For files you want to share across builds, use caches.
Workspaces and caches are considered independently #
It is possible to include a single file in the cache and workspaces.
If you restart some builds within a job, and your workspace isn’t working like you expect it to, try restarting the entire build.