Introduction

Both GitHub Actions and CNB support defining automated build, test, publish, and deploy workflows via YAML configuration files. They share some similarities:

• Workflow configuration files are written in YAML and stored in the repository (CNB workflows are called Pipelines)
• Workflows include one or more jobs (CNB jobs correspond to Stages)
• Jobs include one or more steps or individual commands (CNB steps correspond to Jobs, each executing a series of commands or plugins)

This guide will focus on the differences between the two to help you migrate GitHub Actions to CNB.

Workflow Configuration

• GitHub Actions: Each workflow is a separate YAML file stored in the .github/workflows directory
• CNB: All workflow configuration is stored in a file named .cnb.yml in the repository root (you can also import other configuration files using the include keyword)

The following are the main syntax differences between the two:

GitHub Actions Format

name: Node.js CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

CNB Format

.cnb.yml

main:
  push:
    - name: Node.js CI/CD
      stages:
        - name: build
          image: ubuntu:latest
          jobs:
            - name: Run tests
              script: npm test

  pull_request:
    - name: Node.js CI/CD
      stages:
        - name: build
          image: ubuntu:latest
          jobs:
            - name: Run tests
              script: npm test

To reuse the same config across push and pull_request, see Advanced YAML Syntax for anchor syntax.

Build Trigger Rules

GitHub Actions defines trigger rules via the on field. CNB defines them via trigger branches and trigger events. See Build Trigger Rules for details.

GitHub Actions Format

name: Node.js CI/CD

on:
  push:
    branches: [main]

jobs:
  build:
    steps:
      - name: echo
        run: echo "do some job"

CNB Format

.cnb.yml

main:
  push:
    - stages:
        - name: echo
          script: echo "do some job"

Runners

• GitHub Actions: A Runner is a virtual machine that executes jobs (e.g., macOS, Windows, Linux)
• CNB: A Runner is a build node (by default, a node running Docker containers), currently supporting only Linux Docker containers. Enterprise Edition (private deployment) can connect to macOS, Windows, Linux machines. See Build Node for details.

GitHub Actions uses the runs-on field to specify a Runner, while CNB uses the runner field to specify the build node architecture and resource configuration.

GitHub Actions Format

linux_job:
  runs-on: ubuntu-latest
  steps:
    - run: echo "Hello, $USER!"

CNB Format

.cnb.yml

main:
  push:
    - runner:
        tags: cnb:arch:amd64
        cpus: 16
      docker:
        image: ubuntu:latest
      stages:
        - name: echo
          script: echo "Hello, $USER!"

Build Environment

• GitHub Actions: Workflows run in a virtual machine; required software must be pre-installed or manually installed
• CNB: Workflows run in Docker containers; simply specify the image or Dockerfile. See Build Environment for details

GitHub Actions Format

linux_job:
  runs-on: ubuntu-latest
  steps:
    - name: Use Node.js 21
      uses: actions/setup-node@v4
      with:
        node-version: 21
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

CNB Format

.cnb.yml

main:
  push:
    - docker:
        image: node:21
      stages:
        - name: npm ci
          script: npm ci
        - name: build
          script: npm run build --if-present
        - name: npm test
          script: npm test

Repository Code Preparation

• GitHub Actions: Uses actions/checkout to pull repository code
• CNB: Repository code is pulled by default without explicit declaration. See syntax guide-Repository Configuration for details

GitHub Actions Format

linux_job:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: ls -al .

CNB Format

.cnb.yml

main:
  push:
    - stages:
        - name: ls
          script: ls -al .

Conditional Trigger

• GitHub Actions: Uses the if field to set step execution conditions
• CNB: Uses fields like if, ifModify, ifNewBranch to set step execution conditions. See syntax guide-if for details

GitHub Actions Format

jobs:
  deploy_prod:
    if: contains( github.ref, 'master')
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy to production server"

CNB Format

.cnb.yml

$:
  push:
    - if: echo "$CNB_BRANCH" | grep -q 'master'
      stages:
        - name: Deploy to production server
          script: echo "Deploy to production server"

Job Dependencies

• GitHub Actions: Uses the needs field to define dependencies
• CNB: Uses cnb:await and cnb:resolve built-in tasks to define dependencies and pass variables. See await-resolve Built-in Task for details

GitHub Actions Format

jobs:
  build_a:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This job will be run first."

  build_b:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This job will be run first, in parallel with build_a"

  test_ab:
    runs-on: ubuntu-latest
    needs: [build_a, build_b]
    steps:
      - run: echo "This job will run after build_a and build_b have finished"

  deploy_ab:
    runs-on: ubuntu-latest
    needs: [test_ab]
    steps:
      - run: echo "This job will run after test_ab is complete"

CNB Format

Register a key with cnb:resolve when an upstream pipeline finishes, then wait for it with cnb:await by key to express the same dependency as needs. Stages under each pipeline run sequentially by default.

.cnb.yml

main:
  push:
    # The two pipelines run in parallel and each registers a key on completion
    - name: build_a
      stages:
        - name: build_a
          script: echo "This job will be run first."
        - name: resolve
          type: cnb:resolve
          options:
            key: build_a
    - name: build_b
      stages:
        - name: build_b
          script: echo "This job will be run in parallel with build_a"
        - name: resolve
          type: cnb:resolve
          options:
            key: build_b
    # Wait for both build_a and build_b to finish, then run tests
    - name: test_ab
      stages:
        - name: await build_a & build_b
          type: cnb:await
          options:
            key: [build_a, build_b]
        - name: run tests
          script: echo "This job runs after build_a and build_b"
        - name: resolve
          type: cnb:resolve
          options:
            key: test_ab
    # Wait for test_ab to finish, then deploy
    - name: deploy_ab
      stages:
        - name: await test_ab
          type: cnb:await
          options:
            key: test_ab
        - name: deploy
          script: echo "This job runs after test_ab completes"

cnb:await supports an array key: [build_a, build_b] to wait for multiple upstream Pipelines simultaneously, eliminating the need for separate await stages.

Variables and Secrets

• GitHub Actions: Uses env to specify variables and secrets to reference secrets
• CNB: Uses env to specify variables and imports to reference external repository or secret repository files as environment variables. See Reference Variables and Secret Repository for details

GitHub Actions Format

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    env:
      DEPLOYMENT_ENV: production
    steps:
      - run: echo "This job will deploy to the $DEPLOYMENT_ENV server"

CNB Format

env.yml

DEPLOYMENT_ENV: "production"

.cnb.yml

main:
  push:
    - imports:
        - cnb.build/<your-repo-slug>/-/blob/main/xxx/env.yml
      stages:
        - name: Deploy to the $DEPLOYMENT_ENV server
          script: echo "This job will deploy to the $DEPLOYMENT_ENV server"

Matrix Strategy

• GitHub Actions: Supports matrix strategy to automatically create multiple job runs based on variable combinations
• CNB: Does not natively support matrix strategy, but you can simulate it using YAML anchors. See Advanced YAML Syntax for details

GitHub Actions Format

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [15.x, 16.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install node modules
        run: npm install
      - name: Run a one-line script
        run: npm run build
      - name: Run a multi-line script
        run: npm run test

CNB Format

.cnb.yml

main:
  push:
    - docker:
        image: node:14 # Replace with node:16 to switch versions
      stages:
        - name: Install node modules
          script: npm install
        - name: Build
          script: npm run build
        - name: Test
          script: npm run test

CNB does not natively support matrix strategy; add a separate Pipeline for each version. To avoid repetition, see Advanced YAML Syntax for anchors or include.

Cache

• GitHub Actions: Uses caching strategies to temporarily store intermediate build artifacts for subsequent builds
• CNB: Use pipeline.runner.volumes for local node cache, or docker:cache built-in task for remote Docker image cache. See Pipeline Cache for details

GitHub Actions Format

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Cache node modules
        uses: actions/cache@v2
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - name: Build project
        run: npm ci && npm run build

CNB Format

.cnb.yml

main:
  push:
    - docker:
        image: node:14
        volumes:
          - /root/.npm
      stages:
        - name: Build project
          script: npm ci && npm run build

Use docker:cache built-in task to declare remote Docker image cache:

.cnb.yml

main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            by:
              - package.json
              - package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: Build project
          script: npm ci && npm run build

Where cache.dockerfile is a Dockerfile used to build cache images, example:

FROM node:14
WORKDIR /space
COPY . .
RUN npm ci
ENV NODE_PATH=/space/node_modules

Artifacts

• GitHub Actions: Uses actions/upload-artifact to upload artifacts
• CNB: Uses cnbcool/attachments:latest plugin to save artifacts. See Attachment Plugin for details.

GitHub Actions Format

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Upload a Build Artifact
        uses: actions/upload-artifact@v2
        with:
          name: my-artifact
          path: /path/to/artifact

CNB Format

.cnb.yml

main:
  push:
    - docker:
        image: ubuntu:latest
      stages:
        - name: Upload a Build Artifact
          image: cnbcool/attachments:latest
          settings:
            attachments:
              - /path/to/artifact

Database and Service Containers

• GitHub Actions: Uses the services field to orchestrate database and service containers
• CNB: Declare a docker service and execute docker or docker compose commands directly. See Docker service for details

GitHub Actions Format

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:20-bookworm-slim

    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres

    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      # Performs a clean installation of all dependencies
      # in the `package.json` file
      - name: Install dependencies
        run: npm ci

      - name: Connect to PostgreSQL
        # Runs a script that creates a PostgreSQL client,
        # populates the client with data, and retrieves data
        run: node client.js
        env:
          # The hostname used to communicate with the
          # PostgreSQL service container
          POSTGRES_HOST: postgres
          # The default PostgreSQL port
          POSTGRES_PORT: 5432

CNB Format

.cnb.yml

main:
  push:
    - docker:
        image: ubuntu:latest
      services:
        - docker
      stages:
        - name: Start database and service
          script: docker-compose up -d
        - name: Connect to PostgreSQL
          script: node client.js
          env:
            POSTGRES_HOST: 127.0.0.1
            POSTGRES_PORT: 5432

Previous pageNPC Events

Next pageOn-Demand Build for Monorepo