App Registries

App registries allow you to deploy and distribute Flows apps within your organization or publicly. A registry is simply a collection of JSON files hosted on a web server that describe available apps and their versions.

Overview

App registries provide:

Centralized distribution: Host apps on any web server (S3, GitHub Pages, etc.)
Version management: Support multiple versions of each app with semantic versioning
Automatic updates: Flows periodically checks registries for new versions
Checksum verification: Ensures artifact integrity with SHA-256 checksums

Organizations automatically subscribe to the official Core and Community registries, but you can create and subscribe to custom registries for internal or third-party apps.

Registry Structure

A registry consists of two types of JSON files:

Registry manifest - The main index file listing all apps
App metadata files - Individual files for each app containing version information

Registry Manifest

The registry manifest is a JSON file at the root URL of your registry:

{
  "apps": {
    "my-app": {
      "name": "My App",
      "description": "A custom app for internal workflows",
      "blockStyle": {
        "iconUrl": "https://my-registry.example.com/apps/my-app/icon.png",
        "color": "#3B82F6"
      },
      "appMetadataUrl": "https://my-registry.example.com/apps/my-app/versions.json"
    },
    "another-app": {
      "name": "Another App",
      "description": "Another useful app",
      "blockStyle": {
        "iconUrl": "https://my-registry.example.com/apps/another-app/icon.svg",
        "color": "#10B981"
      },
      "appMetadataUrl": "https://my-registry.example.com/apps/another-app/versions.json"
    }
  }
}

Fields:

apps: Object mapping app keys to app information
- App key: Unique identifier for the app (used in URLs, must be URL-safe)
- name: Display name shown in the UI
- description: Brief description of the app’s functionality
- blockStyle: Visual styling for the app’s blocks
  - iconUrl: URL to the app icon (PNG or SVG)
  - color: Hex color code for the block background
- appMetadataUrl: URL to the app’s version metadata file

App Metadata File

Each app has a metadata file listing its available versions:

{
  "versions": [
    {
      "version": "1.0.0",
      "artifactUrl": "https://my-registry.example.com/apps/my-app/1.0.0.tar.gz",
      "artifactChecksum": "sha256:a1b2c3d4e5f6..."
    },
    {
      "version": "1.1.0",
      "artifactUrl": "https://my-registry.example.com/apps/my-app/1.1.0.tar.gz",
      "artifactChecksum": "sha256:f6e5d4c3b2a1..."
    }
  ]
}

Fields:

versions: Array of version objects (order doesn’t matter)
- version: Semantic version string (e.g., “1.2.3”)
- artifactUrl: URL to download the .tar.gz artifact
- artifactChecksum: SHA-256 checksum in the format sha256:HEX_STRING

Creating Your Own Registry

1. Choose hosting

You can host your registry on any static file server:

Amazon S3: Simple, scalable storage with CloudFront CDN
GitHub Pages: Free hosting for public registries
Azure Blob Storage: Enterprise-grade storage with CDN
Your own web server: Any HTTP server can serve JSON files

2. Create app artifacts

Build your app artifacts using flowctl:

# Create a tarball of your app
flowctl version bundle -e main.ts -o my-app-1.0.0.tar.gz

This creates a .tar.gz file containing your app code.

3. Calculate checksums

Generate SHA-256 checksums for your artifacts:

# macOS/Linux
shasum -a 256 my-app-1.0.0.tar.gz

# Output: a1b2c3d4e5f6... my-app-1.0.0.tar.gz

Format the checksum as sha256:HEX_STRING for the metadata file.

4. Create metadata files

Create the app metadata file (versions.json):

{
  "versions": [
    {
      "version": "1.0.0",
      "artifactUrl": "https://my-registry.example.com/apps/my-app/1.0.0.tar.gz",
      "artifactChecksum": "sha256:a1b2c3d4e5f6..."
    }
  ]
}

5. Create the registry manifest

Create the main registry manifest file:

{
  "apps": {
    "my-app": {
      "name": "My App",
      "description": "Description of my app",
      "blockStyle": {
        "iconUrl": "https://my-registry.example.com/apps/my-app/icon.png",
        "color": "#3B82F6"
      },
      "appMetadataUrl": "https://my-registry.example.com/apps/my-app/versions.json"
    }
  }
}

6. Upload files

Upload all files to your hosting service:

my-registry.example.com/
├── registry.json              # Main manifest
└── apps/
    └── my-app/
        ├── icon.png           # App icon
        ├── versions.json      # App metadata
        └── 1.0.0.tar.gz       # App artifact

7. Configure CORS (if needed)

If hosting on S3 or another origin, configure CORS headers to allow Flows to fetch the files:

{
  "CORSRules": [
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"]
    }
  ]
}

Example: GitHub Pages Registry

Here’s a complete example using GitHub Pages:

Repository structure

my-flows-registry/
├── index.json                 # Main manifest (served as root)
└── apps/
    └── my-app/
        ├── icon.svg
        ├── versions.json
        ├── 1.0.0.tar.gz
        └── 1.1.0.tar.gz

index.json

{
  "apps": {
    "my-app": {
      "name": "My App",
      "description": "Internal workflow automation app",
      "blockStyle": {
        "iconUrl": "https://myorg.github.io/my-flows-registry/apps/my-app/icon.svg",
        "color": "#6366F1"
      },
      "appMetadataUrl": "https://myorg.github.io/my-flows-registry/apps/my-app/versions.json"
    }
  }
}

apps/my-app/versions.json

{
  "versions": [
    {
      "version": "1.0.0",
      "artifactUrl": "https://myorg.github.io/my-flows-registry/apps/my-app/1.0.0.tar.gz",
      "artifactChecksum": "sha256:abc123..."
    },
    {
      "version": "1.1.0",
      "artifactUrl": "https://myorg.github.io/my-flows-registry/apps/my-app/1.1.0.tar.gz",
      "artifactChecksum": "sha256:def456..."
    }
  ]
}

GitHub Pages setup

Create a repository with your registry files
Enable GitHub Pages in repository settings
Set source to the main branch
Access your registry at https://myorg.github.io/my-flows-registry/index.json

Subscribing to a Registry

Once your registry is set up, subscribe your organization to it through the Flows UI or API.

Via UI

Navigate to Settings → App Registries
Click Subscribe to Registry
Enter your registry URL (e.g., https://my-registry.example.com/registry.json)
Provide a name for the registry
Click Subscribe

Flows will automatically refresh the registry and make apps available for installation.

Via API

curl -X POST https://flows.example.com/api/registries/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-registry.example.com/registry.json",
    "name": "My Internal Registry"
  }'

Publishing New Versions

To publish a new version of an app:

Build the artifact:

flowctl version bundle -e main.ts -o my-app-1.2.0.tar.gz

Calculate checksum:
Terminal window
```
shasum -a 256 my-app-1.2.0.tar.gz
```

Update versions.json:

{
  "versions": [
    {
      "version": "1.2.0",
      "artifactUrl": "https://my-registry.example.com/apps/my-app/1.2.0.tar.gz",
      "artifactChecksum": "sha256:NEW_CHECKSUM"
    }
  ]
}

Upload files: Upload the new artifact and updated versions.json

Flows automatically checks for updates hourly and will discover the new version.

Best Practices

Security

Always use HTTPS: Protect artifacts and metadata in transit
Verify checksums: Flows automatically verifies checksums to prevent tampering
Access control: Use signed URLs or authentication if hosting sensitive apps
CORS configuration: Only allow necessary origins if possible

Organization

Semantic versioning: Follow SemVer for predictable version management
Immutable artifacts: Never modify published artifacts; publish new versions instead
Directory structure: Keep a clean, organized structure for maintainability
Documentation: Include a README in your registry repository

Performance

Use a CDN: CloudFront, Fastly, or similar for faster global access
Compress artifacts: Use gzip compression for artifacts (already done by tar.gz)
Cache headers: Set appropriate cache headers for JSON files (e.g., Cache-Control: public, max-age=300)

Version management

Keep all versions: Don’t delete old versions users may depend on
Document breaking changes: Note major version changes in descriptions
Test before publishing: Validate artifacts work before adding to registry
Gradual rollout: Test new versions in development before promoting

Official Registries

Flows includes two official registries:

Core Registry (https://registry.useflows.com/core): Official apps maintained by Spacelift
Community Registry (https://registry.useflows.com/community): Community-contributed apps

All organizations are automatically subscribed to these registries upon creation.

Troubleshooting

Registry not refreshing

Check that your registry URL is accessible via HTTPS
Verify CORS headers are configured correctly
Ensure JSON files are valid (use a JSON validator)
Check Flows logs for specific error messages

Checksums don’t match

Verify you’re using SHA-256 (not SHA-1 or MD5)
Ensure the format is exactly sha256:HEX_STRING (all lowercase)
Check that the artifact file wasn’t modified after checksum calculation
Recalculate the checksum and update the metadata

Icons not displaying

Verify the icon URL is accessible via HTTPS
Check that CORS headers allow the Flows domain
Ensure the image format is PNG or SVG
Keep icon files under 1MB for best performance

Apps not appearing

Verify the app key is URL-safe (alphanumeric, hyphens, underscores)
Check that appMetadataUrl is correct and accessible
Ensure at least one valid version exists in the versions array
Validate all version strings follow semantic versioning