Creating Multi-Platform Releases

This workflow covers creating releases that support multiple platforms and architectures. Releases are immutable—all artifacts must be included when creating the release.

Prerequisites

• API credentials with release creation permissions
• A product created in your catalog
• Artifacts built for each target platform
• SHA-256 hashes computed for all artifacts
• Consistent version number across all platforms

Understanding Release Immutability

Releases cannot be modified after creation. To add artifacts to an existing release:

1. Revoke the existing release (if needed)
2. Create a new release with all artifacts included

You cannot add artifacts to an existing release.

Step 1: Register All Artifacts

Register artifacts for each platform before creating the release:

# Register Windows artifact
ARTIFACT_WIN=$(curl -X POST "${BP_BASE_URL}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "windows-hash-here",
    "size_bytes": 15728640,
    "external_url": "https://artifacts.example.com/v1.0.0/windows.msi"
  }' | jq -r '.artifact_id')

# Register macOS artifact
ARTIFACT_MAC=$(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-hash-here",
    "size_bytes": 20971520,
    "external_url": "https://artifacts.example.com/v1.0.0/macos.dmg"
  }' | jq -r '.artifact_id')

# Register Linux artifact
ARTIFACT_LINUX=$(curl -X POST "${BP_BASE_URL}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "linux-hash-here",
    "size_bytes": 18874368,
    "external_url": "https://artifacts.example.com/v1.0.0/linux.deb"
  }' | jq -r '.artifact_id')

Step 2: Create Release with All Artifacts

Create a single release including all platform artifacts:

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\": \"$ARTIFACT_WIN\",
        \"platform\": \"windows\",
        \"arch\": \"x86_64\",
        \"installer_type\": \"msi\",
        \"requires_admin\": true
      },
      {
        \"artifact_id\": \"$ARTIFACT_MAC\",
        \"platform\": \"macos\",
        \"arch\": \"x86_64\",
        \"installer_type\": \"dmg\",
        \"requires_admin\": false
      },
      {
        \"artifact_id\": \"$ARTIFACT_LINUX\",
        \"platform\": \"linux\",
        \"arch\": \"x86_64\",
        \"installer_type\": \"deb\",
        \"requires_admin\": true
      }
    ],
    \"metadata\": {
      \"release_notes\": \"Initial release with multi-platform support\"
    }
  }"

Step 3: Handle Staged Artifact Availability

If artifacts are built at different times:

Option 1: Wait for all artifacts

Delay release creation until all artifacts are ready. This ensures a complete release.

Option 2: Create and revoke

Create a release with available artifacts, then revoke and recreate when all are ready:

# Create initial release with Windows only
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": "beta",
    "artifacts": [
      {
        "artifact_id": "art_win64",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      }
    ]
  }'

# When macOS is ready, revoke and recreate
curl -X POST "${BP_BASE_URL}/v1/releases/rel_abc123/revoke" \
  -H "Authorization: Bearer $BP_API_TOKEN"

# Create new release with all artifacts
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_win64",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      },
      {
        "artifact_id": "art_macos",
        "platform": "macos",
        "arch": "x86_64",
        "installer_type": "dmg",
        "requires_admin": false
      }
    ]
  }'

Note: This creates two release records (one revoked, one active) for audit purposes.

Platform and Architecture Support

Supported platforms:

• windows — Windows installers (MSI, EXE)
• macos — macOS installers (DMG, PKG)
• linux — Linux packages (DEB, RPM)

Supported architectures:

• x86_64 — 64-bit x86
• x86 — 32-bit x86
• arm64 — ARM 64-bit

Installer types:

• Windows: msi, exe
• macOS: dmg, pkg
• Linux: deb, rpm

CI/CD Integration

Automate multi-platform release creation in your CI/CD pipeline:

# Example GitHub Actions workflow
jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - name: Build Windows Artifact
        run: |
          # Build MSI
          ARTIFACT_WIN=$(register_artifact windows x86_64 msi)
          echo "ARTIFACT_WIN=$ARTIFACT_WIN" >> $GITHUB_ENV

  build-macos:
    runs-on: macos-latest
    steps:
      - name: Build macOS Artifact
        run: |
          # Build DMG
          ARTIFACT_MAC=$(register_artifact macos x86_64 dmg)
          echo "ARTIFACT_MAC=$ARTIFACT_MAC" >> $GITHUB_ENV

  build-linux:
    runs-on: ubuntu-latest
    steps:
      - name: Build Linux Artifact
        run: |
          # Build DEB
          ARTIFACT_LINUX=$(register_artifact linux x86_64 deb)
          echo "ARTIFACT_LINUX=$ARTIFACT_LINUX" >> $GITHUB_ENV

  create-release:
    needs: [build-windows, build-macos, build-linux]
    runs-on: ubuntu-latest
    steps:
      - name: Create Release
        run: |
          curl -X POST "${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\": \"${{ env.ARTIFACT_WIN }}\",
                  \"platform\": \"windows\",
                  \"arch\": \"x86_64\",
                  \"installer_type\": \"msi\",
                  \"requires_admin\": true
                },
                {
                  \"artifact_id\": \"${{ env.ARTIFACT_MAC }}\",
                  \"platform\": \"macos\",
                  \"arch\": \"x86_64\",
                  \"installer_type\": \"dmg\",
                  \"requires_admin\": false
                },
                {
                  \"artifact_id\": \"${{ env.ARTIFACT_LINUX }}\",
                  \"platform\": \"linux\",
                  \"arch\": \"x86_64\",
                  \"installer_type\": \"deb\",
                  \"requires_admin\": true
                }
              ]
            }"

Best Practices

Version consistency: Ensure all artifacts use the same version number and metadata.

Complete releases: Include all target platforms in a single release when possible.

Platform coverage: Support the platforms your customers use. At minimum, provide x86_64 artifacts for Windows, macOS, and Linux.

Artifact verification: Verify all artifacts before creating the release—see Verifying Artifacts.

Next Steps

• Verify artifact integrity — see Verifying Artifacts
• Configure version pinning — see Managing Release Versions
• Set up approval workflows — see Approving a Release