---
url: /en/workspaces/custom-dev-pipeline.md
description: >
  Explains how to write a custom `.cnb.yml` pipeline for Workspaces environment
  creation, including custom Docker images, resource specs (CPU/memory), and
  other pipeline options.
---
If you want to use a custom pipeline when clicking the `Workspace` button on the branch page,
create a `.cnb.yml` in the repository root:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: node:20
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al
```

## Custom Resource Specifications

You can declare the required number of CPU cores through `runner.cpus`,
supporting up to `64 cores`, with memory being cpus × 2 (GB). Add the `runner` declaration to the base configuration:

```yaml{4} title=".cnb.yml"
$:
  vscode:
    - runner:
        cpus: 64
      docker:
        image: node:20
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al
```

## Custom Trigger Events

Through `.cnb.yml`, you can declare specific trigger events to automatically create development environments.
Recommended trigger events include:

* [`vscode`](../build/grammar.md#workspaces-events):
  Create development environment when clicking the `Launch Workspaces` button on repository page
* [`branch.create`](../build/grammar.md#branch-create): Create development environment when creating a branch
* [`api_trigger`](../build/grammar.md#api_trigger): Create development environment through custom API trigger
* [`web_trigger`](../build/trigger-rule.md#web_trigger): Create development environment through custom web page trigger

```yaml{5} title=".cnb.yml"
# Match all branches
(**):
  branch.create:
    - name: vscode
      services:
        - vscode
      docker:
        build: .ide/Dockerfile
      stages:
        - name: Execute custom scripts
          script:
            - npm install
            - npm run start
```

## Custom Availability Timing

By default, Workspace becomes available after the `prepare` phase completes
and before `stages` tasks execute (`code-server` starts during the prepare phase).

If you need to execute certain tasks before entering the development environment (delayed entry),
you can use the built-in task [vscode:go](../build/internal-steps/vscode/go.md).
Once enabled, the `loading` page will stay on the entry selection page until `vscode:go` completes.

Note: Using `vscode:go` increases wait time.
Place pre-entry tasks before `vscode:go`, and post-entry tasks after it.
If delayed entry is not needed, do not use this task.

When `stages` tasks fail, the behavior depends on the configuration:

* Using `vscode:go`: If tasks before `vscode:go` fail, the development environment will be destroyed
* Using `vscode:go`: If tasks after `vscode:go` fail, the development environment will not be destroyed
* Not using `vscode:go`: `stages` task failure will not destroy the environment

## Custom Pre-destruction Tasks

You can use [`endStages`](../build/grammar.md#endstages)
to define tasks that need to be executed before the development environment is
destroyed. Add `endStages` to the base configuration:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: node:20
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al
      endStages:
        - name: end stage 1
          script: echo "end stage 1"
        - name: end stage 2
          script: echo "end stage 2"
```