Customize Environment Creation Pipeline

About 514 wordsAbout 2 min

If you want to use a custom pipeline configuration when clicking the Workspaces button on the branch page, you can add a .cnb.yml file in the repository root directory with the following configuration:

.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 x 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 when to automatically create a development environment based on specific trigger events. 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, Workspaces becomes available after the pipeline preparation (prepare) phase completes (when the code-server service starts) and before the stages tasks execute.

If you want to enter the development environment after executing certain tasks, i.e., delay the timing of entering the development environment, you can use the built-in vscode:go task. When using this task, after starting Workspaces, the loading page will delay entering the Workspaces entry selection page until the vscode:go task executes.

Note that using the vscode:go task will increase waiting time. Tasks that must be executed before entering the development environment should be placed before vscode:go, while tasks that can be executed after entering the development environment should be placed after vscode:go. If there are no tasks that must be executed before entering the development environment, there's no need to use vscode:go.

When stages tasks fail, whether Workspaces ends depends on:

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: If stages tasks fail, the development environment will not be destroyed

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 to execute after development environment starts
      stages:
        - name: ls
          script: ls -al
      # Tasks to execute before development environment is destroyed
      endStages:
        - name: end stage 1
          script: echo "end stage 1"
        - name: end stage 2
          script: echo "end stage 2"