Creating Your First Release

This tutorial walks you through creating and publishing your first release in Big Picture. A release represents a version of your software that clients can query and potentially install.

Prerequisites

• Big Picture instance configured and accessible
• API credentials with release creation permissions
• A product created in your catalog
• A software artifact (installer) ready to publish

Understanding Releases

A release in Big Picture consists of:

• Product — The software being released
• Version — Semantic version (e.g., 1.0.0)
• Channel — Release channel (stable, beta, internal)
• Artifacts — Platform-specific installers or packages
• Metadata — Version info, release notes, compatibility flags

Releases are immutable — once published, they cannot be modified, only revoked.

Step 1: Prepare Your Artifact

Before creating a release, ensure your artifact is ready:

Requirements:

• Artifact is signed (if required by your platform)
• SHA-256 hash is computed
• Size is known
• Platform and architecture are identified

Compute hash:

# Linux/macOS
sha256sum installer.msi

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

Save the hash — you’ll need it when registering the artifact.

Step 2: Register the Artifact

Register your artifact with Big Picture. You can use external references or managed storage.

Option A: External Artifact Reference

If your artifact is hosted externally (JFrog, S3, GCS, etc.):

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

If using Big Picture’s managed storage:

Initiate upload:

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..."
  }'

The response includes an upload_id and upload_url.

Upload artifact:

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

Complete upload:

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 the Release

Create a release referencing your artifact:

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

Response:

{
  "release_id": "rel_abc123",
  "product_id": "prod_xyz789",
  "version": "1.0.0",
  "channel": "stable",
  "published_at": "2024-01-15T10:30:00Z",
  "artifacts": [...]
}

The release is now published and available to clients.

Step 4: Add Multiple Artifacts (Optional)

If you support multiple platforms, add artifacts for each:

# Register macOS artifact
curl -X POST "${BP_BASE_URL}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "macos-artifact-hash",
    "size_bytes": 20480000,
    "external_url": "https://artifacts.example.com/releases/v1.0.0/installer.pkg"
  }'

# Create release with multiple artifacts (all artifacts must be included in single request)
curl -X POST "${BP_BASE_URL}/v1/releases" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "your-product-id",
    "version": "1.0.0",
    "channel": "stable",
    "artifacts": [
      {
        "artifact_id": "windows-artifact-id",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      },
      {
        "artifact_id": "macos-artifact-id",
        "platform": "macos",
        "arch": "x86_64",
        "installer_type": "pkg",
        "requires_admin": true
      }
    ],
    "metadata": {
      "release_notes": "Initial release with core features"
    }
  }'

Note: Releases are immutable. To add artifacts to an existing version, you must create a new release with the same version and include all artifacts (both existing and new) in a single request. Alternatively, publish a new version.

Step 5: Verify Release

Query the release to verify it’s accessible:

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

Test the update decision API:

curl -X POST "${BP_BASE_URL}/v1/decision" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "product_id": "your-product-id",
        "current_version": "0.9.0",
        "channel": "stable",
        "tenant_id": "your-tenant-id"
      }
    ]
  }'

The response should include your release with a signed decision.

Release Channels

Big Picture supports multiple customizable channels for staged rollouts. New tenants are created with default channels (stable, beta, internal), but all channels are fully customizable and can be modified or deleted.

Default Channels:

• stable — Production releases for general availability
• beta — Pre-release testing
• internal — Internal testing and development

You can create custom channels (e.g., canary, staging, qa) to match your deployment workflow. Clients query a specific channel. You can publish the same version to multiple channels if needed.

Revoking a Release

If you need to prevent a release from being served (e.g., security issue):

curl -X POST "${BP_BASE_URL}/v1/releases/rel_abc123/revoke" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Revoked releases remain in the catalog for audit purposes but are not returned to clients. You cannot un-revoke a release — create a new release instead.

CI/CD Integration

Integrate release creation into your CI/CD pipeline:

# Example GitHub Actions workflow
- name: Publish Release
  run: |
    ARTIFACT_ID=$(curl -X POST "${{ secrets.BP_BASE_URL }}/v1/artifacts" \
      -H "Authorization: Bearer ${{ secrets.BP_API_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{\"source_type\":\"EXTERNAL\",\"sha256\":\"$SHA256\",\"size_bytes\":$SIZE,\"external_url\":\"$ARTIFACT_URL\"}" \
      | jq -r '.artifact_id')

    curl -X POST "${{ secrets.BP_BASE_URL }}/v1/releases" \
      -H "Authorization: Bearer ${{ secrets.BP_API_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{\"product_id\":\"$PRODUCT_ID\",\"version\":\"$VERSION\",\"channel\":\"stable\",\"artifacts\":[{\"artifact_id\":\"$ARTIFACT_ID\",\"platform\":\"windows\",\"arch\":\"x86_64\",\"installer_type\":\"msi\",\"requires_admin\":true}],\"metadata\":{\"release_notes\":\"Automated release from CI/CD\"}}"

What’s Next?

Now that you’ve created a release:

• Configure tenant policies to control update behavior
• Set up staged rollouts for gradual deployment
• Learn about distributing artifacts to clients
• Explore release workflows for operational procedures
• See the API Reference for complete endpoint documentation