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

> Automate text-to-cad releases with GitHub Actions. Learn how a single workflow handles version bumping, PRs, artifact publishing, and deployment for efficient releases.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/.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`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) (Release Workflow section) and [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/pyproject.toml), [`package.json`](https://github.com/earthtojake/text-to-cad/blob/main/package.json), and any other manifest files requiring version alignment.

### 3. Main Branch Publication

The workflow executes [`scripts/release/publish-to-main.sh`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

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

```

For specifying an exact version during a hotfix:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/.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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.