Customize Environment Creation Pipeline

About 476 wordsAbout 2 min

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:

.cnb.yml
$:
  # vscode event: specifically for launching Workspaces from the page
  vscode:
    - docker:
        # Custom image as development environment
        image: node:20
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al

Custom Resource Specifications

You can declare the required development resources through runner.cpus, supporting up to 64 cores, with memory being cpus × 2 (GB).

.cnb.yml
$:
  vscode:
    - runner:
        cpus: 64
      docker:
        build: .ide/Dockerfile
      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: Create development environment when clicking the Launch Workspaces button on repository page
branch.create: Create development environment when creating a branch
api_trigger: Create development environment through custom API trigger
web_trigger: Create development environment through custom web page trigger

.cnb.yml
# Match all branches
(**):
  # Create development environment when creating branch
  branch.create:
    - name: vscode
      services:
        # Declare using vscode service
        - vscode
      docker:
        # Custom development environment
        build: .ide/Dockerfile
      stages:
        - name: Execute custom scripts
          script:
            - npm install
            - npm run start

Custom Availability Timing

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

If you need to execute certain tasks before entering the development environment (delayed entry), you can use the built-in task vscode:go. Once enabled, the loading page will stay on the entry selection page after Workspace starts, and will only proceed once 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, vscode:go is unnecessary.

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 to define tasks that need to be executed before the development environment is destroyed.

.cnb.yml
$:
  vscode:
    - docker:
        image: node:20
      services:
        - vscode
        - docker
      # Tasks executed after development environment starts
      stages:
        - name: ls
          script: ls -al
      # Tasks executed before development environment is destroyed
      endStages:
        - name: end stage 1
          script: echo "end stage 1"
        - name: end stage 2
          script: echo "end stage 2"