From d269d35a2c581c8a1ba2edbdcb3e4def27c7e0ab Mon Sep 17 00:00:00 2001 From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com> Date: Tue, 10 Nov 2026 21:04:08 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=B3=20feat:=20Publish=20Release-Matche?= =?UTF-8?q?d=20Channel=20Gateway=20Images=20(#17784)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: publish release-matched channel gateway images * test: isolate compose configuration from service env files * test: render channel compose in a complete isolated fixture * fix: publish stable images from their release commit * fix: omit gateway builds from releases predating channels --- .env.example | 4 ++ .github/scripts/test-channel-compose.mjs | 73 +++++++++++++++++++ .github/scripts/test-channel-release.mjs | 86 +++++++++++++++++++++++ .github/workflows/channel-gateway.yml | 18 +++++ .github/workflows/main-image-workflow.yml | 23 +++--- .github/workflows/tag-images.yml | 3 +- docker-compose.channels-build.yml | 14 ++++ docker-compose.channels.yml | 11 +-- 8 files changed, 213 insertions(+), 19 deletions(-) create mode 100644 .github/scripts/test-channel-compose.mjs create mode 100644 .github/scripts/test-channel-release.mjs create mode 100644 docker-compose.channels-build.yml diff --git a/.env.example b/.env.example index 9037dbd890..dd93a424d8 100644 --- a/.env.example +++ b/.env.example @@ -1565,3 +1565,7 @@ OPENWEATHER_API_KEY= # Circuit breaker: max backoff cap (ms) for exponential backoff # MCP_CB_MAX_BACKOFF_MS=300000 + +# Optional Channels Compose overlay: pin the application and gateway to the same +# published release (including -rcN). Omit for the latest stable release. +# LIBRECHAT_IMAGE_TAG=vX.Y.Z-rcN diff --git a/.github/scripts/test-channel-compose.mjs b/.github/scripts/test-channel-compose.mjs new file mode 100644 index 0000000000..c5d54b032f --- /dev/null +++ b/.github/scripts/test-channel-compose.mjs @@ -0,0 +1,73 @@ +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import { copyFileSync, mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = fileURLToPath(new URL('../..', import.meta.url)); +const fixture = mkdtempSync(join(tmpdir(), 'channel-compose-')); +for (const file of [ + 'docker-compose.yml', + 'docker-compose.channels.yml', + 'docker-compose.channels-build.yml', + 'docker-compose.mongo-replica.yml', + '.env.example', +]) { + copyFileSync(join(root, file), join(fixture, file)); +} +copyFileSync(join(root, '.env.example'), join(fixture, '.env')); +process.on('exit', () => rmSync(fixture, { recursive: true, force: true })); + +function configuration(tag, source = false) { + const files = ['docker-compose.yml', 'docker-compose.channels.yml']; + if (source) { + files.push('docker-compose.channels-build.yml'); + } + files.push('docker-compose.mongo-replica.yml'); + return JSON.parse( + execFileSync( + 'docker', + [ + 'compose', + '--env-file', + '.env.example', + ...files.flatMap((file) => ['-f', file]), + '--profile', + 'channels', + 'config', + '--format', + 'json', + ], + { + cwd: fixture, + encoding: 'utf8', + env: { ...process.env, UID: '1000', GID: '1000', LIBRECHAT_IMAGE_TAG: tag }, + }, + ), + ).services; +} + +for (const tag of ['', 'v1.2.3-rc1', 'v1.2.3']) { + const services = configuration(tag); + assert.equal(services.api.image, `ghcr.io/librechat-ai/librechat:${tag || 'latest'}`); + assert.equal( + services['channel-gateway'].image, + `ghcr.io/librechat-ai/librechat-channel-gateway:${tag || 'latest'}`, + ); + assert.equal(services.api.build, undefined); + assert.equal(services['channel-gateway'].build, undefined); + assert.equal(services.api.depends_on['mongodb-init'].condition, 'service_completed_successfully'); + assert.equal(services['channel-gateway'].depends_on.api.condition, 'service_healthy'); + assert.deepEqual(services['channel-gateway'].profiles, ['channels']); + assert.equal(services['channel-gateway'].ports, undefined); +} + +const source = configuration('v1.2.3-rc1', true); +assert.equal(source.api.image, 'librechat-channels-api:local'); +assert.equal(source.api.build.dockerfile, 'Dockerfile'); +assert.equal(source['channel-gateway'].image, 'librechat-channel-gateway:local'); +assert.equal(source['channel-gateway'].build.dockerfile, 'packages/channel-gateway/Dockerfile'); +assert.equal(source.api.pull_policy, 'build'); +assert.equal(source['channel-gateway'].pull_policy, 'build'); +console.log('PASS: release tags match, releases need no build, source builds remain explicit'); diff --git a/.github/scripts/test-channel-release.mjs b/.github/scripts/test-channel-release.mjs new file mode 100644 index 0000000000..d233a6b40f --- /dev/null +++ b/.github/scripts/test-channel-release.mjs @@ -0,0 +1,86 @@ +import assert from 'node:assert/strict'; +import { execFileSync } from 'node:child_process'; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import yaml from 'js-yaml'; + +const readWorkflow = (file) => + yaml.load(readFileSync(new URL(`../workflows/${file}`, import.meta.url), 'utf8')); +const manual = readWorkflow('main-image-workflow.yml'); +for (const workflow of [readWorkflow('tag-images.yml')]) { + const images = JSON.parse(workflow.jobs.publish.with.images); + const gateway = images.find((image) => image.image_name === 'librechat-channel-gateway'); + assert.equal(gateway.file, 'packages/channel-gateway/Dockerfile'); + assert.equal(gateway.target, 'runtime'); +} + +const fixture = mkdtempSync(join(tmpdir(), 'channel-release-')); +try { + const git = (...args) => + execFileSync('git', args, { + cwd: fixture, + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + }).trim(); + git('init', '--initial-branch=main'); + git('config', 'user.email', 'fixture@example.com'); + git('config', 'user.name', 'Release fixture'); + git('commit', '--allow-empty', '-m', 'Stable release'); + let release = git('rev-parse', 'HEAD'); + git('tag', 'v1.2.3'); + git('commit', '--allow-empty', '-m', 'Unreleased main changes'); + assert.notEqual(git('rev-parse', 'HEAD'), release); + git('tag', 'v1.3.0-rc1'); + git('remote', 'add', 'origin', fixture); + + const output = join(fixture, 'output'); + const resolve = manual.jobs['resolve-tag'].steps.find((step) => step.id === 'tag'); + function resolveRelease() { + writeFileSync(output, ''); + execFileSync('bash', ['-e', '-c', resolve.run], { + cwd: fixture, + env: { ...process.env, GITHUB_OUTPUT: output }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + return Object.fromEntries( + readFileSync(output, 'utf8') + .trim() + .split('\n') + .map((line) => line.split('=')), + ); + } + const old = resolveRelease(); + assert.equal(old.latest_tag, 'v1.2.3'); + assert.equal(old.sha, release); + assert.equal( + JSON.parse(old.images).length, + 2, + 'old releases must not attempt a missing gateway build', + ); + + mkdirSync(join(fixture, 'packages/channel-gateway'), { recursive: true }); + writeFileSync(join(fixture, 'packages/channel-gateway/Dockerfile'), 'FROM scratch AS runtime\n'); + git('add', '.'); + git('commit', '-m', 'Release with gateway'); + release = git('rev-parse', 'HEAD'); + git('tag', 'v1.2.4'); + git('commit', '--allow-empty', '-m', 'More unreleased main changes'); + const values = resolveRelease(); + assert.equal(values.latest_tag, 'v1.2.4'); + assert.equal(values.sha, release, 'a stable version must not publish unreleased main code'); + const gateway = JSON.parse(values.images).find( + (image) => image.image_name === 'librechat-channel-gateway', + ); + assert.equal(gateway.file, 'packages/channel-gateway/Dockerfile'); + assert.equal(gateway.target, 'runtime'); + assert.equal(manual.jobs.publish.with.images, '${{ needs.resolve-tag.outputs.images }}'); + assert.equal(manual.jobs.publish.with.checkout_ref, '${{ needs.resolve-tag.outputs.sha }}'); + assert.equal( + manual.jobs.publish.with.build_branch, + '${{ needs.resolve-tag.outputs.latest_tag }}', + ); + console.log('PASS: release gateway targets and stable tag provenance with main ahead'); +} finally { + rmSync(fixture, { recursive: true, force: true }); +} diff --git a/.github/workflows/channel-gateway.yml b/.github/workflows/channel-gateway.yml index cd0a2c4855..ead8c7de2f 100644 --- a/.github/workflows/channel-gateway.yml +++ b/.github/workflows/channel-gateway.yml @@ -9,7 +9,14 @@ on: - 'package-lock.json' - 'scripts/typecheck.mts' - '.dockerignore' + - 'docker-compose.yml' - 'docker-compose.channels.yml' + - 'docker-compose.channels-build.yml' + - '.github/scripts/test-channel-compose.mjs' + - '.github/scripts/test-channel-release.mjs' + - '.github/workflows/tag-images.yml' + - '.github/workflows/main-image-workflow.yml' + - '.github/workflows/docker-publish.yml' - 'docker-compose.mongo-replica.yml' - 'utils/docker/init-replica.js' - '.env.example' @@ -23,7 +30,14 @@ on: - 'package-lock.json' - 'scripts/typecheck.mts' - '.dockerignore' + - 'docker-compose.yml' - 'docker-compose.channels.yml' + - 'docker-compose.channels-build.yml' + - '.github/scripts/test-channel-compose.mjs' + - '.github/scripts/test-channel-release.mjs' + - '.github/workflows/tag-images.yml' + - '.github/workflows/main-image-workflow.yml' + - '.github/workflows/docker-publish.yml' - 'docker-compose.mongo-replica.yml' - 'utils/docker/init-replica.js' - '.env.example' @@ -60,6 +74,10 @@ jobs: run: npm run test:ci --workspace @librechat/channel-gateway - name: Build gateway run: npm run build --workspace @librechat/channel-gateway + - name: Verify release image provenance + run: node .github/scripts/test-channel-release.mjs + - name: Verify release and source Compose configuration + run: node .github/scripts/test-channel-compose.mjs - name: Verify local replica conversion and restart shell: bash run: | diff --git a/.github/workflows/main-image-workflow.yml b/.github/workflows/main-image-workflow.yml index a1482d9c94..4d29b72463 100644 --- a/.github/workflows/main-image-workflow.yml +++ b/.github/workflows/main-image-workflow.yml @@ -1,4 +1,4 @@ -name: Docker Compose Build Latest Main Image Tag (Manual Dispatch) +name: Publish Latest Stable Release Images (Manual Dispatch) on: workflow_dispatch: @@ -16,6 +16,7 @@ jobs: outputs: latest_tag: ${{ steps.tag.outputs.latest_tag }} sha: ${{ steps.tag.outputs.sha }} + images: ${{ steps.tag.outputs.images }} steps: - name: Checkout uses: actions/checkout@v5 @@ -36,24 +37,26 @@ jobs: exit 1 fi printf 'latest_tag=%s\n' "$LATEST_TAG" >> "$GITHUB_OUTPUT" - # Pin the publish to the commit this job resolved the tag from. `main` - # is a moving ref: were each build leg to resolve it independently, the - # amd64 and arm64 halves of one release could come from different - # commits and still be published under the same tags. - printf 'sha=%s\n' "$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" + # A versioned artifact must build the selected release, even when main + # has advanced. Both architectures receive that immutable commit. + printf 'sha=%s\n' "$(git rev-parse "${LATEST_TAG}^{commit}")" >> "$GITHUB_OUTPUT" + images='[{"target":"api-build","file":"Dockerfile.multi","image_name":"librechat-api"},{"target":"node","file":"Dockerfile","image_name":"librechat"}' + # Older releases have no gateway; do not invent an artifact for them. + if git cat-file -e "${LATEST_TAG}:packages/channel-gateway/Dockerfile" 2>/dev/null; then + images+=',{"target":"runtime","file":"packages/channel-gateway/Dockerfile","image_name":"librechat-channel-gateway"}' + fi + printf 'images=%s]\n' "$images" >> "$GITHUB_OUTPUT" publish: needs: resolve-tag uses: ./.github/workflows/docker-publish.yml with: - images: >- - [{"target":"api-build","file":"Dockerfile.multi","image_name":"librechat-api"}, - {"target":"node","file":"Dockerfile","image_name":"librechat"}] + images: ${{ needs.resolve-tag.outputs.images }} tag_suffixes: | ${{ needs.resolve-tag.outputs.latest_tag }} latest checkout_ref: ${{ needs.resolve-tag.outputs.sha }} - build_branch: main + build_branch: ${{ needs.resolve-tag.outputs.latest_tag }} secrets: DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} diff --git a/.github/workflows/tag-images.yml b/.github/workflows/tag-images.yml index 450e3ef939..760f42f5f0 100644 --- a/.github/workflows/tag-images.yml +++ b/.github/workflows/tag-images.yml @@ -67,7 +67,8 @@ jobs: with: images: >- [{"target":"api-build","file":"Dockerfile.multi","image_name":"librechat-api"}, - {"target":"node","file":"Dockerfile","image_name":"librechat"}] + {"target":"node","file":"Dockerfile","image_name":"librechat"}, + {"target":"runtime","file":"packages/channel-gateway/Dockerfile","image_name":"librechat-channel-gateway"}] tag_suffixes: ${{ needs.resolve-tags.outputs.tag_suffixes }} build_branch: ${{ github.ref_name }} secrets: diff --git a/docker-compose.channels-build.yml b/docker-compose.channels-build.yml new file mode 100644 index 0000000000..ae835eeaf8 --- /dev/null +++ b/docker-compose.channels-build.yml @@ -0,0 +1,14 @@ +# Add after docker-compose.channels.yml to build both services from this checkout. +services: + api: + image: librechat-channels-api:local + pull_policy: build + build: + context: . + dockerfile: Dockerfile + channel-gateway: + image: librechat-channel-gateway:local + pull_policy: build + build: + context: . + dockerfile: packages/channel-gateway/Dockerfile diff --git a/docker-compose.channels.yml b/docker-compose.channels.yml index 4a273fa607..d9ce6ed1d5 100644 --- a/docker-compose.channels.yml +++ b/docker-compose.channels.yml @@ -1,11 +1,8 @@ -# Optional source-built application and stateless gateway. +# Optional release-matched application and stateless gateway. # Setup: https://www.librechat.ai/docs/features/agent_channels#docker-compose services: api: - image: librechat-channels-api:local - build: - context: . - dockerfile: Dockerfile + image: ghcr.io/librechat-ai/librechat:${LIBRECHAT_IMAGE_TAG:-latest} volumes: - ./librechat.yaml:/app/librechat.yaml:ro healthcheck: @@ -22,9 +19,7 @@ services: retries: 12 channel-gateway: profiles: [channels] - build: - context: . - dockerfile: packages/channel-gateway/Dockerfile + image: ghcr.io/librechat-ai/librechat-channel-gateway:${LIBRECHAT_IMAGE_TAG:-latest} depends_on: api: condition: service_healthy