bx-sites GitHub Actions Operations

Use this skill for CI and release operations in:

• Repository: ortus-boxlang/bx-sites
• Actions dashboard: https://github.com/ortus-boxlang/bx-sites/actions

Workflow inventory

Workflow	File	Trigger	Purpose
Daily Tests	cron.yml	cron 0 0 * * * (UTC)	Calls tests.yml
Pull Requests	pr.yml	push on any branch except main/master/development/releases/v*; pull_request to development and releases/v*; both ignore core/**, gradle-plugin/**, maven-plugin/**	Calls tests.yml; cancels the older duplicate run per branch
Test Suites	tests.yml	workflow_call + workflow_dispatch only	The one real test workflow
Build Snapshot	snapshot.yml	push to development, dispatch	Runs tests.yml, then release.yml with snapshot: true
Release	release.yml	push to main/master, workflow_call, dispatch	Stable release (or snapshot when called with snapshot: true)
Docbox	docbox.yml	workflow_call + workflow_dispatch only	Generates API docs, uploads ./apidocs to S3 via ./runDocs.sh
Publish Docs	pages.yml	push to development/main (no paths: filter), dispatch	10-theme matrix build, assemble, deploy to GitHub Pages
Gradle / Maven Plugin CI	gradle-plugin-ci.yml, maven-plugin-ci.yml	push to development/main/master and pull requests touching core/**, the plugin folder, or the workflow file	Job Build & Test on JDK 21
Gradle / Maven Plugin Release	gradle-plugin-release.yml, maven-plugin-release.yml	tags gradle-plugin-v* / maven-plugin-v*	Test, then publish to the Gradle Plugin Portal / Maven Central

The two plugin CI/release pairs are independent of the module's own tests.yml/release.yml flow - a failing plugin job is usually a JDK 21 / Gradle-and-Maven-only concern, not a bx-sites runtime regression. The Maven jobs first run ./gradlew publishToMavenLocal in core/, so a Maven failure can originate in core/.

Where failures show up

tests.yml (reached via cron.yml, pr.yml, snapshot.yml):

• Matrix: ubuntu-latest (job Tests bx-sites) and windows-latest (job Tests bx-sites (windows-latest)). Both are required; a red Windows job fails the run. It covers path handling (backslashes, drive letters).
• CI installs bx-esapi bx-yaml bx-toml bx-markdown bx-image bx-docbox with [email protected] (with-commandbox). A missing module shows up as a spec or build error, not a setup error.
• Step Run Tests: TestBox does not return a failing exit code, so this step sums tests/failures/errors across tests/results/*.xml and fails on any failure or error. 0 tests or no XML at all is treated as a crash (likely a compile or bootstrap error earlier in the log). Each failing spec is printed as FAILURE: <class> > <spec> or ERROR: <class> > <spec> in that step's log - start there.
• Step Smoke Test - Real CLI Build (pwsh): bxSites new, build, page:rename, build, asserting site/ outputs and the rewritten link. It fails on any non-zero CLI exit. A failure here with green specs means a real-CLI or path bug the TestBox fakes missed.
• Artifacts tests-<os> hold the JUnit XML; job Publish Test Results publishes them.

release.yml: job build ("Build & Publish Release") runs [email protected], finalizes the changelog and docs/releases/ page (non-snapshot only), builds with Build.bx, tags, uploads to S3, publishes to ForgeBox, and creates the GitHub release. Job prep_next_release is skipped on development; otherwise it checks out development, runs box bump --minor --!TagVersion (module bx-cli) and commits "Version bump". A snapshot failure is usually in the S3 or ForgeBox step, not the tests, since snapshot.yml already ran them.

docbox.yml: [email protected] with bx-docbox; failures are in "Generate Documentation" (./runDocs.sh) or the S3 upload.

pages.yml ("Publish Docs"): main deploys the site root, development deploys only /next/ once main exists (whole site before then). Key log steps, in order: "Build the site" (per theme), "Verify the build actually produced output" (fails if site/ is empty), "Detect whether main exists yet" (step detect-main, a live git ls-remote), "Deploy the pruned site/ tree to GitHub Pages" (peaceiris/actions-gh-pages@v4, keep_files: true). One red matrix leg (Build [<theme>] (<branch>)) blocks assemble-and-deploy for all themes. Runs are grouped per branch with cancel-in-progress: false. If the live site is stale, check the run for that branch before the other.

Plugin workflows: JDK 21 (temurin). CI runs ./gradlew check in core/ and the plugin (Maven: mvn --batch-mode verify). Releases are triggered by pushing a gradle-plugin-v<version> / maven-plugin-v<version> tag; the tag suffix becomes the published version.

Versions: BoxLang 1.18.0 is the module minimum; the bx-sites CLI exits non-zero on failure, so a red step that runs boxlang bxSites ... is a real failure, not a masked one.

Required troubleshooting flow

When users mention CI/build/test/workflow failures, always do this:

1. List recent runs for the target workflow or repository.
2. Inspect failed jobs and fetch logs.
3. Identify the first actionable root cause.
4. Recommend minimal remediation steps.
5. If requested, trigger rerun or cancel stuck runs.

Suggested GitHub tool operations

• List workflows: actions_list(method=list_workflows)
• List runs: actions_list(method=list_workflow_runs, resource_id=<workflow id or file>)
• List jobs: actions_list(method=list_workflow_jobs, resource_id=<run id>)
• Read logs: get_job_logs(job_id=<job id>, return_content=true)
• Rerun run: actions_run_trigger(method=rerun_workflow_run, run_id=<run id>)
• Rerun failed jobs: actions_run_trigger(method=rerun_failed_jobs, run_id=<run id>)
• Cancel run: actions_run_trigger(method=cancel_workflow_run, run_id=<run id>)

Output expectations

For each investigation, report:

• Workflow/run/job identifiers
• Failing step name
• Direct error excerpt from logs
• Root cause summary
• Minimal fix or rerun recommendation