Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Update helm chart release workflows (#295)

Chirag Jainfd2f350cc9f5
diff --git a/.github/workflows/build-and-prepare-chart-release.yml b/.github/workflows/build-and-prepare-chart-release.yml
new file mode 100644
index 000000000..12fae118d
--- /dev/null
+++ b/.github/workflows/build-and-prepare-chart-release.yml
@@ -0,0 +1,188 @@
+name: Build and prepare chart release
+
+# Prod lane: build the npm-install Dockerfile, push {appVersion}-{shortSha},
+# then open/update the chart-release bot PR (merge of that PR tags + publishes).
+#
+# Triggered manually, including by release.yml through workflow_dispatch.
+on:
+ workflow_dispatch:
+ inputs:
+ app_version:
+ description: npm version to install (empty = Chart.yaml appVersion)
+ required: false
+ type: string
+ update_app_version:
+ description: Also set Chart.yaml appVersion to app_version on the bot PR
+ required: false
+ type: boolean
+ default: false
+
+concurrency:
+ group: release-image-and-chart
+ cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+ resolve:
+ name: Resolve versions
+ runs-on: ubuntu-latest
+ outputs:
+ app_version: ${{ steps.resolve.outputs.app_version }}
+ image_tag: ${{ steps.resolve.outputs.image_tag }}
+ update_app_version: ${{ steps.resolve.outputs.update_app_version }}
+ short_sha: ${{ steps.resolve.outputs.short_sha }}
+ permissions:
+ contents: read
+ steps:
+ - name: Check out
+ uses: actions/checkout@v4
+
+ - name: Install yq
+ run: |
+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq
+ sudo chmod +x /usr/bin/yq
+
+ - name: Resolve app version and image tag
+ id: resolve
+ env:
+ INPUT_APP_VERSION: ${{ inputs.app_version }}
+ INPUT_UPDATE_APP_VERSION: ${{ inputs.update_app_version }}
+ run: |
+ set -euo pipefail
+ CHART_APP=$(yq -r '.appVersion' charts/trueforge/Chart.yaml | tr -d '"')
+ if [[ -n "${INPUT_APP_VERSION}" ]]; then
+ APP_VERSION="$INPUT_APP_VERSION"
+ else
+ APP_VERSION="$CHART_APP"
+ fi
+ if [[ -z "$APP_VERSION" || "$APP_VERSION" == "null" ]]; then
+ echo "Could not resolve APP_VERSION" >&2
+ exit 1
+ fi
+ if ! printf '%s' "$APP_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$'; then
+ echo "APP_VERSION '$APP_VERSION' is not a semver-like version" >&2
+ exit 1
+ fi
+ SHORT_SHA="${GITHUB_SHA:0:7}"
+ IMAGE_TAG="${APP_VERSION}-${SHORT_SHA}"
+ UPDATE_APP="${INPUT_UPDATE_APP_VERSION:-false}"
+ # workflow_dispatch boolean can be the string "true"/"false"
+ if [[ "$UPDATE_APP" == "true" ]]; then
+ UPDATE_OUT=true
+ else
+ UPDATE_OUT=false
+ fi
+ echo "app_version=$APP_VERSION" >> "$GITHUB_OUTPUT"
+ echo "image_tag=$IMAGE_TAG" >> "$GITHUB_OUTPUT"
+ echo "short_sha=$SHORT_SHA" >> "$GITHUB_OUTPUT"
+ echo "update_app_version=$UPDATE_OUT" >> "$GITHUB_OUTPUT"
+ echo "Resolved APP_VERSION=$APP_VERSION IMAGE_TAG=$IMAGE_TAG update_app_version=$UPDATE_OUT"
+
+ build:
+ name: Build and push server image
+ needs: [resolve]
+ uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main
+ permissions:
+ id-token: write
+ contents: read
+ with:
+ artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
+ artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}
+ image_artifact_name: trueforge
+ image_tag: ${{ needs.resolve.outputs.image_tag }}
+ image_context: .
+ dockerfile_path: Dockerfile
+ image_build_args: |
+ APP_VERSION=${{ needs.resolve.outputs.app_version }}
+ platforms: linux/amd64
+ enable_jfrog: true
+ enable_public_ecr: false
+ secrets:
+ artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
+ artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
+
+ open-chart-pr:
+ name: Open chart release PR
+ needs: [resolve, build]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ pull-requests: write
+ env:
+ PR_BRANCH: release-chart/trueforge
+ steps:
+ - name: Check out
+ uses: actions/checkout@v4
+
+ - name: Install yq
+ run: |
+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq
+ sudo chmod +x /usr/bin/yq
+
+ - name: Update chart metadata
+ id: chart
+ env:
+ IMAGE_TAG: ${{ needs.resolve.outputs.image_tag }}
+ APP_VERSION: ${{ needs.resolve.outputs.app_version }}
+ UPDATE_APP_VERSION: ${{ needs.resolve.outputs.update_app_version }}
+ run: |
+ set -euo pipefail
+ SEMVER='^([0-9]+)\.([0-9]+)\.([0-9]+)(-[0-9A-Za-z.-]+)?$'
+ CURRENT=$(yq -r '.version' charts/trueforge/Chart.yaml)
+ if [[ ! "$CURRENT" =~ $SEMVER ]]; then
+ echo "Chart.yaml version '$CURRENT' on $GITHUB_REF_NAME is not semver" >&2
+ exit 1
+ fi
+ MAJOR="${BASH_REMATCH[1]}"
+ MINOR="${BASH_REMATCH[2]}"
+ PATCH="${BASH_REMATCH[3]}"
+ VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+
+ # create-pull-request rebuilds the PR branch from base plus this
+ # workspace, so a reviewer's major/minor bump on the open PR is dropped
+ # unless it is re-applied here. Only outrank the patch bump: a PR
+ # version at or below it means base already absorbed that release.
+ if git ls-remote --exit-code --heads origin "$PR_BRANCH" >/dev/null 2>&1; then
+ git fetch --depth=1 origin "$PR_BRANCH"
+ PR_VERSION=$(git show FETCH_HEAD:charts/trueforge/Chart.yaml | yq -r '.version')
+ if [[ "$PR_VERSION" =~ $SEMVER ]] &&
+ (( BASH_REMATCH[1] > MAJOR ||
+ (BASH_REMATCH[1] == MAJOR && BASH_REMATCH[2] > MINOR) ||
+ (BASH_REMATCH[1] == MAJOR && BASH_REMATCH[2] == MINOR && BASH_REMATCH[3] > PATCH + 1) )); then
+ echo "Keeping chart version $PR_VERSION from $PR_BRANCH (over $VERSION)"
+ VERSION="$PR_VERSION"
+ fi
+ fi
+ export VERSION IMAGE_TAG APP_VERSION
+ yq -i '.version = strenv(VERSION)' charts/trueforge/Chart.yaml
+ yq -i '.image.tag = strenv(IMAGE_TAG)' charts/trueforge/values.yaml
+ if [[ "$UPDATE_APP_VERSION" == "true" ]]; then
+ yq -i '.appVersion = strenv(APP_VERSION)' charts/trueforge/Chart.yaml
+ fi
+ APP_VERSION=$(yq -r '.appVersion' charts/trueforge/Chart.yaml)
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ echo "app_version=$APP_VERSION" >> "$GITHUB_OUTPUT"
+
+ - name: Open or update chart-release PR
+ uses: peter-evans/create-pull-request@v7
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ branch: ${{ env.PR_BRANCH }}
+ base: main
+ commit-message: 'release(chart): ${{ steps.chart.outputs.version }}'
+ title: 'release(chart): ${{ steps.chart.outputs.version }} (image ${{ needs.resolve.outputs.image_tag }})'
+ body: |
+ ## Chart release
+
+ | Field | Value |
+ | --- | --- |
+ | Chart version | `${{ steps.chart.outputs.version }}` |
+ | appVersion | `${{ steps.chart.outputs.app_version }}` |
+ | image.tag | `${{ needs.resolve.outputs.image_tag }}` |
+
+ Merging this PR creates `charts/trueforge@${{ steps.chart.outputs.version }}`,
+ creates a GitHub Release, and publishes the OCI Helm chart.
+ add-paths: |
+ charts/trueforge/Chart.yaml
+ charts/trueforge/values.yaml
diff --git a/.github/workflows/build-dev-image.yml b/.github/workflows/build-dev-image.yml
new file mode 100644
index 000000000..a89a5b617
--- /dev/null
+++ b/.github/workflows/build-dev-image.yml
@@ -0,0 +1,54 @@
+name: Build dev image
+
+# From-source image for floating-main / external deploy repos.
+# Builds Dockerfile.dev and pushes .../trueforge:<fullSha>. No chart publish.
+on:
+ workflow_dispatch:
+
+concurrency:
+ group: build-dev-image
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build and push from-source image
+ uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main
+ permissions:
+ id-token: write
+ contents: read
+ with:
+ artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
+ artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}
+ image_artifact_name: trueforge
+ image_tag: ${{ github.sha }}
+ image_context: .
+ dockerfile_path: Dockerfile.dev
+ platforms: linux/amd64
+ enable_jfrog: true
+ enable_public_ecr: false
+ secrets:
+ artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
+ artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
+
+ summary:
+ name: Print image URI
+ needs: [build]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ steps:
+ - name: Summary
+ env:
+ IMAGE_URI: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}/trueforge:${{ github.sha }}
+ run: |
+ set -euo pipefail
+ echo "Pushed image URI: $IMAGE_URI"
+ {
+ echo "### Dev image (from-source)"
+ echo "\`$IMAGE_URI\`"
+ echo ""
+ echo "Patch this SHA into your external \`truefoundry.yaml\` as \`image.tag\`."
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release-chart.yml b/.github/workflows/release-chart.yml
new file mode 100644
index 000000000..69b347668
--- /dev/null
+++ b/.github/workflows/release-chart.yml
@@ -0,0 +1,156 @@
+name: Publish Helm chart
+
+# A chart-release PR merge creates the tag/GitHub Release and publishes the
+# chart. Human charts/trueforge@* tags use the same publish job.
+on:
+ pull_request:
+ types: [closed]
+ branches: [main]
+ push:
+ tags:
+ - 'charts/trueforge@*'
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: Existing tag to publish (e.g. charts/[email protected])
+ required: true
+ type: string
+
+concurrency:
+ group: publish-helm-chart
+ cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+ release:
+ name: Create release and publish chart
+ if: >-
+ github.event_name != 'pull_request' ||
+ (
+ github.event.pull_request.merged == true &&
+ github.event.pull_request.head.ref == 'release-chart/trueforge' &&
+ github.event.pull_request.head.repo.full_name == github.repository
+ )
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ env:
+ CHART_DIR: charts/trueforge
+ HELM_REGISTRY_URL: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
+ HELM_CHART_REPOSITORY: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY }}
+ steps:
+ - name: Check out chart commit
+ uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.pull_request.merge_commit_sha || inputs.tag || github.ref }}
+ fetch-depth: 0
+
+ - name: Install yq
+ run: |
+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq
+ sudo chmod +x /usr/bin/yq
+
+ - name: Install Helm
+ uses: azure/setup-helm@v4
+ with:
+ version: v3.16.4
+
+ - name: Resolve or create chart release
+ env:
+ EVENT_NAME: ${{ github.event_name }}
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ INPUT_TAG: ${{ inputs.tag }}
+ MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+ PR_BODY: ${{ github.event.pull_request.body }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ run: |
+ set -euo pipefail
+
+ # Read the chart identity from the checked-out commit.
+ VERSION=$(yq -r '.version' charts/trueforge/Chart.yaml)
+ APP_VERSION=$(yq -r '.appVersion' charts/trueforge/Chart.yaml)
+ IMAGE_TAG=$(yq -r '.image.tag' charts/trueforge/values.yaml)
+
+ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+ echo "Invalid chart version: $VERSION" >&2
+ exit 1
+ fi
+
+ # Path A: bot chart-release PR was merged.
+ # Create the charts/trueforge@<version> tag + GitHub Release here,
+ # because GITHUB_TOKEN tag pushes do not start a separate push workflow.
+ if [[ "$EVENT_NAME" == "pull_request" ]]; then
+ TAG="charts/trueforge@${VERSION}"
+
+ if git rev-parse "$TAG" >/dev/null 2>&1; then
+ echo "Tag $TAG already exists; refusing to move it" >&2
+ exit 1
+ fi
+
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git tag -a "$TAG" -m "Helm chart ${VERSION} (appVersion ${APP_VERSION}, image ${IMAGE_TAG})"
+ git push origin "$TAG"
+
+ # Write notes via a file so PR body cannot inject into the shell.
+ NOTES_FILE="$(mktemp)"
+ {
+ echo "Source PR: #${PR_NUMBER}"
+ echo
+ printf '%s\n' "$PR_BODY"
+ } >"$NOTES_FILE"
+ gh release create "$TAG" \
+ --target "$MERGE_SHA" \
+ --title "$TAG" \
+ --notes-file "$NOTES_FILE"
+ rm -f "$NOTES_FILE"
+ # Path B: manual retry via workflow_dispatch with an explicit tag.
+ elif [[ -n "${INPUT_TAG:-}" ]]; then
+ TAG="$INPUT_TAG"
+
+ # Path C: human pushed charts/trueforge@* themselves.
+ else
+ TAG="${GITHUB_REF#refs/tags/}"
+ fi
+
+ # Every path must publish the same chart version the tag names.
+ case "$TAG" in
+ charts/trueforge@*) EXPECTED="${TAG#charts/trueforge@}" ;;
+ *) echo "Invalid chart tag: $TAG" >&2; exit 1 ;;
+ esac
+
+ ACTUAL=$(yq -r '.version' "$CHART_DIR/Chart.yaml")
+ if [[ "$ACTUAL" != "$EXPECTED" ]]; then
+ echo "Chart.yaml version '$ACTUAL' does not match tag version '$EXPECTED'" >&2
+ exit 1
+ fi
+
+ # VERSION is consumed by the package/push step below.
+ echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+ echo "Publishing chart version=$ACTUAL appVersion=$APP_VERSION image.tag=$IMAGE_TAG"
+
+ - name: Helm registry login
+ env:
+ HELM_REGISTRY_USERNAME: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
+ HELM_REGISTRY_PASSWORD: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
+ run: |
+ printf '%s' "$HELM_REGISTRY_PASSWORD" \
+ | helm registry login -u "$HELM_REGISTRY_USERNAME" --password-stdin "$HELM_REGISTRY_URL"
+
+ - name: Build chart dependencies
+ run: helm dependency build "$CHART_DIR"
+
+ - name: Package and push chart
+ run: |
+ set -euo pipefail
+ CHART_NAME=$(yq -r '.name' "$CHART_DIR/Chart.yaml")
+ mkdir -p dist
+ helm package "$CHART_DIR" --destination dist
+ PACKAGE="dist/${CHART_NAME}-${VERSION}.tgz"
+ echo "Pushing $PACKAGE to oci://$HELM_CHART_REPOSITORY"
+ helm push "$PACKAGE" "oci://$HELM_CHART_REPOSITORY"
+ {
+ echo "### Helm chart"
+ echo "Pushed \`oci://${HELM_CHART_REPOSITORY}/${CHART_NAME}:${VERSION}\`"
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release-image-and-chart.yml b/.github/workflows/release-image-and-chart.yml
deleted file mode 100644
index 0069cf1d8..000000000
--- a/.github/workflows/release-image-and-chart.yml
+++ /dev/null
@@ -1,126 +0,0 @@
-name: Release image and Helm chart
-
-# Manually dispatch to build and push the server image (tagged with the commit
-# SHA), stamp that SHA into the Helm chart, package it, and push it to the
-# JFrog public OCI Helm repo.
-on:
- workflow_dispatch:
-
-# One release at a time so the chart push cannot race.
-concurrency:
- group: release-image-and-chart
- cancel-in-progress: false
-
-permissions:
- contents: read
-
-jobs:
- # TODO: Re-enable this when we want to derive the version from the release tag.
- # Derive the version from the release tag; it is the single source of truth for
- # the image tag and the chart version/appVersion.
- # prepare:
- # name: Resolve release version
- # runs-on: ubuntu-latest
- # outputs:
- # version: ${{ steps.version.outputs.version }}
- # steps:
- # - name: Resolve version
- # id: version
- # env:
- # TAG: ${{ github.event.release.tag_name }}
- # run: |
- # set -euo pipefail
- # VERSION="${TAG#v}"
- # if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
- # echo "Release tag '$TAG' is not a semver vX.Y.Z tag" >&2
- # exit 1
- # fi
- # echo "Releasing version $VERSION"
- # echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
- # Build and push the server image (API + UI) via the shared reusable workflow.
- build:
- name: Build and push server image
- uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main
- permissions:
- id-token: write
- contents: read
- with:
- artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
- artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}
- image_artifact_name: trueforge
- image_tag: ${{ github.sha }}
- image_context: .
- dockerfile_path: Dockerfile
- platforms: linux/amd64
- # The chart pulls the server image from JFrog (values.yaml image.repository),
- # so JFrog is the only publish target; public ECR stays off.
- enable_jfrog: true
- enable_public_ecr: false
- secrets:
- artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
- artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
-
- # Stamp the commit SHA into the chart, then package and publish it.
- release-chart:
- name: Package and publish Helm chart
- needs: [build]
- runs-on: ubuntu-latest
- env:
- # Helm requires SemVer for Chart.yaml version; prerelease form keeps the
- # commit SHA while remaining packageable. Image tag stays the raw SHA.
- VERSION: 0.0.0-${{ github.sha }}
- IMAGE_TAG: ${{ github.sha }}
- CHART_DIR: charts/trueforge
- HELM_REGISTRY_URL: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}
- HELM_REGISTRY_USERNAME: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}
- HELM_REGISTRY_PASSWORD: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}
- HELM_CHART_REPOSITORY: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY }}
- steps:
- - name: Check out release commit
- uses: actions/checkout@v4
-
- - name: Install yq
- run: |
- sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq
- sudo chmod +x /usr/bin/yq
-
- - name: Install Helm
- uses: azure/setup-helm@v4
- with:
- version: v3.16.4
-
- - name: Stamp version into chart
- run: |
- set -euo pipefail
- yq -i '.version = strenv(VERSION) | .appVersion = strenv(IMAGE_TAG)' "$CHART_DIR/Chart.yaml"
- yq -i '.image.tag = strenv(IMAGE_TAG)' "$CHART_DIR/values.yaml"
- echo "Stamped chart version=$VERSION image.tag=$IMAGE_TAG"
-
- - name: Helm registry login
- run: |
- helm registry login -u "$HELM_REGISTRY_USERNAME" -p "$HELM_REGISTRY_PASSWORD" "$HELM_REGISTRY_URL"
-
- # Fetch the postgresql/redis subcharts from the public Bitnami OCI archive,
- # pinned by Chart.lock. The archive is public (no auth); the images those
- # subcharts run are separately mirrored to JFrog via values.yaml.
- - name: Build chart dependencies
- run: helm dependency build "$CHART_DIR"
-
- - name: Package and push chart
- run: |
- set -euo pipefail
- CHART_NAME=$(yq -r '.name' "$CHART_DIR/Chart.yaml")
- helm package "$CHART_DIR" --destination dist
- PACKAGE="dist/${CHART_NAME}-${VERSION}.tgz"
- echo "Pushing $PACKAGE to oci://$HELM_CHART_REPOSITORY"
- helm push "$PACKAGE" "oci://$HELM_CHART_REPOSITORY"
-
- - name: Print image URI
- env:
- IMAGE_URI: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}/trueforge:${{ github.sha }}
- run: |
- set -euo pipefail
- echo "Pushed image URI: $IMAGE_URI"
- echo "### Server image" >> "$GITHUB_STEP_SUMMARY"
- echo "\`$IMAGE_URI\`" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index bd075f76c..890bd68bb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -142,6 +142,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
+ actions: write
contents: write
id-token: write
steps:
@@ -163,6 +164,7 @@ jobs:
- run: pnpm install --frozen-lockfile
- name: Publish packages
+ id: publish
uses: changesets/action/publish@v2
with:
pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
@@ -170,3 +172,48 @@ jobs:
# TODO(oss): set NPM_CONFIG_PROVENANCE once the repo is public. Do NOT
# set it now: provenance publicly attests the source repo and commit.
# publishConfig.provenance is false on every public package.
+
+ - name: Detect @truefoundry/trueforge publish
+ id: trueforge
+ env:
+ PUBLISHED: ${{ steps.publish.outputs.published }}
+ PACKAGES_KEBAB: ${{ steps.publish.outputs['published-packages'] }}
+ PACKAGES_CAMEL: ${{ steps.publish.outputs.publishedPackages }}
+ run: |
+ set -euo pipefail
+ if [[ "${PUBLISHED:-}" != "true" ]]; then
+ echo "published=false" >> "$GITHUB_OUTPUT"
+ echo "version=" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ PACKAGES="${PACKAGES_KEBAB:-${PACKAGES_CAMEL:-[]}}"
+ VERSION=$(printf '%s' "$PACKAGES" | python3 -c '
+ import json,sys
+ pkgs=json.load(sys.stdin)
+ for p in pkgs:
+ if p.get("name")=="@truefoundry/trueforge":
+ print(p["version"])
+ break
+ ')
+ if [[ -n "$VERSION" ]]; then
+ echo "published=true" >> "$GITHUB_OUTPUT"
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ echo "Published @truefoundry/trueforge@$VERSION"
+ else
+ echo "published=false" >> "$GITHUB_OUTPUT"
+ echo "version=" >> "$GITHUB_OUTPUT"
+ echo "@truefoundry/trueforge was not in this publish set"
+ fi
+
+ - name: Start prod image release
+ if: steps.trueforge.outputs.published == 'true'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ VERSION: ${{ steps.trueforge.outputs.version }}
+ run: |
+ # Pin to this publish commit so a newer main push cannot change the
+ # Dockerfile / shortSha used for the prod image tag.
+ gh workflow run build-and-prepare-chart-release.yml \
+ --ref "$GITHUB_SHA" \
+ -f app_version="$VERSION" \
+ -f update_app_version=true
diff --git a/Dockerfile b/Dockerfile
index 9879b80ef..f7a541b4d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,102 +1,27 @@
# syntax=docker/dockerfile:1
#
-# Multi-stage build for @truefoundry/trueforge, which also serves the UI: the only image the stack needs.
+# Production image: installs published @truefoundry/trueforge from npm.
+# The app bits match the npm package exactly (not floating monorepo source).
#
-# Lives at the repository root because the build needs the whole pnpm workspace
-# as its context: the server depends on the workspace package @truefoundry/trueforge-core.
+# Required build-arg:
+# APP_VERSION — npm version to install, e.g. 0.1.0
#
-# Dependency install uses pnpm fetch (lockfile-only) then install --offline so
-# the download layer stays cached when only package.json / scripts change.
-# See https://pnpm.io/cli/fetch
+# Example:
+# docker build --build-arg APP_VERSION=0.1.0 -t trueforge:0.1.0 .
-FROM node:24-slim AS base
-ENV PNPM_HOME=/pnpm
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable && pnpm config set store-dir /pnpm/store
+FROM node:24-slim AS runner
WORKDIR /app
-
-# Native dependencies (for example better-sqlite3) compile in build stages.
-FROM base AS build-base
-RUN apt-get update \
- && apt-get install -y --no-install-recommends g++ make python3 \
- && rm -rf /var/lib/apt/lists/*
-
-# ---------------------------------------------------------------------------
-# store: the pnpm store, from the lockfile only (stable when manifests churn).
-# ---------------------------------------------------------------------------
-FROM build-base AS store
-COPY pnpm-lock.yaml pnpm-workspace.yaml ./
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch
-
-# ---------------------------------------------------------------------------
-# workspace: install inputs shared by every stage below — the manifests plus the
-# sources the root postinstall hook (build:gen) inlines.
-# ---------------------------------------------------------------------------
-FROM store AS workspace
-COPY package.json .npmrc tsconfig.base.json ./
-COPY packages/trueforge-core/package.json packages/trueforge-core/package.json
-COPY packages/trueforge/package.json packages/trueforge/package.json
-COPY packages/trueforge-sdk/package.json packages/trueforge-sdk/package.json
-COPY packages/frontend/package.json packages/frontend/package.json
-COPY packages/trueforge-ui/package.json packages/trueforge-ui/package.json
-COPY packages/trueforge-core/scripts packages/trueforge-core/scripts
-COPY packages/trueforge-core/src/core/sandbox/scripts packages/trueforge-core/src/core/sandbox/scripts
-
-# ---------------------------------------------------------------------------
-# builder: install all deps (incl. dev) and build trueforge-core + server.
-# ---------------------------------------------------------------------------
-FROM workspace AS builder
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
- pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...
-COPY packages/trueforge-core packages/trueforge-core
-COPY packages/trueforge packages/trueforge
-RUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundry/trueforge build
-
-# ---------------------------------------------------------------------------
-# frontend-builder: build the UI the server serves (parallel to builder above).
-# ---------------------------------------------------------------------------
-FROM workspace AS frontend-builder
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
- pnpm install --frozen-lockfile --offline --filter frontend...
-COPY packages/trueforge-sdk packages/trueforge-sdk
-RUN pnpm --filter @truefoundry/trueforge-sdk build
-COPY packages/trueforge-ui packages/trueforge-ui
-RUN pnpm --filter @truefoundry/trueforge-ui build
-COPY packages/frontend packages/frontend
-RUN pnpm --filter frontend build
-
-# ---------------------------------------------------------------------------
-# prod-deps: production dependency tree (no dev tooling), resolved offline.
-# ---------------------------------------------------------------------------
-FROM workspace AS prod-deps
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
- pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...
-
-# ---------------------------------------------------------------------------
-# runner: minimal image with prod node_modules + built artifacts.
-# ---------------------------------------------------------------------------
-FROM base AS runner
ENV NODE_ENV=production
+ENV STANDALONE=false
-# Production dependency tree (pnpm workspace symlinks preserved).
-COPY --from=prod-deps /app/node_modules ./node_modules
-COPY --from=prod-deps /app/packages/trueforge-core/node_modules ./packages/trueforge-core/node_modules
-COPY --from=prod-deps /app/packages/trueforge/node_modules ./packages/trueforge/node_modules
-
-# Built workspace dependency (@truefoundry/trueforge-core).
-COPY --from=builder /app/packages/trueforge-core/package.json ./packages/trueforge-core/package.json
-COPY --from=builder /app/packages/trueforge-core/dist ./packages/trueforge-core/dist
-
-# Built server (JS). UI is copied below from the parallel frontend stage into
-# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.
-COPY --from=builder /app/packages/trueforge/package.json ./packages/trueforge/package.json
-COPY --from=builder /app/packages/trueforge/dist ./packages/trueforge/dist
-# Frontend builds in a parallel stage; place it at the same path as the npm tarball.
-COPY --from=frontend-builder /app/packages/frontend/dist ./packages/trueforge/dist/_frontend
+ARG APP_VERSION
+RUN test -n "$APP_VERSION" || (echo "APP_VERSION build-arg is required" >&2 && exit 1)
-WORKDIR /app/packages/trueforge
+# Fail closed if the version is not on the registry (no workspace fallback).
+RUN npm install --omit=dev "@truefoundry/trueforge@${APP_VERSION}" \
+ && npm cache clean --force
EXPOSE 8790
-# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.
-CMD ["node", "dist/main.js"]
+# Same entry as the from-source image / `pnpm start` (launch-only; dist is in the package).
+CMD ["node", "node_modules/@truefoundry/trueforge/dist/main.js"]
diff --git a/Dockerfile.dev b/Dockerfile.dev
new file mode 100644
index 000000000..12744eb8b
--- /dev/null
+++ b/Dockerfile.dev
@@ -0,0 +1,97 @@
+# syntax=docker/dockerfile:1
+#
+# From-source multi-stage build for local smoke / floating-main / SHA-tagged
+# dev images. Production/OSS Helm images use the root Dockerfile (npm install).
+#
+# Lives at the repository root because the build needs the whole pnpm workspace
+# as its context: the server depends on the workspace package @truefoundry/trueforge-core.
+#
+# Dependency install uses pnpm fetch (lockfile-only) then install --offline so
+# the download layer stays cached when only package.json / scripts change.
+# See https://pnpm.io/cli/fetch
+
+FROM node:24-slim AS base
+ENV PNPM_HOME=/pnpm
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable && pnpm config set store-dir /pnpm/store
+WORKDIR /app
+
+# ---------------------------------------------------------------------------
+# store: the pnpm store, from the lockfile only (stable when manifests churn).
+# ---------------------------------------------------------------------------
+FROM base AS store
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch
+
+# ---------------------------------------------------------------------------
+# workspace: install inputs shared by every stage below — the manifests plus the
+# sources the root postinstall hook (build:gen) inlines.
+# ---------------------------------------------------------------------------
+FROM store AS workspace
+COPY package.json .npmrc tsconfig.base.json ./
+COPY packages/trueforge-core/package.json packages/trueforge-core/package.json
+COPY packages/trueforge/package.json packages/trueforge/package.json
+COPY packages/trueforge-sdk/package.json packages/trueforge-sdk/package.json
+COPY packages/frontend/package.json packages/frontend/package.json
+COPY packages/trueforge-ui/package.json packages/trueforge-ui/package.json
+COPY packages/trueforge-core/scripts packages/trueforge-core/scripts
+COPY packages/trueforge-core/src/core/sandbox/scripts packages/trueforge-core/src/core/sandbox/scripts
+
+# ---------------------------------------------------------------------------
+# builder: install all deps (incl. dev) and build trueforge-core + server.
+# ---------------------------------------------------------------------------
+FROM workspace AS builder
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+ pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...
+COPY packages/trueforge-core packages/trueforge-core
+COPY packages/trueforge packages/trueforge
+RUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundry/trueforge build
+
+# ---------------------------------------------------------------------------
+# frontend-builder: build the UI the server serves (parallel to builder above).
+# ---------------------------------------------------------------------------
+FROM workspace AS frontend-builder
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+ pnpm install --frozen-lockfile --offline --filter frontend...
+COPY packages/trueforge-sdk packages/trueforge-sdk
+RUN pnpm --filter @truefoundry/trueforge-sdk build
+COPY packages/trueforge-ui packages/trueforge-ui
+RUN pnpm --filter @truefoundry/trueforge-ui build
+COPY packages/frontend packages/frontend
+RUN pnpm --filter frontend build
+
+# ---------------------------------------------------------------------------
+# prod-deps: production dependency tree (no dev tooling), resolved offline.
+# ---------------------------------------------------------------------------
+FROM workspace AS prod-deps
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
+ pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...
+
+# ---------------------------------------------------------------------------
+# runner: minimal image with prod node_modules + built artifacts.
+# ---------------------------------------------------------------------------
+FROM base AS runner
+ENV NODE_ENV=production
+
+# Production dependency tree (pnpm workspace symlinks preserved).
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=prod-deps /app/packages/trueforge-core/node_modules ./packages/trueforge-core/node_modules
+COPY --from=prod-deps /app/packages/trueforge/node_modules ./packages/trueforge/node_modules
+
+# Built workspace dependency (@truefoundry/trueforge-core).
+COPY --from=builder /app/packages/trueforge-core/package.json ./packages/trueforge-core/package.json
+COPY --from=builder /app/packages/trueforge-core/dist ./packages/trueforge-core/dist
+
+# Built server (JS). UI is copied below from the parallel frontend stage into
+# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.
+COPY --from=builder /app/packages/trueforge/package.json ./packages/trueforge/package.json
+COPY --from=builder /app/packages/trueforge/dist ./packages/trueforge/dist
+# Frontend builds in a parallel stage; place it at the same path as the npm tarball.
+COPY --from=frontend-builder /app/packages/frontend/dist ./packages/trueforge/dist/_frontend
+
+WORKDIR /app/packages/trueforge
+
+EXPOSE 8790
+
+# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.
+CMD ["node", "dist/main.js"]
diff --git a/README.md b/README.md
index 8f955b9a0..6f0b3d91e 100644
--- a/README.md
+++ b/README.md
@@ -10,38 +10,18 @@
<p align="center">The open-source agent harness - the runtime layer that turns an LLM into a working agent</p>
<p align="center">
- <a href="https://github.com/truefoundry/trueforge/blob/main/LICENSE">
- <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
- </a>
- <a href="https://nodejs.org">
- <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg" alt="Node.js >= 22.13">
- </a>
- <a href="https://trueforge.dev">
- <img src="https://img.shields.io/badge/Documentation-trueforge.dev-blue.svg" alt="Documentation">
- </a>
- <a href="https://trueforge.dev/quickstart">
- <img src="https://img.shields.io/badge/Quickstart-trueforge.dev/quickstart-blue.svg" alt="Quickstart">
- </a>
- <a href="https://trueforge.dev/api/overview">
- <img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg" alt="SDK">
- </a>
+ <a href="https://github.com/truefoundry/trueforge/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg?style=flat-square" alt="Node.js >= 22.13"></a>
+ <a href="https://trueforge.dev"><img src="https://img.shields.io/badge/Documentation-trueforge.dev-blue.svg?style=flat-square" alt="Documentation"></a>
+ <a href="https://trueforge.dev/quickstart"><img src="https://img.shields.io/badge/Quickstart-trueforge.dev/quickstart-blue.svg?style=flat-square" alt="Quickstart"></a>
+ <a href="https://trueforge.dev/api/overview"><img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg?style=flat-square" alt="SDK"></a>
</p>
<p align="center">
- <a href="https://www.npmjs.com/package/@truefoundry/trueforge">
- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge" alt="npm @truefoundry/trueforge">
- </a>
- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk">
- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk" alt="npm @truefoundry/trueforge-sdk">
- </a>
- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui">
- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui" alt="npm @truefoundry/trueforge-ui">
- </a>
- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core">
- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core" alt="npm @truefoundry/trueforge-core">
- </a>
- <a href="https://deepwiki.com/truefoundry/trueforge">
- <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
- </a>
+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge&style=flat-square" alt="npm @truefoundry/trueforge"></a>
+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk&style=flat-square" alt="npm @truefoundry/trueforge-sdk"></a>
+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui&style=flat-square" alt="npm @truefoundry/trueforge-ui"></a>
+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core&style=flat-square" alt="npm @truefoundry/trueforge-core"></a>
+ <a href="https://deepwiki.com/truefoundry/trueforge"><img src="https://deepwiki.com/badge.svg?style=flat-square" alt="Ask DeepWiki"></a>
</p>
# TrueForge
diff --git a/RELEASING.md b/RELEASING.md
index adad7418c..f0f013a6f 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,152 +1,201 @@
# Releasing
-This repository ships two independent release pipelines:
+This repo ships npm packages, a production container image, a Helm chart, and
+optional from-source **dev** images.
-| What | Trigger | Workflow |
-| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
-| npm packages | Push to `main` (Changesets) | [`.github/workflows/release.yml`](.github/workflows/release.yml) |
-| Server image + Helm chart | Manual `workflow_dispatch` | [`.github/workflows/release-image-and-chart.yml`](.github/workflows/release-image-and-chart.yml) |
+| What | Trigger | Workflow |
+| ----------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| npm packages | Push to `main` (Changesets) | [`release.yml`](.github/workflows/release.yml) |
+| Prod image + chart-release PR | After `@truefoundry/trueforge` npm publish, or manual dispatch | [`build-and-prepare-chart-release.yml`](.github/workflows/build-and-prepare-chart-release.yml) |
+| Chart tag, GitHub Release, OCI push | Merge of `release-chart/trueforge`, or push/dispatch of `charts/trueforge@*` | [`release-chart.yml`](.github/workflows/release-chart.yml) |
+| Dev (from-source) image | Manual `workflow_dispatch` | [`build-dev-image.yml`](.github/workflows/build-dev-image.yml) |
-Publishing npm does not stamp or push the chart. Publishing the image/chart does not publish npm.
+## Versioning
-## Published packages
+| Artifact | Identity |
+| ---------------------------- | ---------------------------------------------------------------------------------- |
+| npm `@truefoundry/trueforge` | SemVer `X.Y.Z` — source of truth for app bits |
+| Chart `appVersion` | A **published** npm version |
+| Prod image | Root [`Dockerfile`](Dockerfile): `npm install @truefoundry/trueforge@$APP_VERSION` |
+| Prod image tag | `{appVersion}-{shortSha}` (shortSha of the build commit) |
+| Chart `version` | Independent SemVer; git tag `charts/[email protected]` must match |
+| Dev image | [`Dockerfile.dev`](Dockerfile.dev); tag = full commit SHA |
-| Package | Source | Notes |
-| ----------------------------- | ------------------------- | --------------------------------------------------------------- |
-| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist", "README.md"]`) |
-| `@truefoundry/trueforge` | `packages/trueforge` | App + CLI; tarball includes embedded UI under `dist/_frontend/` |
-| `@truefoundry/trueforge-sdk` | `packages/trueforge-sdk` | Fern-generated client — do not hand-edit |
-| `@truefoundry/trueforge-ui` | `packages/trueforge-ui` | Embeddable chat UI |
+Install a published chart:
-`packages/frontend` is not published on its own. The server build copies its output into `@truefoundry/trueforge`'s `dist/_frontend/`.
-
-Workspace dependencies use `workspace:*`. On publish, pnpm rewrites them to the exact version in each dependency's `package.json`. `changeset publish` publishes in dependency order, so a package never lands pointing at an unpublished sibling from the same run.
+```bash
+helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge --version <chart-semver>
+```
---
# npm packages
-## Release flow
-
-There is no `v*` git-tag publish. One workflow both versions and publishes, split into least-privilege jobs (`select-mode` → `version` | `pack` → `publish`):
+| Package | Source | Notes |
+| ----------------------------- | ------------------------- | --------------------------------------------- |
+| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library |
+| `@truefoundry/trueforge` | `packages/trueforge` | App + CLI; tarball includes `dist/_frontend/` |
+| `@truefoundry/trueforge-sdk` | `packages/trueforge-sdk` | Fern-generated — do not hand-edit |
+| `@truefoundry/trueforge-ui` | `packages/trueforge-ui` | Embeddable chat UI |
-1. **Add a changeset** in the same PR as the code change:
+`packages/frontend` is not published; its build is copied into `@truefoundry/trueforge`'s tarball.
+`workspace:*` is rewritten to exact versions on publish.
- ```bash
- pnpm changeset
- # non-interactive:
- pnpm change --bump patch --summary "…" @truefoundry/trueforge-core
- ```
+## Flow
- Name only the packages that should bump. A dependency can ship without its dependents. SDK regeneration on a PR already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
+No `v*` tag publish. [`release.yml`](.github/workflows/release.yml) does both version and publish
+(`select-mode` → `version` \| `pack` → `publish`):
-2. **Merge to `main`.** `.github/workflows/release.yml` runs. `changesets/action/select-mode` picks the path. With pending `.changeset/*.md` files, the **version** job opens or updates a **Version Packages** PR (`pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if the SDK version moved). Review bumps and changelogs, then merge.
+1. Add a changeset in the same PR as the code change (`pnpm changeset`, or
+ `pnpm change --bump patch --summary "…" <pkg>`). SDK regen already adds
+ `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
+2. Merge to `main`. Pending changesets → **Version Packages** PR
+ (`pnpm run version`). Review and merge.
+3. With no pending changesets, **pack** (build/test) then **publish** via npm
+ trusted publishing (OIDC; no `NPM_TOKEN`).
+4. If `@truefoundry/trueforge` was published, the publish job dispatches
+ **Build and prepare chart release** at `--ref "$GITHUB_SHA"` (pinned to the
+ publish commit, not floating `main`).
+5. Pin dependents to exact versions during early `0.x`.
-3. **Merge Version Packages to publish.** The same workflow sees no pending changesets: **pack** builds/tests and packs tarballs, then **publish** uploads them. Auth is npm trusted publishing over GitHub OIDC (`id-token` only on the publish job; no `NPM_TOKEN`).
+`workflow_dispatch` on **Release** re-runs the same workflow.
- **Dist-tags:** while `.changeset/pre.json` exists (`pnpm changeset pre enter rc`), publishes use the `rc` tag. After `pnpm changeset pre exit`, the next Version Packages merge publishes to `latest`. Install an RC with `npx @truefoundry/trueforge@rc` or a concrete `x.y.z-rc.N` version.
+## Prerelease mode
-4. **Update downstream pins** that depend on these packages. Prefer exact versions (no `^`) during early `0.x` churn.
+Repo-wide via `.changeset/pre.json` (absent = publish to `latest`):
-`workflow_dispatch` on **Release** re-runs the same workflow (useful after a bot-only commit that did not re-trigger it).
+| Goal | Command | Then |
+| -------- | ----------------------------- | ------------------------------------------------------------------------- |
+| Enter RC | `pnpm changeset pre enter rc` | Commit `pre.json`, merge; versions look like `x.y.z-rc.N` (`rc` dist-tag) |
+| Exit RC | `pnpm changeset pre exit` | Commit the delete, merge; next Version Packages merge publishes `latest` |
-A push to `main` with no pending changesets still publishes any `package.json` version not yet on npm and no-ops the rest.
+`pre enter` / `pre exit` do not bump or publish. Do not mix stable and RC packages in one
+`changeset version`.
-## Prerelease mode
+## Trusted publishing
-Pre mode is repo-wide (`.changeset/pre.json`), not per-package. The repo is currently in `rc`.
+Each public package must list this repo + workflow as a trusted publisher on npmjs.com:
-| Goal | Command | Then |
-| -------------------- | ----------------------------- | ------------------------------------------------------------------------- |
-| Stay on RCs | (already in pre) | Normal PRs + Version Packages. Versions look like `x.y.z-rc.N`. |
-| Ship stable `latest` | `pnpm changeset pre exit` | Commit the deleted `pre.json`, merge, then merge the Version Packages PR. |
-| Start a new RC line | `pnpm changeset pre enter rc` | Commit `pre.json`, merge, continue as above. |
+- Repository: `truefoundry/trueforge`
+- Workflow: `release.yml` (exact filename)
+- No GitHub Environment name
-`pre enter` / `pre exit` do not bump versions or publish. The Version Packages PR versions; merging it publishes.
+Do not set `NPM_TOKEN` / `_authToken` on the publish job — that disables OIDC.
+Only the **publish** job has `id-token: write`.
-Do not mix stable and RC packages in one `changeset version` — exit pre only when the next publish should be GA.
+## Local without publishing
-## Package layout (`@truefoundry/trueforge-core`)
+```bash
+pnpm clean && pnpm build && pnpm standalone:start
+# or: pnpm pack inside packages/trueforge-core / packages/trueforge
+```
-Packages publish from their package root. The core build emits CJS (`.js`), ESM (`.mjs`), and `.d.ts` under `dist/`; `package.json` `exports` point at those paths and `files: ["dist", "README.md"]` keeps `src/` out of the tarball.
+## Troubleshooting
-- Deep imports such as `@truefoundry/trueforge-core/core/llm/LLMTypes` resolve via the package `exports` map for modern `moduleResolution` modes (`bundler`, `node16`, `nodenext`).
-- Curated barrels (`.`, `./core`, `./agent-session`) are the supported public API; deep imports are an escape hatch.
-- A custom `"trueforge-dev"` export condition points at `./src` for dist-free monorepo development only. `src/` is not in the tarball, and the condition is not named `"development"`, so external tooling will not activate it accidentally.
+- **No Version Packages PR** — no `.changeset/*.md` on `main`. Add one, or re-run **Release**.
+- **Publish wants a tag** — RCs need the `rc` dist-tag (set automatically while `pre.json` exists).
+- **403** — version already on npm, or trusted-publisher config mismatch.
+- **OIDC fail** — pnpm >= 11.0.7; remove registry `_authToken`.
+- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` first.
+- **SDK not regenerated on Version PR** — only when `@truefoundry/trueforge-sdk` version moved
+ (`scripts/version.mjs`; needs Docker).
-Sourcemaps / declaration maps are currently enabled in the published tarball.
+---
-## Why dependents pin exact versions
+# Image and Helm chart
-On publish, `workspace:*` becomes the **exact version** in the dependency's `package.json`. If that version is missing from npm, consumers fail at install/runtime. Changeset both packages together when a dependent needs new APIs from its dependency.
+```text
+npm publish @truefoundry/[email protected]
+ → dispatch build-and-prepare-chart-release @ publish SHA
+ → build Dockerfile (APP_VERSION=X.Y.Z) → push X.Y.Z-<shortSha>
+ → open/update PR on branch release-chart/trueforge
+ → merge PR → tag + GH Release + OCI push (release-chart.yml)
-## Local iteration without publishing
+manual rebuild (same or other app version)
+ → workflow_dispatch build-and-prepare-chart-release
+ → same PR path
-```bash
-pnpm clean && pnpm build && pnpm standalone:start
-# or pack only:
-cd packages/trueforge-core && pnpm build && pnpm pack
-cd packages/trueforge && pnpm pack
+chart-only
+ → human PR bumps Chart.yaml version
+ → human tags charts/[email protected] (or gh release create)
+ → release-chart.yml publishes OCI (no image rebuild)
```
-Point consumers at a tarball with a `file:` dependency (or `yalc`) until a real version is published.
+## Dockerfiles
-## npm trusted publishing
+| File | Role |
+| ---------------------------------- | --------------------------------------------------------------------------------------- |
+| [`Dockerfile`](Dockerfile) | Prod/OSS. `ARG APP_VERSION` → `npm install @truefoundry/trueforge@$APP_VERSION` |
+| [`Dockerfile.dev`](Dockerfile.dev) | From-source. Used by [`docker-compose.yml`](docker-compose.yml) and **Build dev image** |
-Each of the four packages must list this repository and workflow as a trusted publisher on npmjs.com:
+Prod fails if that npm version is missing (no workspace fallback), so `appVersion` stays honest
+even when `main` has moved on.
-- Repository: `truefoundry/trueforge`
-- Workflow filename: `release.yml` (must match exactly)
-- No GitHub Environment name (the publish job does not use one)
+## Build and prepare chart release
-Configure the trusted-publisher row **before** the first publish for a new package. Do not set `NPM_TOKEN` or an `_authToken` in `.npmrc` on the publish job — that disables the OIDC exchange. Only the **publish** job has `id-token: write`.
+[`build-and-prepare-chart-release.yml`](.github/workflows/build-and-prepare-chart-release.yml)
+(`workflow_dispatch`):
-## Troubleshooting
+| Input | Default | Meaning |
+| -------------------- | ------------------------- | -------------------------------------------------------------------- |
+| `app_version` | `Chart.yaml` `appVersion` | npm version to install into the image |
+| `update_app_version` | `false` | Also write that version into `Chart.yaml` `appVersion` on the bot PR |
-- **Version Packages PR never appears** — no `.changeset/*.md` on `main` (only `config.json` / `README.md` / `pre.json` remain). Add a changeset and merge, or run **Release** via `workflow_dispatch`.
-- **Publish fails requiring a tag** — prerelease versions need the `rc` dist-tag. `changeset publish` sets that while pre mode is on; for a local publish use `pnpm publish --tag rc`.
-- **Publish fails with 403/E403** — version already published (npm versions are immutable), or the trusted publisher config does not match the workflow filename/repo exactly.
-- **OIDC/auth error** — requires pnpm >= 11.0.7 (native OIDC; `pnpm/action-setup@v4` reads `packageManager` from the root) and a matching trusted publisher config. Remove any registry `_authToken`.
-- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the pack job fails closed if the copy is absent.
-- **Version PR did not regenerate the SDK** — `scripts/version.mjs` only runs `pnpm sdk:generate` when `@truefoundry/trueforge-sdk`'s version changed. That step needs Docker (available on `ubuntu-latest`).
+Always: build/push `{appVersion}-{shortSha}`, patch-bump chart `version`, set `image.tag`,
+open/update one PR on `release-chart/trueforge`.
----
+```bash
+gh workflow run build-and-prepare-chart-release.yml
+gh workflow run build-and-prepare-chart-release.yml -f app_version=0.1.0
+# after npm publish of a new app version:
+gh workflow run build-and-prepare-chart-release.yml \
+ -f app_version=0.1.0 -f update_app_version=true
+```
-# Server image and Helm chart
+You may edit chart SemVer (minor/major) on the PR before merging; the tag follows
+`Chart.yaml` `version` at merge time. Each run rebuilds the `release-chart/trueforge` branch
+from `main`, but a chart `version` on the branch that outranks the patch bump is carried over,
+so a manual bump survives later image rebuilds. Other manual edits on that branch do not —
+commit them to `main` instead.
-A separate pipeline ships the deployable artifacts: the server container image (API + UI, built from the root `Dockerfile`) and the `charts/trueforge` Helm chart. It is driven by `.github/workflows/release-image-and-chart.yml` and runs only on manual **`workflow_dispatch`** (Actions → **Release image and Helm chart** → Run workflow).
+## Publish Helm chart
-Install a published chart with:
+[`release-chart.yml`](.github/workflows/release-chart.yml) is one job with three entry points:
-```bash
-helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
- --version <x.y.z>
-```
-
-## What the workflow does
+| Trigger | What it does |
+| --------------------------------------------------------- | ------------------------------------------------------------------- |
+| Merged PR from `release-chart/trueforge` (same repo only) | Create `charts/trueforge@<version>` + GitHub Release, then OCI push |
+| Push of tag `charts/trueforge@*` | OCI push only (tag already exists) |
+| `workflow_dispatch` with `tag=` | OCI push for an existing tag (retry) |
-The dispatch commit SHA is the image tag. The workflow:
+Only the `release-chart/trueforge` branch auto-tags. Ordinary merges never create chart tags.
-1. **Builds and pushes the image** via `truefoundry/github-workflows-public/.github/workflows/build.yml@main` to the public JFrog Artifactory repository, tagged with `github.sha`.
-2. **Stamps the chart in the runner workspace** — sets `Chart.yaml` `version` to `0.0.0-<sha>` (Helm SemVer-compatible prerelease), and `appVersion` / `image.tag` to the raw SHA. Those stamps are **not** committed back to `main`.
-3. **Publishes the chart** — packages `charts/trueforge` and pushes it to the JFrog public OCI Helm repository (`oci://tfy.jfrog.io/tfy-helm`). It does not attach artifacts to a GitHub Release.
+Chart-only example:
-## Per-release flow
+```bash
+# after merging a PR that bumped Chart.yaml version:
+git tag charts/[email protected]
+git push origin charts/[email protected]
+```
-1. On the commit you want to ship, run the workflow from the Actions tab (or `gh workflow run release-image-and-chart.yml`).
-2. Watch the run. The image and chart land in JFrog; the job summary prints the image URI.
+## Dev / floating main
-## Required repository configuration
+External deploy repo owns `truefoundry.yaml` (`git-helm-repo` @ `main`). Build a from-source image:
-**Variables:** `TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY`.
+```bash
+gh workflow run build-dev-image.yml --ref main
+# → tfy.jfrog.io/tfy-images/trueforge:<fullSha>
+```
-**Secrets:** `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD`.
+Patch that SHA into `image.tag`. Secrets via `secretKeyRef` only — never plaintext in git.
+Do not use SHA-tagged images as production chart defaults.
## Bundled chart dependencies
-The chart optionally bundles Postgres and Redis (Bitnami subcharts from `oci://registry-1.docker.io/bitnamicharts`, pinned by `Chart.lock`). The workflow runs `helm dependency build` before packaging. Disable them with `postgresql.enabled=false` / `redis.enabled=false` to use external services.
+Optional Postgres/Redis Bitnami subcharts (`Chart.lock`). Publish runs `helm dependency build`.
+Disable with `postgresql.enabled=false` / `redis.enabled=false`.
-Bitnami left the charts public but moved versioned container images to `docker.io/bitnamilegacy`. `charts/trueforge/values.yaml` points the subcharts at pinned tags mirrored on JFrog and sets `global.security.allowInsecureImages: true`. Mirror once per pinned tag:
+Subchart **images** are mirrored on JFrog (`values.yaml`). Mirror once per pin:
```bash
for img in \
@@ -154,18 +203,15 @@ for img in \
redis:8.2.1-debian-12-r0; do
crane copy "docker.io/bitnamilegacy/${img}" "tfy.jfrog.io/tfy-mirror/bitnamilegacy/${img}"
done
-# If you enable metrics/volumePermissions, also mirror:
-# postgres-exporter:0.17.1-debian-12-r16 os-shell:12-debian-12-r51
-# redis-exporter:1.76.0-debian-12-r0
```
-To bump a bundled version: change `dependencies:` in `Chart.yaml`, run `pnpm chart:deps`, update the matching `image.tag` in `values.yaml`, and mirror the new legacy tag to JFrog.
+To bump: edit `Chart.yaml` deps → `pnpm chart:deps` → update `values.yaml` image tags → mirror.
-## Validating the chart locally
+## Validate chart locally
```bash
-pnpm chart:deps # helm dependency build (uses Chart.lock)
-pnpm chart:lint # helm lint with charts/trueforge/ci/lint-values.yaml
-pnpm chart:template # render manifests
-pnpm chart:package # package to dist/ (gitignored)
+pnpm chart:deps
+pnpm chart:lint
+pnpm chart:template
+pnpm chart:package
```
diff --git a/charts/trueforge/Chart.yaml b/charts/trueforge/Chart.yaml
index 4fc8273d0..df823cfca 100644
--- a/charts/trueforge/Chart.yaml
+++ b/charts/trueforge/Chart.yaml
@@ -2,9 +2,8 @@ apiVersion: v2
name: trueforge
description: TrueForge server (API + UI) served from a single container image.
type: application
-# version (chart) and appVersion are stamped at publish time by
-# .github/workflows/release-image-and-chart.yml (workflow_dispatch, commit SHA);
-# committed values are placeholders until that workflow runs.
+# version / appVersion are maintained on main (bot chart-release PR or human).
+# Publishing is gated by git tag charts/trueforge@<version> (must match version).
version: 0.0.1
appVersion: "0.0.1"
kubeVersion: ">=1.25.0-0"
diff --git a/charts/trueforge/README.md b/charts/trueforge/README.md
index 969487bed..407a675ad 100644
--- a/charts/trueforge/README.md
+++ b/charts/trueforge/README.md
@@ -1,15 +1,17 @@
# trueforge Helm chart
Deploys the TrueForge server, a single container image that serves both the API
-and the UI (built from the repository-root `Dockerfile`).
+and the UI. **Production** images install `@truefoundry/trueforge` from npm
+(repository-root [`Dockerfile`](../../Dockerfile) with `APP_VERSION`).
+**Local smoke / from-source** builds use [`Dockerfile.dev`](../../Dockerfile.dev)
+(see [`docker-compose.yml`](../../docker-compose.yml)).
The chart always runs the server in **distributed** mode (`STANDALONE=false`) against
Postgres and Redis.
-The chart version, `appVersion`, and `image.tag` are stamped at publish time by
-[`.github/workflows/release-image-and-chart.yml`](../../.github/workflows/release-image-and-chart.yml)
-(manual `workflow_dispatch`, commit SHA as the image tag). Committed chart
-values are placeholders until that workflow runs.
+Chart `version` / `appVersion` / `image.tag` are maintained on `main` (chart-release
+bot PR or human). Publishing is gated by git tag `charts/trueforge@<version>`.
+See [`RELEASING.md`](../../RELEASING.md).
## Dev defaults (read before exposing)
diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yaml
index f39fc4faa..13a5462d4 100644
--- a/charts/trueforge/values.yaml
+++ b/charts/trueforge/values.yaml
@@ -4,8 +4,8 @@ replicaCount: 1
image:
repository: tfy.jfrog.io/tfy-images/trueforge
- # Tag defaults to the chart appVersion when empty; the release workflow stamps
- # the released version here.
+ # Tag defaults to chart appVersion when empty. Prod chart-release PRs set this
+ # to {appVersion}-{shortSha} for the npm-install image already in the registry.
tag: ""
pullPolicy: IfNotPresent
diff --git a/docker-compose.yml b/docker-compose.yml
index e661b65fa..4033f7a66 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -39,6 +39,8 @@ services:
server:
build:
context: .
+ # From-source image; root Dockerfile is the npm-install prod recipe.
+ dockerfile: Dockerfile.dev
image: truefoundry-server:latest
ports:
# Host 8791 avoids conflict with host `pnpm dev` on 8790.