Define and use workspaces

CloudBees CD/RO can handle any number of workspace roots, which are defined by selecting the Cloud  Workspaces tabs. To create a workspace root, provide a workspace name and three file paths for jobs to access the workspace:

During the CloudBees CD/RO installation, you had the option of defining a workspace. If you defined a workspace, it was named "default" and will be the default workspace for all jobs, as described below.

By default, remote workspaces are accessed with the agent user’s credentials. For Windows resources, you can override that user’s credential by attaching a credential to the workspace. Using a credential attached to a workspace is useful if the agent machine is not a member of the domain, but the workspace is located on a machine in the domain. An attached credential for a domain user allows the agent to manipulate the workspace as that domain user.

The simplest way to use workspaces is to define a single workspace named "default" that is readable and writable on all resources, and never specify any other workspace information. With this approach the default workspace will be used for all steps in all jobs.

However, you can also arrange for different jobs to use different workspaces, or even for different steps within a single job to use different workspaces.

You can specify a workspace name in any of the following CloudBees CD/RO objects:

If workspaces are defined in several of these places, the workspace for a particular step is chosen in priority order corresponding to the list above: a workspace specified in a step takes priority over all others, followed by a workspace in the procedure, project, and finally resource. If no workspace is specified in any of these locations, the workspace named "default" is used.

A job workspace directory name, within its workspace root, is derived from the name of the job. For example, if a job named "job_63" uses a workspace whose root directory is //ec/workspaces, the job workspace directory is //ec/workspaces/job_63. Changing the name of a job has no impact on workspace names: the initial name of the job is always used for workspace directory names.

A job is allocated a single job workspace only within a particular workspace root, which is shared by all steps that specify that root. For example, suppose a job has five steps:

The three steps that specify A all share a single directory under A, and the other two steps share a single directory under B.

By default, each job step begins execution with its current working directory set to the top-level directory in the job’s workspace. A job step can override this location by specifying an explicit working directory. If a job step specifies a relative path for its working directory, the path is relative to the top-level workspace directory.

The simplest way to set up CloudBees CD/RO is to make every workspace root accessible on every resource. This accessibility mode provides the most flexibility and simplifies CloudBees CD/RO system management

Unfortunately, some environments cannot allow such universal access. For example, some sites do not provide file sharing between UNIX and Windows machines. In large enterprise environments where CloudBees CD/RO is shared among multiple groups, you may want to partition resources among the groups and limit access by each group to the other groups' resources. In the most extreme case, you may not have network file sharing at all. CloudBees CD/RO can handle all of these cases.

If a workspace root is not accessible on a particular resource, you should not use that workspace in any step that runs on the resource. If you do, the resource is not able to create the job workspace directory and the step stalls until the issue is resolved. A workspace root (on a resource) must be both readable and writable to be used for job steps.

Before a job step can use a particular workspace, three access limitations must be satisfied:

Potentially, two system accounts can impact each job step execution:

Because of these requirements, you may end up with a configuration where any job step running in a workspace can read or write any file under that workspace root, including files from other jobs that share the same workspace root. In many environments this solution works, but in some situations you may want to prevent one job from accessing files from a different job.

To create job privacy, run all the job’s steps with credentials for a separate account. In addition, run a job step at the beginning of the job that creates a subdirectory within the job workspace and change the protection on that directory to permit access to the credentialed account only. Next, place all private files for the build in the protected subdirectory.

These files are not accessible to other jobs or the agent. The top-level directory in the job workspace still needs to be accessible to the agent, so it can read and write log files, but everything in the lower-level directory are private.

Configuration of a permission mask for Linux agent workspaces is available for CloudBees CD/RO v2023.08.0 and higher. Use the root workspace parameter workspaceMask to set default permissions for new agent workspace directories. To modify permissions for specific agent workspaces, use the `agentWorkspaceMask`parameter.

CloudBees CD/RO automatically places certain files in the top-level job step workspace directory:

Prior to the v9.1, CloudBees CD/RO did not provide a facility for automatically deleting old workspaces. This can now be selected when cleaning up runtime results by toggling Cleanup Associated Workspaces in the Data Retention feature. This feature relies on the resource associated with the original work to perform the cleanup activity and is a granular, or job-by-job, form of cleanup. If you delete a job manually or without using the Data Retention option, CloudBees CD/RO does not automatically delete its associated workspace files from the workspace folder.

If files remain in the workspace for any reason and you no longer need them, then clearing out files via a Linux or Windows script is the recommended method to clear out large blocks of files quickly. Typically, set up rules to run on a 6-month schedule.

When CloudBees CD/RO agents (on platforms other than Linux or Windows) run steps that create log files in a workspace the CloudBees CD/RO web server cannot access (through Linux or Windows agents), use the ecremotefilecopy tool to recreate job logs, so they are visible on those CloudBees CD/RO agents, which then enables the web server to retrieve and render those log files.

ecremotefilecopy is installed with CloudBees CD/RO. For more information, refer to CloudBees CD/RO utility and tools.