Skip to main content

ci_cd_integration

Integrating your CI/CD pipeline with nullplatform involves notifying nullplatform about new builds, uploading assets (Docker images, Lambda packages), and updating build status. This guide shows how to use the nullplatform CLI in your CI/CD workflows.

Build lifecycle in CI/CD:

  1. Start a build (np build start)
  2. Build and test your code
  3. Push assets (np asset push)
  4. Update build status to successful or failed (np build update)

Complete GitHub Actions example​

Here's a complete, production-ready example:

name: ci-nullplatform
env:
  NULLPLATFORM_API_KEY: ${{ secrets.NULLPLATFORM_API_KEY }}
on:
  push:
    branches:
      - main
      - master
permissions:
  id-token: write
  contents: read
  packages: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Install nullplatform cli
        run: curl https://cli.nullplatform.com/install.sh | sh
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Start nullplatform CI
        run: np build start
      - name: Build asset
        run: docker build -t main .
      - name: Push asset
        run: np asset push --type docker-image --source main
      - name: End nullplatform CI
        if: ${{ always() }}
        run: np build update --status ${{ contains(fromJSON('["failure", "cancelled"]'), job.status) && 'failed' || 'successful' }}

Key points:

  • NULLPLATFORM_API_KEY is set at workflow level from secrets
  • if: ${{ always() }} ensures build status is updated even on failure
  • Status logic handles both failure and cancellation cases
  • CLI automatically detects application, branch, and commit from GitHub environment

Installing the nullplatform CLI​

First step in any CI/CD pipeline is installing the CLI:

curl https://cli.nullplatform.com/install.sh | sh

This works in GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and any CI environment.

Starting a build​

Notify nullplatform that a build is starting. The CLI automatically detects CI environment variables.

Np Cli:

np build start

The CLI automatically infers:

  • Application ID (from repository URL)
  • Branch name
  • Commit SHA
  • Commit permalink

You can override these if needed:

np build start --application-id <application_id> --branch <branch> --commit-sha <sha>

This creates a build with status "in_progress" visible in the nullplatform UI.

Pushing assets​

After building your code (Docker image, Lambda package), push the asset to nullplatform.

Docker images​

Np Cli:

# Push a Docker image (automatically logs in and pushes)
np asset push --type docker-image --source <image_name>

# Example with a local image
np asset push --type docker-image --source main

# With extra tags
np asset push --type docker-image --source main --extra-tags latest,v1.0.0

The CLI will:

  1. Automatically log into the configured Docker registry
  2. Tag the image appropriately
  3. Push the image to the registry
  4. Register the asset with the build

Lambda packages​

Np Cli:

# Push a Lambda package (zip file)
np asset push --type lambda --source <path_to_zip_file>

# Example
np asset push --type lambda --source dist/function.zip

Bundle assets​

Np Cli:

# Push a bundle asset (URL reference)
np asset push --type bundle --url <asset_url>

Updating build status​

After build completion, update the status to successful or failed:

Np Cli:

# Mark build as successful
np build update --status successful

# Mark build as failed
np build update --status failed

The CLI automatically finds the current build based on CI environment variables.

Always use if: always() in GitHub Actions to ensure status updates even on failure:

- name: End nullplatform CI
  if: ${{ always() }}
  run: np build update --status ${{ contains(fromJSON('["failure", "cancelled"]'), job.status) && 'failed' || 'successful' }}

Working with monorepos​

If you're using a monorepo, specify the application path:

# Start build for specific application in monorepo
np build start --path apps/frontend

# Push asset for specific application
np asset push --type docker-image --source main --path apps/frontend

Authentication​

The CLI uses the NULLPLATFORM_API_KEY environment variable for authentication. Set this in your CI/CD secrets:

GitHub Actions:

  1. Go to repository Settings → Secrets and variables → Actions
  2. Add new repository secret: NULLPLATFORM_API_KEY
  3. Use in workflow: ${{ secrets.NULLPLATFORM_API_KEY }}

GitLab CI:

variables:
  NULLPLATFORM_API_KEY: $CI_NULLPLATFORM_API_KEY

Azure Pipelines:

variables:
  NULLPLATFORM_API_KEY: $(NULLPLATFORM_API_KEY)

API equivalents​

While the CLI is recommended for CI/CD, you can also use the API directly:

Start a build​

Api Call:

Method: POST
Endpoint: /build
Body: '{
  "application_id": <application_id>,
  "branch": "<branch_name>",
  "commit": {
    "id": "<commit_sha>",
    "permalink": "<commit_url>"
  },
  "status": "in_progress"
}'

Push an asset​

Api Call:

Method: POST
Endpoint: /asset
Body: '{
  "build_id": <build_id>,
  "type": "docker-image",
  "name": "main"
}'

Then upload the asset to the provided repository URL.

Update build status​

Api Call:

Method: PATCH
Endpoint: /build/:id
Body: '{
  "status": "successful"
}'

GitLab CI example​

stages:
  - build

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  variables:
    NULLPLATFORM_API_KEY: $CI_NULLPLATFORM_API_KEY
  before_script:
    - curl https://cli.nullplatform.com/install.sh | sh
  script:
    - np build start
    - docker build -t main .
    - np asset push --type docker-image --source main
  after_script:
    - |
      if [ "$CI_JOB_STATUS" == "success" ]; then
        np build update --status successful
      else
        np build update --status failed
      fi

Best practices​

  1. Set API key at workflow/pipeline level - Makes it available to all steps
  2. Always use if: always() - Ensures build status is updated on failure
  3. Install CLI first - Before any other steps
  4. Let CLI auto-detect - Don't manually specify branch/commit unless needed
  5. Handle failures gracefully - Update status to failed, don't skip
  6. Use specific image names - main is a common convention
  7. Add extra tags for versioning - --extra-tags latest,v1.0.0

Continuous deployment​

Once builds are created, you can enable continuous deployment in nullplatform:

  1. Go to application → Scopes
  2. Enable "Continuous Deployment" for a scope
  3. Select the branch to auto-deploy (e.g., main)

Nullplatform will automatically:

  • Create a release from successful builds
  • Deploy to the configured scope
  • Use "all-in" deployment strategy

Important notes​

  • CLI auto-detects CI environment - works with GitHub Actions, GitLab, Azure Pipelines, Jenkins
  • API key must be set as secret - never hardcode in workflow files
  • Builds must be marked successful - only successful builds can be used for releases
  • Assets are pushed to your registries - not proxied through nullplatform
  • Build status affects release creation - failed builds cannot be released
  • Always update status - even on failure, to track build history accurately