🐳 feat: Publish Release-Matched Channel Gateway Images (#17784)

* 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
This commit is contained in:
Dustin Healy 2026-11-10 21:04:08 -08:00 • committed by GitHub
parent 0b1185b214
commit d269d35a2c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 213 additions and 19 deletions

View file

@ -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

View file

@ -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');

View file

@ -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 });
}

View file

@ -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: |

View file

@ -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 }}

View file

@ -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:

View file

@ -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

View file

@ -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