Skip to content
Big Picture

Creating a Release

This workflow covers creating a release in Big Picture. A release represents a version of your software that clients can query and install.

Prerequisites

Section titled “Prerequisites”
  • API credentials with release creation permissions
  • A product created in your catalog
  • At least one artifact registered or ready to upload
  • SHA-256 hash computed for each artifact
  • Version number following semantic versioning

Step 1: Prepare Artifacts

Section titled “Step 1: Prepare Artifacts”

Before creating a release, ensure your artifacts are ready:

Compute SHA-256 hash:

Terminal window
# Linux
sha256sum installer.deb


# macOS
shasum -a 256 installer.dmg


# Windows (PowerShell)
Get-FileHash installer.msi -Algorithm SHA256

Record artifact details:

  • SHA-256 hash
  • Size in bytes
  • Platform (windows, macos, linux)
  • Architecture (x86_64, x86, arm64)
  • Installer type (msi, exe, dmg, pkg, deb, rpm)

Step 2: Register Artifacts

Section titled “Step 2: Register Artifacts”

Register each artifact with Big Picture. Choose external reference or managed upload.

Option A: External Artifact Reference

Section titled “Option A: External Artifact Reference”

If your artifact is hosted externally:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "a1b2c3d4e5f6...",
    "size_bytes": 15728640,
    "external_url": "https://artifacts.example.com/releases/v1.0.0/installer.msi"
  }'

Save the artifact_id from the response.

Option B: Managed Artifact Upload

Section titled “Option B: Managed Artifact Upload”

If using Big Picture managed storage:

Initiate upload:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/artifacts/uploads" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 15728640,
    "sha256": "a1b2c3d4e5f6..."
  }'

Upload artifact:

Terminal window
curl -X PUT "$UPLOAD_URL" \
  --data-binary @installer.msi \
  -H "Content-Type: application/octet-stream"

Complete upload:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/artifacts/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Save the artifact_id from the completion response.

Step 3: Create Release

Section titled “Step 3: Create Release”

Create a release referencing your artifact:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/releases" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "version": "1.0.0",
    "channel": "stable",
    "artifacts": [
      {
        "artifact_id": "art_abc123",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      }
    ],
    "metadata": {
      "release_notes": "Initial release with core features",
      "min_os_version": "Windows 10"
    }
  }'

Required fields:

  • product_id — Product identifier
  • version — Semantic version (e.g., 1.0.0)
  • channel — Release channel (stable, beta, internal, or custom)
  • artifacts — Array of artifact references

Optional fields:

  • metadata — Release notes, compatibility info, etc.

Step 4: Verify Release

Section titled “Step 4: Verify Release”

Query the release to confirm it’s accessible:

Terminal window
curl "${BP_BASE_URL}/v1/products/prod_xyz789/releases?channel=stable&version=1.0.0" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Test the update decision API:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/decision" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "product_id": "prod_xyz789",
        "current_version": "0.9.0",
        "channel": "stable",
        "tenant_id": "tenant_abc123"
      }
    ]
  }'

The response should include your release with a signed decision.

Common Issues

Section titled “Common Issues”

Duplicate version: Each version can only exist once per channel. Use a different version or channel.

Invalid artifact: Ensure artifact is registered and artifact_id is correct.

Missing metadata: Metadata is optional but recommended for release notes and compatibility information.

Next Steps

Section titled “Next Steps”