Skip to content

Component Release

This page defines how Appcircle workflow and publish components are versioned, tested, promoted, and released across environments.

Tags: component-release workflow-components publishflow-components build-server publish-server

What "Component Release" is

In Appcircle, a component is a single, versioned, runnable building block that appears as a step in a Build or Publish workflow — what a user sees in the workflow editor as "Run Tests", "Sign iOS", "Upload to TestFlight", "Firebase App Distribution", etc. Each component is a small repo that contains:

  • a component.yaml (metadata: title, description, inputs/outputs, execution settings)
  • a main.<ext> (Ruby/shell/etc.) that does the actual work

Source of truth

Component releases are not driven directly from the component repository alone. The effective component catalogue is controlled by the component manifest repositories listed below.

Scope

This process applies to components referenced by:

Area Manifest repository Consumer
Build components appcircle-workflow-components Build Server
Publish components appcircle-publishflow-components Publish Server and, for most publish components, Build Server

The manifest repositories keep versioned component definitions that point to a specific commit in the real component repository. Build and Publish servers read these manifest repositories and expose the resolved component list to end users.

Key Rules

Do not mutate released component versions

If an existing component version requires a fix, create a new component version and point it to the corrected commit. Do not silently change the commit behind an already released version.

  • appcircle-workflow-components and appcircle-publishflow-components are authoritative for the component title, description, version, and exposed metadata.
  • Title and description changes must be made in the manifest repositories, even if similar metadata exists in the component repository.
  • The commit field in component.yaml must point to the exact commit that should be executed.
  • Version bumps must follow the impact of the change:
  • Patch: backwards-compatible bug fixes, copy fixes, metadata fixes, small behavior corrections.
  • Minor: backwards-compatible new behavior, new optional inputs, new capabilities.
  • Major: breaking behavior, removed inputs, changed defaults, incompatible output or execution changes.
  • Publish component changes may require both Publish Server and Build Server deployment.
  • For publish components, components that are not server-side (runOn: "Server" in the component YAML) are interpreted by Build Server. Therefore, their manifest changes must be picked up by Build Server as well.

Branch and Environment Mapping

Manifest branch Environment Deployment trigger
testing Develop Automatic branch update, followed by Build/Publish server deployment to develop
develop Prep Manual promotion, followed by Build/Publish server deployment to prep
master Production Manual promotion, followed by Build/Publish server deployment to production

Note

Develop environments consume the testing branch of the component manifest repositories. Production deployments consume the master branch.

Component Metadata Example

Component versions are managed by folder structure, not by a version field inside component.yaml. Each version must have its own folder under the component directory.

Example:

appcircle_publish_send_email/
+-- 1.0.0/
|   +-- component.yaml
+-- 1.2.0/
    +-- component.yaml

When adding a new component version, create a new version folder by following the versioning convention, then place the updated component.yaml under that folder.

The component.yaml file inside the version folder must point to the exact component repository commit:

title: Run Tests
description: Executes the configured test command and publishes the result.
commit: 051a22a

When the implementation is updated, add a new version folder and reference the new commit:

appcircle_publish_send_email/
+-- 1.2.1/
    +-- component.yaml

commit: 8f71c10

Standard Release Flow

Use this flow when develop-environment validation is sufficient.

1. Implement the Component Change

  1. Open a feature branch in the real component repository.
  2. Implement the feature, improvement, metadata-related behavior, or fix.
  3. Push the branch.
  4. Record the latest commit ID from the feature branch.

2. Register the Candidate Version

  1. Open the relevant manifest repository:
  2. Build component: appcircle-workflow-components
  3. Publish component: appcircle-publishflow-components
  4. Checkout the testing branch.
  5. Add a new component version by following the versioning convention. Each version must be added as a new folder, for example appcircle_publish_send_email/1.2.1/component.yaml.
  6. Set component.yaml commit to the feature branch commit ID.
  7. Push the change to testing.

3. Deploy to Develop

Deploy the relevant services to the develop environment so they pick up the testing branch:

  • Build component change: deploy Build Server.
  • Publish component change: deploy Publish Server.
  • Publish component change interpreted by Build Server: deploy both Build Server and Publish Server.

4. Validate on Develop

Run the required component tests and user-flow validation on the develop environment.

The validation must confirm:

  • The new component version appears in the UI.
  • Title and description are correct.
  • Inputs, outputs, defaults, and runtime behavior match the change.
  • Existing component versions are not regressed.
  • Build and/or Publish server logs do not show manifest parsing or execution errors.

5. Promote to Production

If develop validation is sufficient:

  1. Merge the component repository feature branch into main.
  2. Record the latest commit ID from main.
  3. Update the relevant manifest repository entry to point to the main commit ID.
  4. Merge the manifest change to develop.
  5. Merge develop to master.
  6. Trigger production deployment from master:
  7. Build-only component: deploy Build Server.
  8. Publish component: deploy Publish Server.
  9. Publish component interpreted by Build Server: deploy both Build Server and Publish Server.

Once the production deployment is complete, the component version is available from the master manifest branch.

Prep Validation Flow

Use this flow when develop validation is not enough and the change must also be verified on prep before production.

1. Complete Develop Validation

Follow the standard release flow through develop validation.

At this point, the manifest testing branch points to the feature branch commit ID.

2. Promote the Candidate to Prep

  1. Update the develop branch of the relevant manifest repository to point to the same feature branch commit ID.
  2. Deploy the relevant services to the prep environment:
  3. Build component change: deploy Build Server.
  4. Publish component change: deploy Publish Server.
  5. Publish component interpreted by Build Server: deploy both Build Server and Publish Server.
  6. Validate the component on prep.

3. Finalize the Component Commit

After prep validation passes:

  1. Merge the component repository feature branch into main.
  2. Record the latest commit ID from main.
  3. Update the testing branch of the manifest repository to point to the main commit ID.
  4. Update the develop branch of the manifest repository to point to the main commit ID.
  5. Merge develop to master.
  6. Trigger production deployment from master.

Important

The commit ID used for production must be the commit from the component repository main branch, not the temporary feature branch commit used during develop or prep validation.

Release Checklist

Before production deployment:

  • A new component version has been created for every implementation or metadata fix.
  • component.yaml points to the intended commit ID.
  • Title and description are updated in the manifest repository.
  • Develop validation has passed.
  • Prep validation has passed, if required.
  • The component feature branch has been merged to main.
  • Manifest branches point to the final main commit ID.
  • develop has been merged to master.
  • Build Server deployment is triggered when the component is build-side or interpreted by Build Server.
  • Publish Server deployment is triggered when the component is publish-side.

Rollback Guidance

Rollback should be performed from the manifest repository first.

  1. Revert the manifest entry on the active branch or publish a newer fixed component version.
  2. Deploy the affected server again from the corrected branch.
  3. Confirm the previous known-good component version is visible and executable.

Do not roll back by force-pushing component repository history. The manifest commit reference must remain auditable.

Principle

A component release is complete only when the manifest version, referenced commit, target branch, and deployed server environment all point to the same intended release state.