Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tektoncd/pipeline/llms.txt

Use this file to discover all available pages before exploring further.

Workspaces allow Tasks to share data with each other and declare the volumes they need at runtime.

​
WorkspaceDeclaration

Declares a workspace required by a Task.
​
name
string
required
Name of the workspace.Used to reference the workspace in steps and bind it at runtime.
​
description
string
Human-readable description of how the workspace is used.
​
mountPath
string
Path where the workspace will be mounted.Defaults to /workspace/<name> if not specified.
​
readOnly
boolean
default:false
Whether the workspace is read-only.If true, the volume is mounted read-only.
​
optional
boolean
default:false
Whether the workspace is optional.If true, the Task can run without this workspace being provided.

​
WorkspaceBinding

Binds a declared workspace to an actual volume at runtime (in TaskRuns/PipelineRuns).
​
name
string
required
Name of the workspace being bound.Must match a workspace declared in the Task or Pipeline.
​
subPath
string
Subdirectory on the volume to use for this binding.Useful when multiple workspaces share the same volume.

​
Volume Sources

One of the following volume sources must be specified:
​
emptyDir
EmptyDirVolumeSource
Temporary directory that shares the Task’s lifetime.Data is lost when the Task completes.
workspaces:
  - name: scratch
    emptyDir: {}
​
persistentVolumeClaim
PersistentVolumeClaimVolumeSource
Reference to an existing PersistentVolumeClaim.
workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: my-pvc
​
volumeClaimTemplate
PersistentVolumeClaim
Template for creating a PVC for each run.The PVC is automatically created and deleted.
workspaces:
  - name: source
    volumeClaimTemplate:
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 1Gi
​
configMap
ConfigMapVolumeSource
Populate workspace from a ConfigMap.
workspaces:
  - name: config
    configMap:
      name: my-config
​
secret
SecretVolumeSource
Populate workspace from a Secret.
workspaces:
  - name: credentials
    secret:
      secretName: my-secret
​
projected
ProjectedVolumeSource
Combine multiple volume sources into one.
workspaces:
  - name: combined
    projected:
      sources:
        - secret:
            name: secret1
        - configMap:
            name: config1
​
csi
CSIVolumeSource
Use a CSI (Container Storage Interface) driver.
workspaces:
  - name: csi-volume
    csi:
      driver: secrets-store.csi.k8s.io
      readOnly: true

​
PipelineWorkspaceDeclaration

Declares a workspace required by a Pipeline.
​
name
string
required
Name of the workspace.
​
description
string
Description of how the workspace is used in the Pipeline.
​
optional
boolean
default:false
Whether the workspace is optional.

​
WorkspacePipelineTaskBinding

Maps a Pipeline workspace to a Task workspace.
​
name
string
required
Name of the workspace as declared by the Task.
​
workspace
string
Name of the workspace declared by the Pipeline.If omitted, assumes the names match.
​
subPath
string
Subdirectory within the Pipeline workspace.

​
Using Workspaces in Steps

Access workspace paths in steps: 
steps:
  - name: write-file
    image: bash
    script: |
      echo "Hello" > $(workspaces.source.path)/file.txt
  - name: read-file
    image: bash
    script: |
      cat $(workspaces.source.path)/file.txt

​
Workspace Isolation

Steps can request exclusive access to workspaces: 
steps:
  - name: exclusive-step
    image: bash
    workspaces:
      - name: source
    script: |
      # This step has exclusive access to 'source'
      # Other steps cannot access it simultaneously

​
Examples

​
Task with Workspace

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: task-with-workspace
spec:
  workspaces:
    - name: source
      description: The source code to build
      mountPath: /workspace/source
    - name: cache
      description: Build cache
      optional: true
  steps:
    - name: build
      image: golang
      workingDir: $(workspaces.source.path)
      script: |
        go build ./...

​
TaskRun with emptyDir

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: taskrun-emptydir
spec:
  taskRef:
    name: task-with-workspace
  workspaces:
    - name: source
      emptyDir: {}

​
TaskRun with PVC

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: taskrun-pvc
spec:
  taskRef:
    name: task-with-workspace
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: source-pvc

​
Pipeline Sharing Workspace

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: build-and-test
spec:
  workspaces:
    - name: shared-data
      description: Workspace shared between tasks
  tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
      workspaces:
        - name: output
          workspace: shared-data
    - name: build
      taskRef:
        name: build-task
      workspaces:
        - name: source
          workspace: shared-data
      runAfter:
        - fetch-source
    - name: test
      taskRef:
        name: test-task
      workspaces:
        - name: source
          workspace: shared-data
      runAfter:
        - build

​
PipelineRun with VolumeClaimTemplate

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipelinerun-with-pvc
spec:
  pipelineRef:
    name: build-and-test
  workspaces:
    - name: shared-data
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 5Gi
          storageClassName: fast-ssd

​
Using SubPath

workspaces:
  - name: cache
    persistentVolumeClaim:
      claimName: shared-cache
    subPath: project-a/build-cache

​
ConfigMap Workspace

workspaces:
  - name: config
    configMap:
      name: app-config
      items:
        - key: config.yaml
          path: config.yaml

​
Secret Workspace

workspaces:
  - name: ssh-creds
    secret:
      secretName: git-ssh-key
      items:
        - key: ssh-privatekey
          path: id_rsa
          mode: 0600

​
Best Practices

  1. Use descriptive names - Clearly indicate workspace purpose
  2. Document workspace usage - Explain what data the workspace contains
  3. Use volumeClaimTemplate for pipelines - Automatically provision storage
  4. Mark optional workspaces - Allow tasks to run without optional data
  5. Use subPath for organization - Share volumes across workspaces
  6. Choose appropriate volume types - Match volume type to data persistence needs
  7. Set readOnly when appropriate - Prevent accidental modifications
  8. Clean up PVCs - Remove volumeClaimTemplate PVCs after use

Build docs developers (and LLMs) love

Get started for freeTalk to us