How text-to-cad Automates Releases Using GitHub Actions: A Complete Workflow Guide

The text-to-cad repository automates its entire release pipeline through a single, parameter-driven GitHub Actions workflow named Release that handles version bumping, pull request creation, artifact publishing, and deployment in one atomic run.

The earthtojake/text-to-cad project streamlines its distribution process through sophisticated GitHub Actions release automation. This open-source CAD generation tool leverages a unified workflow defined in .github/workflows/release.yml to eliminate manual intervention during version updates. Understanding this automation provides valuable insights into maintaining reproducible build pipelines for complex, multi-component software projects.

The Single-Workflow Architecture

The repository employs a monolithic release workflow rather than fragmented CI jobs. This design ensures that version bumps, artifact uploads, and deployments occur within a single deterministic execution context.

Centralizing the automation reduces configuration drift and guarantees that every release follows the identical sequence defined in the workflow file. The approach also consolidates release policy documentation, which contributors can reference in AGENTS.md (Release Workflow section) and CONTRIBUTING.md (Releases section).

Step-by-Step Release Pipeline

When triggered, the workflow executes seven distinct phases through orchestrated shell and Node.js scripts.

1. Version Bump and PR Creation

The workflow initiates by calling scripts/release/create-pr.mjs to generate a release pull request. This script bumps the semantic version in plugins/cad/VERSION and targets the develop branch by default.

The pull request contains all necessary version increments, allowing maintainers to review changes before they reach production.

2. Version Synchronization

After the release PR merges, scripts/release/sync-version.mjs propagates the new version throughout the repository. This script stamps the updated version into pyproject.toml, package.json, and any other manifest files requiring version alignment.

3. Main Branch Publication

The workflow executes scripts/release/publish-to-main.sh to promote the release commit. This script checks out the main branch, cherry-picks or merges the release commit from develop, and pushes the update to the primary production branch.

4. Git Tagging and GitHub Release

Using scripts/release/publish-github-release.sh, the automation creates a Git tag matching the new semantic version and publishes a corresponding GitHub Release. This step can be disabled by setting the workflow input publish=false for dry-run scenarios.

5. Model Artifact Upload

The generated CAD models residing in models/ are uploaded to Vercel Blob storage via scripts/release/upload-models.sh. This ensures that binary assets are immediately available to end-users without manual upload procedures.

6. Web Application Deployment

The workflow triggers scripts/release/deploy-webapps.sh to rebuild and deploy the documentation site, CAD Viewer, and associated web interfaces. This guarantees that public-facing applications reflect the newly released functionality immediately.

7. Post-Release Validation

Finally, the workflow executes scripts/test/test.sh against the freshly built bundle to verify release integrity. This validation step runs the full test suite, ensuring that the published artifacts are functional and stable.

Workflow Inputs and Configuration

The release automation is parameter-driven, exposing several workflow inputs that callers can override when dispatching the action:

• base_branch – Source branch for the release PR (default: develop)
• target_branch – Branch receiving the final release commit (default: main)
• publish – Boolean flag to create GitHub Release immediately (default: true)
• set_version – Optional specific semver value to override automatic version bumping (useful for retries or hotfixes)

These inputs make the automation flexible while maintaining deterministic defaults suitable for standard release cycles.

Triggering the Release Automation

The workflow supports both manual invocation through the GitHub web interface and programmatic triggering via the GitHub CLI.

Manual Trigger via GitHub UI

1. Navigate to the Actions tab in the repository
2. Select the Release workflow from the sidebar
3. Click Run workflow
4. Accept the default parameters or modify inputs as needed
5. Click Run workflow to initiate the pipeline

Command-Line Invocation

Maintainers can trigger releases programmatically using the gh CLI tool:

gh workflow run Release \
  -f base_branch=develop \
  -f target_branch=main \
  -f publish=true

For specifying an exact version during a hotfix:

gh workflow run Release \
  -f set_version=1.2.3-hotfix.1 \
  -f publish=true

Summary

• The text-to-cad repository uses a single GitHub Actions workflow defined in .github/workflows/release.yml to automate releases.
• The pipeline executes seven phases: PR creation, version sync, main branch promotion, Git tagging, model upload, web deployment, and validation testing.
• Key scripts include scripts/release/create-pr.mjs, scripts/release/sync-version.mjs, and scripts/release/publish-github-release.sh.
• Workflow inputs like base_branch, target_branch, and publish allow flexible, parameterized releases without modifying workflow code.
• The automation handles binary assets by uploading models/ to Vercel Blob and deploys web applications atomically with the release.

Frequently Asked Questions

Can I specify an exact version number instead of auto-bumping?

Yes. Pass the set_version parameter with a specific semver value when triggering the workflow. The scripts/release/create-pr.mjs script will use this value instead of automatically incrementing the version, which is particularly useful for hotfixes or retrying failed releases.

What happens if the release PR fails tests?

The workflow waits for the PR to be manually reviewed and merged. If tests fail on the PR, the release process pauses until those issues are resolved. The workflow only proceeds to the version synchronization and deployment phases after the PR successfully merges into the base branch.

How are CAD models handled during the release?

The scripts/release/upload-models.sh script uploads all generated files from the models/ directory to Vercel Blob storage. This occurs after the GitHub Release is created but before the final validation tests, ensuring that binary assets are publicly available immediately upon release publication.

Is the release process atomic?

Yes. By consolidating version bumping, artifact publishing, and deployment into a single workflow run, the repository ensures that all release steps succeed or fail together. This atomic approach prevents scenarios where a version is bumped but artifacts fail to upload, maintaining consistency between the Git repository state and published releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}