Tutti App Release

Tutti App Release

Use this skill when an external app repository publishes a remote Tutti workspace app into App Center release metadata.

The external repository calls the reusable workflow from the Tutti/Tutti repository:

uses: tutti-os/tutti/.github/workflows/publish-tutti-app-release.yml@main

That workflow builds one app package, runs @tutti-os/app-release-tools, uploads immutable release files plus mutable latest.json and versions.json, and can optionally merge that app into the shared catalog.json.

Operating Rules

Inspect before acting:

• Read the caller workflow, tutti.app.json, package script, and recent GitHub Actions runs.
• Confirm whether the user wants a new app release, a catalog refresh, or CI debugging. Do not rerun a release just to repair catalog state.

For catalog publication:

• There are three valid modes. Explain them explicitly when helping a user choose.
• Release only: publish_catalog: false. This uploads a new app version and updates apps/<appId>/latest.json and versions.json; App Center will see it the next time catalog.json is published.
• Release and catalog: publish_catalog: true. This uploads the app release, then immediately merges that release into catalog.json.
• Catalog only: catalog_only: true. Use this after a release already succeeded when the user forgot to publish catalog, wants to validate first, or wants to refresh catalog without bumping or uploading a new version.
• Do not rerun a full app release just to repair catalog state.
• If the app caller workflow exposes catalog_only, use that. If it does not, use the Tutti catalog workflow directly or add the caller input when the user wants that repo to support catalog-only dispatch.

For versioning:

• Production releases should be workflow-driven. Run the production caller workflow with release_bump (patch, minor, or major); the reusable workflow calculates the next version from the greater of the packaged manifest version and existing release tags, then creates the tag after the S3 release verifies.
• The workflow never bumps or commits app manifest versions. Do not add caller-side release PRs or manifest bump commits to work around protected branches.
• Staging releases should leave release_bump empty. The workflow uses manifest.version+<short git sha> from the packaged manifest and does not create a release tag.

For reusable workflow changes:

• Keep long-lived release behavior in the Tutti reusable workflows and app release tools.
• Keep caller workflows small and stable: app id, package command/dir, runner/tool versions when needed, and environment-specific AWS/CDN values.
• Require callers to declare min_tutti_version explicitly. Use 0.0.0 only for releases that are safe for every legacy Tutti client.
• Avoid requiring app repositories to change for catalog repair behavior. Use an existing catalog-only path for that.

Release Contract

The caller repository must be compatible with pnpm. The reusable workflow runs pnpm install --frozen-lockfile before package_command, so the repository should commit pnpm-lock.yaml and define the package script used by package_command.

The caller repository must commit a source manifest:

tutti.app.json

The generated package directory must contain:

• tutti.app.json
• bootstrap.sh
• AGENTS.md
• the manifest icon asset, such as icon.png or icon.svg
• all runtime files and assets

The source and package manifests must use schemaVersion: "tutti.app.manifest.v1". appId must match the workflow app_id input.

The workflow writes release objects under:

apps/<appId>/<version>/
apps/<appId>/latest.json
apps/<appId>/versions.json

For production, the workflow derives the next release version by fetching existing stable semver tags with the configured release_tag_prefix (default <appId>-v), reading the packaged manifest version, and applying release_bump to the greater version. It creates the annotated release tag after the S3 release has been uploaded and verified. If release_bump is empty, the workflow uses manifest.version+<short git sha> from the packaged manifest, which is intended for staging.

Reference Caller Workflow

Use this as the default single-app production caller. Production releases should be workflow-driven so publishing does not need to write version bump commits back to the protected source branch. Keep new app repositories as close to this reference as their package command allows.

name: Publish Tutti App Production

on:
  workflow_dispatch:
    inputs:
      release_bump:
        description: Semver bump to publish.
        required: true
        type: choice
        default: patch
        options:
          - patch
          - minor
          - major
      publish_catalog:
        description: Whether to publish the production App Center catalog after this release.
        required: false
        type: boolean
        default: true
      catalog_only:
        description: Whether to skip app release upload and only publish the existing latest release to catalog.
        required: false
        type: boolean
        default: false
permissions:
  contents: write
  id-token: write

jobs:
  publish:
    uses: tutti-os/tutti/.github/workflows/publish-tutti-app-release.yml@main
    with:
      app_id: your-app-id
      min_tutti_version: "REQUIRED_MIN_TUTTI_VERSION"
      package_command: pnpm package:tutti
      package_dir: build/tutti-app/package
      icon_path: build/tutti-app/package/icon.png
      release_tag_prefix: your-app-id-v
      release_bump: ${{ inputs.release_bump }}
      create_release_tag: ${{ !inputs.catalog_only }}
      publish_catalog: ${{ inputs.publish_catalog }}
      catalog_only: ${{ inputs.catalog_only }}
      aws_region: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_AWS_REGION || vars.TUTTI_APP_RELEASES_AWS_REGION }}
      aws_role_arn: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_AWS_ROLE_ARN || vars.TUTTI_APP_RELEASES_AWS_ROLE_ARN }}
      s3_bucket: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_S3_BUCKET || vars.TUTTI_APP_RELEASES_S3_BUCKET }}
      s3_prefix: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_S3_PREFIX || vars.TUTTI_APP_RELEASES_S3_PREFIX }}
      release_assets_base_url: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_BASE_URL || vars.TUTTI_APP_RELEASES_BASE_URL }}
      catalog_cloudfront_distribution_id: ${{ vars.TUTTI_APP_RELEASES_PRODUCTION_CLOUDFRONT_DISTRIBUTION_ID || vars.TUTTI_APP_RELEASES_CLOUDFRONT_DISTRIBUTION_ID || '' }}

Use only workflow_dispatch for staging unless every merge should publish staging too. Keep staging and production on separate S3 prefixes and base URLs.

Pin the reusable workflow ref only when the caller needs reproducible release behavior:

uses: tutti-os/tutti/.github/workflows/publish-tutti-app-release.yml@<tag-or-commit-sha>

For monorepos that publish multiple apps, keep the caller shape the same but resolve a target matrix from repository config. Each matrix target should expose the same reusable workflow inputs:

app_id: ${{ matrix.target.app_id }}
min_tutti_version: ${{ matrix.target.min_tutti_version }}
package_command: ${{ matrix.target.package_command }}
package_dir: ${{ matrix.target.package_dir }}
icon_path: ${{ matrix.target.icon_path }}
release_tag_prefix: ${{ matrix.target.release_tag_prefix }}
release_bump: ${{ inputs.release_bump }}
create_release_tag: ${{ !inputs.catalog_only }}

Reusable Workflow Inputs

Required release inputs:

• app_id: app id, matching the source and package tutti.app.json.
• min_tutti_version: minimum compatible Tutti SemVer for a normal release. It has no permissive default; catalog-only repairs read the stored rule from versions.json.
• aws_region: AWS region for the release bucket.
• aws_role_arn: IAM role assumed through GitHub OIDC.
• s3_bucket: bucket receiving release files.

Conditionally required inputs:

• package_command: builds or copies the final package. Required unless catalog_only is true.
• package_dir: package directory produced by package_command. Required unless catalog_only is true.
• release_assets_base_url: public base URL for s3_bucket plus s3_prefix. Required unless catalog_only is true.

Optional release/version inputs:

• icon_path: package-local icon path override. Use when the manifest icon should be resolved from a generated package path.
• release_tag_prefix: release tag prefix used when calculating and creating production release tags. Defaults to <appId>-v.
• release_bump: production semver bump. Valid values are patch, minor, and major. Leave empty for staging.
• create_release_tag: create the annotated release tag after the S3 release verifies. Production callers should set this to true; staging callers should leave it false.

Optional catalog inputs:

• publish_catalog: after uploading the app release, merge that release into catalog.json. Default: false.
• catalog_only: skip package build, release metadata generation, and app release upload; rebuild the app from apps/<appId>/versions.json into catalog.json. Default: false.
• catalog_cloudfront_distribution_id: CloudFront distribution id for invalidating /<s3_prefix>/catalog.json after catalog upload. Default: empty. Caller workflows normally read this from TUTTI_APP_RELEASES_PRODUCTION_CLOUDFRONT_DISTRIBUTION_ID or TUTTI_APP_RELEASES_CLOUDFRONT_DISTRIBUTION_ID; prefer storing the shared value as an organization variable with selected repository access, and use repository variables only for overrides or when organization variables are unavailable. If neither variable is configured, invalidation is skipped and readers rely on the catalog cache TTL.

Optional runtime/tooling inputs:

• runner: GitHub runner label. Default: ubuntu-latest.
• node_version: Node.js version. Default: 24.
• pnpm_version: pnpm version. Default: 10.11.0.
• release_tools_package: app release tools package spec. Default: @tutti-os/app-release-tools@latest. Pin this only when debugging or when the reusable workflow depends on a version not yet intended for general use.