This document describes the current test-release workflow of web.template and its relationship to frontend release-type detection.
The test-release workflow:
- creates an Expo Web export
- packages the generated files
- publishes the ZIP as a GitHub Actions artifact
- uploads the same ZIP to a dedicated FTP test directory
The architecture follows:
Application --> Template --> Core
Standard Agent.Workbench functionality belongs to the Base Template.
Concrete consumer Applications such as HEMS may own their own product-specific build and deployment configuration.
The test-release workflow provides a deployable web build for validation before a production release.
Typical purposes include:
- internal testing
- frontend/backend compatibility validation
- update-system testing
- release-type testing
- UI validation
- infrastructure validation
- manual inspection of a generated release artifact
The test workflow is not intended to represent the final production release.
The repository currently contains release workflows including:
.github/workflows/export-put-release.yml
.github/workflows/export-put-test-release.yml
This document focuses on:
.github/workflows/export-put-test-release.yml
The documented GitHub Actions workflow name is:
Export Put Test Release
Workflow behavior should always be verified against the committed YAML before changing release documentation.
The test-release workflow is manually triggered through:
on:
workflow_dispatch:This means the test release is explicitly started through GitHub Actions.
The documented workflow does not use an automatic branch or tag trigger for the test release.
The documented workflow runs on:
ubuntu-latest
The current job is documented as:
install
The workflow checks out the repository using:
uses: actions/checkout@v4with:
fetch-depth: 1The workflow also prints repository information for diagnostics.
Examples include:
GITHUB_SHA
current Git commit
current branch
repository files
package.json availability
package-lock.json availability
These diagnostic steps help identify build-context problems.
The documented workflow uses:
Node.js 20
through:
uses: actions/setup-node@v4with npm caching enabled.
The workflow then installs:
npm 10
using:
npm install -g npm@10The active Node.js and npm versions are printed before the build continues.
Dependencies are installed using:
npm ciThis is appropriate for release automation because it uses the committed lockfile instead of recalculating dependency resolution.
The workflow also contains diagnostic checks for package and lockfile information.
Observed diagnostics include areas such as:
package.json
package-lock.json
lockfile version
package name
package version
@floating-ui/dom
These checks are workflow diagnostics and not architectural requirements.
The release version is read from:
package.json
using:
node -p "require('./package.json').version"The result is used as the workflow version value and participates in artifact naming.
The workflow creates a timestamp using:
date +%Y%m%d-%H%MFormat:
yyyyMMdd-HHmm
Example:
20260810-1542
The timestamp participates in the generated artifact filename.
The documented workflow exports the Expo Web application using:
npx expo export -p webExpo writes the exported web application to:
dist/
The contents of dist/ are then packaged into the release ZIP.
Developer-facing Application configuration uses:
src/application/config/
├── application.properties
├── features.properties
└── navigation.properties
The project provides:
npm run config:generateGenerated runtime artifacts are written under:
src/application/generated/
The normal development lifecycle uses configuration generation before Application startup.
However, the documented test-release workflow directly executes:
npx expo export -p webTherefore the release workflow must not assume that normal npm startup lifecycle hooks automatically regenerate Application configuration.
The desired deterministic release sequence is:
checkout
|
v
npm ci
|
v
npm run config:generate
|
v
npx expo export -p web
If the current workflow does not explicitly contain the config:generate step, this remains a release-workflow improvement that should be addressed before relying on configuration-only changes in automated releases.
The developer-facing configuration source is the .properties configuration.
Generated TypeScript is build/runtime output.
Release automation should therefore produce generated artifacts from the committed configuration source instead of relying on previously generated files being current.
Conceptually:
Application .properties
|
v
config:generate
|
v
generated runtime artifacts
|
v
Expo export
This keeps release builds deterministic.
After the Expo export, the workflow packages the contents of:
dist/
into a ZIP file.
The documented naming pattern is:
<PROJECT_NAME>_<package.version>_<yyyyMMdd-HHmm>.zip
The ZIP contains the exported web application contents rather than introducing dist/ as an additional top-level directory.
Conceptually:
dist/*
|
v
<PROJECT_NAME>_<version>_<timestamp>.zip
The artifact name uses the GitHub repository secret:
PROJECT_NAME
Conceptually:
PROJECT_NAME
+
package.json version
+
timestamp
=
artifact filename
The workflow therefore does not need to hardcode the project name directly into the artifact name.
The generated ZIP is uploaded as a GitHub Actions artifact.
The documented workflow uses:
actions/upload-artifact@v4The artifact name follows:
<PROJECT_NAME>_<version>_<timestamp>
The uploaded ZIP is:
<PROJECT_NAME>_<version>_<timestamp>.zip
This allows the test build to be inspected independently from the FTP deployment.
The same ZIP is uploaded to the configured FTP server.
The test target is:
<PROJECT_PATH>/test
Conceptually:
GitHub Actions
|
v
generated ZIP
|
+------------------+
| |
v v
GitHub artifact FTP test directory
The target test directory must exist on the FTP server unless the workflow explicitly creates it.
The workflow uses the command-line FTP client.
Conceptually:
open <FTP_UPLOAD_URL>
user <FTP_USER> <FTP_PSWD>
cd <PROJECT_PATH>/test
put <artifact>.zip
exit
The workflow should not expose credential values in logs.
The documented test workflow references:
| Secret | Purpose |
|---|---|
FTP_UPLOAD_URL |
FTP server address |
FTP_USER |
FTP username |
FTP_PSWD |
FTP password |
PROJECT_NAME |
Prefix for artifact naming |
PROJECT_PATH |
Base FTP project directory |
The test workflow appends:
/test
to PROJECT_PATH.
The secret name:
FTP_PSWD
must not be renamed in documentation unless the workflow is changed at the same time.
The FTP /test path determines where the test artifact is uploaded.
Frontend release-type presentation is a separate concern.
The frontend receives release-type information from backend application settings.
Relevant backend key:
_WebAppReleaseType
The deployment directory must not become a second independent frontend release-type detection mechanism.
The documented frontend release states are:
PRODUCTION_RELEASE
TEST_RELEASE
UNKNOWN
Reusable release state is represented by:
WebAppReleaseType
under:
src/template/state/release/appReleaseSlice.tsx
Release state belongs to Template because it supports reusable application-shell behavior.
Technical backend release-type parsing is implemented in:
src/core/server/serverCheck.ts
The server-check infrastructure reads:
_WebAppReleaseType
from backend application settings.
The documented recognized values include:
TEST_RELEASE
PRODUCTION_RELEASE
Technical parsing belongs to Core because it is reusable backend inspection behavior.
Reusable release state exists at:
src/template/state/release/appReleaseSlice.tsx
The state handles the normalized release classification used by reusable Template presentation.
Conceptually:
Backend application settings
|
v
Core serverCheck
|
v
Template release state
|
v
Template presentation
Technical parsing and UI state remain separate responsibilities.
The Template release state also supports:
UNKNOWN
The current implementation should be inspected before changing fallback or overwrite behavior.
Release-type fallback logic should remain centralized rather than being duplicated inside presentation components.
Changes should be tested together with server switching and initialization behavior.
Reusable footer presentation exists at:
src/template/components/layout/Footer.tsx
Release-related UI such as a test-release indicator belongs to Template presentation.
The footer consumes normalized state.
It must not parse backend settings directly.
Responsibility remains:
serverCheck
-> technical detection
appReleaseSlice
-> reusable state
Footer
-> presentation
Release-related architecture follows:
Core
|
+-- technical backend release-type parsing
Template
|
+-- reusable release Redux state
+-- reusable release presentation
Application
|
+-- concrete consumer build configuration
+-- concrete consumer deployment configuration
+-- product-specific release settings where required
Standard Agent.Workbench frontend behavior remains part of Template.
Agent.Workbench is the current in-repository Application identity/composition, but it is not modeled as a separate consumer Application repository.
Concrete consumer Applications should own their product-specific build and deployment configuration.
For example, a future HEMS repository may own:
HEMS release configuration
HEMS deployment destination
HEMS product infrastructure
HEMS build workflow
The Base Template may provide reusable build mechanisms and integration contracts.
It should not need to know a concrete consumer's deployment target.
The release workflows currently live inside web.template.
This is valid for the current repository because web.template also contains the in-repository Agent.Workbench Application composition and standard Agent.Workbench Base Template functionality.
Their current physical location does not imply that future concrete consumer repositories such as HEMS must share the same deployment configuration.
Future consumer build ownership should be validated when a real consumer repository is integrated.
The previous architecture assumed a future:
Agent.Workbench Application repository
with its own extracted product build and deployment workflow.
That is no longer the selected architecture.
Standard Agent.Workbench functionality belongs to the Base Template.
Therefore the architecture does not require a separate Agent.Workbench consumer repository solely for release ownership.
Future release separation work should focus on concrete consumers such as HEMS.
The repository contains:
.github/workflows/export-put-test-release.yml
.github/workflows/export-put-release.yml
The documented test workflow uploads to:
<PROJECT_PATH>/test
Production behavior must be verified against:
.github/workflows/export-put-release.yml
before documenting or changing production-release behavior.
Do not infer unverified production behavior from the test workflow.
Use the test-release workflow when:
- a frontend build should be validated before production
- update behavior needs testing
- frontend/backend compatibility should be checked
- a release ZIP should be inspected
- release-type presentation needs validation
- infrastructure changes need a deployed test build
- testing should occur without using the production deployment target
The documented artifact naming structure is:
<PROJECT_NAME>_<version>_<timestamp>.zip
The test nature of the deployment is represented by:
<PROJECT_PATH>/test
The documented workflow does not add a -TEST suffix to the ZIP name.
If artifact naming changes, update workflow and documentation together.
If the workflow fails before export, inspect:
Node.js version
npm version
npm ci
package-lock.json
package.json
workflow logs
Do not change dependency resolution from inside the release workflow merely to make a release succeed.
Dependency fixes belong in the repository and lockfile.
If the exported Application contains unexpected configuration, inspect:
src/application/config/application.properties
src/application/config/features.properties
src/application/config/navigation.properties
and generated artifacts under:
src/application/generated/
Then verify whether the release workflow ran:
npm run config:generatebefore Expo export.
A stale generated file must not be treated as authoritative over the developer-facing .properties configuration.
If the GitHub Actions artifact exists but FTP upload fails, then build and packaging have already succeeded.
Check:
FTP_UPLOAD_URL
FTP_USER
FTP_PSWD
PROJECT_PATH
FTP server availability
FTP target directory
workflow logs
Also verify that:
<PROJECT_PATH>/test
exists or is created by the workflow.
If a test deployment does not produce the expected frontend test indicator, inspect the backend application settings for:
_WebAppReleaseType
Expected test value:
TEST_RELEASE
Then inspect:
src/core/server/serverCheck.ts
src/template/state/release/appReleaseSlice.tsx
src/template/components/layout/Footer.tsx
Do not add a second release-type parser in the footer.
After changing release infrastructure, validate relevant source and workflow references.
Useful searches:
git grep -n "_WebAppReleaseType" -- src
git grep -n "TEST_RELEASE" -- src
git grep -n "PRODUCTION_RELEASE" -- src
git grep -n "appReleaseSlice" -- src testInspect workflow changes:
git diff -- .github/workflows/export-put-test-release.ymlRun Application configuration generation:
npm run config:generateRun TypeScript validation:
npx tsc --noEmitRun affected tests:
npm test -- --runInBandValidate the patch:
git diff --check
git status --shortThe documented test-release workflow includes:
manual workflow trigger
Node.js 20
npm 10
npm caching
npm ci
Expo Web export
ZIP packaging
GitHub Actions artifact upload
FTP test upload
/test deployment target
backend _WebAppReleaseType parsing
Template release state
reusable release presentation
The key current release-workflow review item is:
ensure npm run config:generate executes explicitly
before Expo export
This is a deterministic-build concern.
It is not an Agent.Workbench extraction concern.
Future concrete consumer Applications may require:
consumer-specific build workflows
consumer-specific deployment destinations
consumer release configuration
consumer infrastructure configuration
HEMS is an example of such a future consumer.
Release-related work must preserve:
Application --> Template --> Core.- Core must not import Template or Application.
- Backend release-type parsing may remain reusable Core functionality.
- Reusable release state belongs to Template.
- Reusable release presentation belongs to Template.
- Standard Agent.Workbench functionality belongs to Template.
- HEMS-specific deployment configuration belongs to HEMS.
- Release-type UI must consume normalized state instead of parsing backend settings independently.
- Test and production deployment targets must remain distinguishable.
- Application configuration generation should be deterministic before export.
- Workflow documentation must match the committed workflow.
- Unverified production behavior must not be documented as fact.
- Future concrete consumer repositories may own their own build/deployment pipelines.
- A separate Agent.Workbench Application repository is not required.
The following statements are no longer correct:
"Agent.Workbench is a concrete Application repository."
"Agent.Workbench must eventually own a separate release pipeline."
"Release workflow ownership requires Agent.Workbench extraction."
"web.template is only temporarily responsible for Agent.Workbench releases."
"Agent.Workbench and HEMS must have equivalent consumer repositories."
The correct architecture is:
Agent.Workbench standard functionality
-> Base Template
HEMS
-> concrete Application
The test-release architecture is correct when:
- The committed workflow and documentation match.
- Test builds use deterministic dependency installation.
- Application configuration is generated explicitly before export.
- Test artifacts remain separate from production deployment.
- Backend release type is parsed in one reusable technical location.
- Template state consumes normalized release information.
- Presentation does not duplicate backend parsing.
- Standard Agent.Workbench release presentation remains Template-owned.
- Concrete consumers such as HEMS can own their own deployment configuration.
- The Base Template does not depend on HEMS deployment details.
- Workflow secrets remain documented consistently with the workflow.
- Architecture remains consistent with
Application --> Template --> Core.
The test-release workflow currently builds and deploys the web frontend for validation.
The architectural ownership is:
Core
technical release-type parsing
Template
reusable release state
reusable release presentation
standard Agent.Workbench frontend behavior
Application
concrete consumer build/deployment configuration
The most important current workflow improvement is to ensure that:
npm run config:generateruns explicitly before:
npx expo export -p webwhen that step is not already present in the committed workflow.
This keeps generated Application configuration deterministic.
A future HEMS consumer may own its own release pipeline.
A separate Agent.Workbench Application repository is not part of the current architecture.