Skip to main content

build_and_release

In nullplatform, builds and releases are distinct but connected concepts. Understanding the difference is essential for the deployment workflow.

Build: Created during CI/CD, contains compiled code, assets (Docker images, Lambda packages), and references to the source code commit.

Release: A deployable package that references a specific build and uses semantic versioning (semver). You deploy releases, not builds.

Workflow: Code → Build (CI/CD) → Release → Deployment

Listing builds for an application​

To see all available builds for an application:

Api Call:

Method: GET
Endpoint: /build?application_id=<application_id>

Np Cli:

np build list --application_id <application_id>

You can filter builds by branch or commit:

# Filter by branch
np build list --application_id <application_id> --branch main

# Filter by commit ID
np build list --application_id <application_id> --commit.id <commit_sha>

Reading a specific build​

To get details about a specific build (including assets):

Api Call:

Method: GET
Endpoint: /build/:id

Np Cli:

np build read --id <build_id>

This shows:

  • Build status (successful, failed, creating)
  • Associated commit information
  • Available assets (Docker images, Lambda packages)
  • Build metadata

Listing releases for an application​

To see all releases for an application:

Api Call:

Method: GET
Endpoint: /release?application_id=<application_id>

Np Cli:

np release list --application_id <application_id>

Reading a specific release​

To get details about a specific release:

Api Call:

Method: GET
Endpoint: /release/:id

Np Cli:

np release read --id <release_id>

This shows:

  • Semver version
  • Associated build ID
  • Release status
  • Application ID

Creating a release​

To create a release from a build, you need the build ID and application ID. You should also specify a semantic version (semver).

Api Call:

Method: POST
Endpoint: /release
Body: '{
  "status": "active",
  "build_id": <build_id>,
  "application_id": <application_id>,
  "semver": "<version>" // e.g., "1.2.3", check the last release to increment properly
}'

Np Cli:

np release create --body '{
  "status": "active",
  "build_id": <build_id>,
  "application_id": <application_id>,
  "semver": "<version>"
}'

Semver best practices:

  • Check the latest release first to determine the next version
  • Use semantic versioning format: MAJOR.MINOR.PATCH (e.g., 1.2.3)
  • Increment PATCH for bug fixes, MINOR for features, MAJOR for breaking changes

Common workflow: From build to deployment​

Here's the typical workflow to deploy code:

  1. Find the latest successful build:
np build list --application_id <application_id> --limit 10
  1. Check the latest release to determine next version:
np release list --application_id <application_id> --limit 1
  1. Create a new release from the build:
np release create --body '{
  "status": "active",
  "build_id": <build_id>,
  "application_id": <application_id>,
  "semver": "1.2.4"
}'
  1. Deploy the release to a scope:
np deployment create --body '{
  "scope_id": <scope_id>,
  "release_id": <release_id>
}'

Finding builds by commit​

If you know the commit SHA and want to find the corresponding build:

Api Call:

Method: GET
Endpoint: /build?application_id=<application_id>&commit.id=<commit_sha>

Np Cli:

np build list --application_id <application_id> --commit.id <commit_sha>

Important notes​

  • Builds are created by CI/CD pipelines using np build start and np build update
  • Releases must reference successful builds - you cannot create a release from a failed build
  • One build can have multiple releases - useful for deploying the same code with different versions
  • Semantic versioning is required - helps track what changes are in each release
  • Assets are tied to builds - when you create a release, it inherits the build's assets