CI/CD Integration

CI/CD integration enables pipelines to publish releases into Big Picture automatically. This integration supports artifact registration, release creation, and multi-platform builds across common CI/CD platforms.

---

How CI/CD Integration Works

CI/CD pipelines integrate with Big Picture through the REST API:

1. Build artifacts — Pipeline builds installers or packages for target platforms
2. Register artifacts — Pipeline registers artifacts with Big Picture (external URLs or managed storage)
3. Create releases — Pipeline creates releases that reference registered artifacts
4. Publish releases — Releases become available to clients through update decisions

Big Picture does not replace CI/CD systems. Instead, it receives release metadata and artifact references from pipelines, enabling release governance and update decisions.

---

Supported Platforms

Big Picture provides integration examples and guides for:

• GitHub Actions — Workflow examples for single and multi-platform releases
• GitLab CI — Pipeline examples with artifact handling
• Jenkins — Declarative and scripted pipeline examples

Other CI/CD platforms can integrate using the same REST API patterns.

---

Prerequisites

Before integrating CI/CD pipelines:

1. Service account — Create a service account with ci:write and artifacts:write scopes
2. API credentials — Store API token as CI/CD secret or environment variable
3. Product configuration — Identify product ID and channel names
4. Artifact storage — Decide between external URLs or managed storage

---

Integration Patterns

External Artifact References

Pipelines register artifacts stored externally (S3, GCS, JFrog, GitHub Releases):

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

Managed Artifact Storage

Pipelines upload artifacts to Big Picture 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": 12345678,
    "sha256": "..."
  }'

# Upload artifact content
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" \
  -H "Content-Type: application/json" \
  -d '{
    "checksum": "..."
  }'

Release Creation

After registering artifacts, pipelines create releases:

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
      }
    ],
    "release_notes": "Release 1.0.0"
  }'

---

Platform-Specific Guides

Detailed step-by-step guides are available for:

• GitHub Actions — Workflow examples and best practices
• GitLab CI — Pipeline configuration and artifact handling
• Jenkins — Declarative and scripted pipeline examples

---

Best Practices

1. Use service accounts — Create dedicated service accounts for CI/CD pipelines
2. Store credentials securely — Use CI/CD secrets management, never commit tokens
3. Validate artifacts — Compute and verify SHA256 checksums before registration
4. Handle errors — Implement error handling and retry logic for API calls
5. Idempotent workflows — Design workflows that can be rerun safely
6. Multi-platform builds — Use parallel jobs for multi-platform releases
7. Version extraction — Extract versions consistently from Git tags or build metadata

---

Common Workflows

Tag-Based Releases

Pipelines trigger on Git tags and publish releases automatically:

# Example: GitHub Actions
on:
  push:
    tags:
      - 'v*'

Multi-Platform Releases

Pipelines build artifacts for multiple platforms and create single releases:

• Build Windows, macOS, and Linux artifacts in parallel
• Register all artifacts
• Create release referencing all platform artifacts

Pre-Release Validation

Pipelines validate artifacts before publishing:

• Verify artifact checksums
• Test installer functionality
• Check release metadata completeness

---

Troubleshooting

Authentication failures — Verify service account credentials and scopes

Artifact registration errors — Check artifact URLs are accessible and checksums match

Release creation failures — Verify product ID, version format, and artifact IDs

Network issues — Ensure CI/CD runners can reach Big Picture API endpoints

---

Related Documentation

• Reference: API Overview — Complete API documentation
• Workflows: Creating a Release — Release creation procedures
• Workflows: Creating Multi-Platform Releases — Multi-platform release workflows