Workspace Expressions

Harness workspace expressions empower you to dynamically reference workspace-level parameters within your pipelines, enhancing flexibility and customization. By leveraging JEXL (Java Expression Language), you can seamlessly access key workspace attributes.

Key Benefits

• Dynamic Retrieval: Access workspace-specific identifiers and paths effortlessly.
• Environment Integration: Utilize environment and secret variables within the workspace context.
• Versioning and Provisioning: Integrate versioning and provisioner details directly into your pipeline logic.
• Cost Management: Extract outputs and control cost estimation features.
• Git Management: Seamlessly manage Git-related parameters like repository name, branch, commit SHA, and tags.

These expressions are invaluable when adapting pipelines to different environments or configurations.

migrate expressions

Go to the Migrate Expressions tab in the How to Use Workspace Expressions section to update old expressions to the latest format.

Available Workspace Expressions

Supported workspace expressions are written in the syntax <+workspace.ATTRIBUTE>, where ATTRIBUTE can be a single or multi-level identifier, such as:

• <+workspace.identifier>
• <+workspace.type> (e.g., opentofu)
• <+workspace.envVars.SOME_ENV_VAR>

See full list of supported workspace expressions

Parameter	Expression	Description
Workspace ID	<+workspace.identifier>	Retrieves the unique identifier for the workspace.
Folder Path	<+workspace.folderPath>	Returns the root directory path associated with the workspace.
Provisioner Type	<+workspace.type>	Provides the type of provisioner being used, such as opentofu or terraform.
Provisioner Version	<+workspace.provisionerVersion>	Fetches the version of the provisioner used in the workspace.
Connector Reference	<+workspace.connectorRef>	Retrieves the connector reference associated with the workspace.
Environment Variable	<+workspace.envVars.SOME_ENV_VAR>	Accesses a specific environment variable within the workspace.
Terraform/Opentofu Variable	<+workspace.variables.OPEN_TOFU_VAR>	Retrieves a variable specific to Terraform or OpenTofu within the workspace.
Secret Variable	<+workspace.envVars.SECRET_ENV_VAR>	Accesses a secret variable defined in the workspace.
Output	<+workspace.outputs.OUTPUT_ID>	Retrieves a specific output from the workspace.
Workspace Name	<+workspace.name>	Returns the name of the workspace.
Cost Estimation Enabled	<+workspace.enableCostEstimation>	Indicates whether cost estimation is enabled for the workspace.
Git Connector Reference	<+workspace.gitConnectorRef>	Retrieves the Git connector reference for the workspace.
Git Repository Name	<+workspace.gitRepoName>	Provides the name of the Git repository associated with the workspace.
Git Branch	<+workspace.gitBranch>	Returns the name of the Git branch currently in use.
Git SHA	<+workspace.gitSha>	Retrieves the commit SHA from the Git repository.
Git Tag	<+workspace.gitTag>	Returns the Git tag associated with the current commit.

How to Use Workspace Expressions

Here's an example of applying workspace expressions in your pipelines to output the workspace identifier and secret variable value.

reserved keyword

Avoid naming your run step workspace as it is a reserved keyword.

Interactive Guide

Migrate Expressions

If you're using an older expression format, update it to the new format as follows:

For example, update secret variables from:

// OLD
<+pipeline.stages.stage_name.spec.execution.steps.step_name.spec.secretVariables.secret_variable_name>

// NEW
<+workspace.envVars.SECRET_ENV_VAR>

The following guide demonstrates updating your workspace's secret environment variable reference:

See the reference of old and new expression formats:

See old and new expressions

Value	Expressions
Workspace ID	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.workspace>
	After: <+workspace.identifier>
Folder Path	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.PLUGIN_ROOT_DIR>
	After: <+workspace.folderPath>
Provisioner Type	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.PLUGIN_PROVISIONER>
	After: <+workspace.type>
Provisioner Version	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.PLUGIN_TF_VERSION>
	After: <+workspace.provisionerVersion>
Connector Ref	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.PLUGIN_CONNECTOR_REF>
	After: <+workspace.connectorRef>
Env Variable	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.SOME_ENV_VAR>
	After: <+workspace.envVars.SOME_ENV_VAR>
Terraform/Opentofu var	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariables.PLUGIN_WS_TF_VAR_OPEN_TOFU_VAR>
	After: <+workspace.variables.OPEN_TOFU_VAR>
Secret Variable	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.secretVariables.SECRET_ENV_VAR>
	After: <+workspace.envVars.SECRET_ENV_VAR>
Output	Before: <+workspace.<+pipeline.stages.s1.spec.execution.steps.init.spec.workspace>.OUTPUT_ID>
	After: <+workspace.outputs.OUTPUT_ID>
Env Var from Connector	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.envVariablesFromConnector.PLUGIN_ACCESS_KEY>
	After: <+workspce.envVariablesFromConnector.PLUGIN_ACCESS_KEY>
Secret from Connector	Before: <+pipeline.stages.s1.spec.execution.steps.init.spec.secretVariablesFromConnector.PLUGIN_SECRET_KEY>
	After: <+workspace.secretVariablesFromConnector.PLUGIN_SECRET_KEY>

By understanding and utilizing workspace expressions in Harness IaCM, you can significantly enhance the efficiency and adaptability of your infrastructure management processes.