Skip to content

docs: update chat component docs to use @inkeep/agents-ui-cloud #195

docs: update chat component docs to use @inkeep/agents-ui-cloud

docs: update chat component docs to use @inkeep/agents-ui-cloud #195

name: Preview Environments
# Required GitHub Actions configuration
# Secrets:
# - RAILWAY_TOKEN
# - VERCEL_TOKEN
# - VERCEL_ORG_ID
# - VERCEL_API_PROJECT_ID
# - VERCEL_MANAGE_UI_PROJECT_ID
#
# Required preview auth configuration:
# - PREVIEW_MANAGE_UI_USERNAME=<admin email> (repo variable)
# - PREVIEW_MANAGE_UI_PASSWORD=<admin password> (secret)
# - PREVIEW_BETTER_AUTH_SECRET=<preview Better Auth secret> (secret)
# - PREVIEW_SPICEDB_PRESHARED_KEY=<preview SpiceDB key> (secret)
#
# Repository variables:
# - PREVIEW_ENVIRONMENTS_ENABLED=true|false
# - RAILWAY_PROJECT_ID=<railway project id>
# - RAILWAY_TEMPLATE_ENVIRONMENT=<base environment to copy, e.g. staging>
# - RAILWAY_OUTPUT_SERVICE=<service name/id that exposes resolved runtime vars, default: agents-api>
# - RAILWAY_MANAGE_DB_SERVICE=<service name/id for Doltgres, default: doltgres>
# - RAILWAY_RUN_DB_SERVICE=<service name/id for runtime Postgres, default: postgres>
# - RAILWAY_SPICEDB_SERVICE=<service name/id for preview SpiceDB, default: spicedb>
# - RAILWAY_SPICEDB_TCP_PORT=<SpiceDB gRPC port for Railway TCP proxy, default: 50051>
# - RAILWAY_SPICEDB_PRESHARED_KEY_KEY=<service var key for SpiceDB auth, default: SPICEDB_GRPC_PRESHARED_KEY>
# - RAILWAY_MANAGE_DB_URL_KEY=<runtime var key, default: INKEEP_AGENTS_MANAGE_DATABASE_URL>
# - RAILWAY_RUN_DB_URL_KEY=<runtime var key, default: INKEEP_AGENTS_RUN_DATABASE_URL>
# - RAILWAY_SPICEDB_ENDPOINT_KEY=<runtime var key, default: SPICEDB_ENDPOINT>
# - Optional explicit runtime templates (authoritative overrides when set):
# - RAILWAY_MANAGE_DB_URL_TEMPLATE (example: postgresql://appuser:password@${{doltgres.RAILWAY_TCP_PROXY_DOMAIN}}:${{doltgres.RAILWAY_TCP_PROXY_PORT}}/inkeep_agents?sslmode=disable)
# - RAILWAY_RUN_DB_URL_TEMPLATE (example: postgresql://appuser:password@${{postgres.RAILWAY_TCP_PROXY_DOMAIN}}:${{postgres.RAILWAY_TCP_PROXY_PORT}}/inkeep_agents?sslmode=disable)
# - RAILWAY_SPICEDB_ENDPOINT_TEMPLATE (default: ${{spicedb.RAILWAY_TCP_PROXY_DOMAIN}}:${{spicedb.RAILWAY_TCP_PROXY_PORT}})
on:
pull_request:
types: [opened, reopened, synchronize, closed]
workflow_dispatch:
inputs:
pr_number:
description: Pull request number to simulate
required: false
type: string
force_enable:
description: Force-enable preview flow for this manual run only
required: false
default: false
type: boolean
permissions:
contents: read
pull-requests: write
concurrency:
group: preview-environments-${{ github.event.pull_request.number || inputs.pr_number || github.ref }}
cancel-in-progress: false
env:
PREVIEW_BASE_DOMAIN: preview.inkeep.com
PREVIEW_ENVIRONMENTS_ENABLED: ${{ vars.PREVIEW_ENVIRONMENTS_ENABLED || 'false' }}
jobs:
compute-context:
name: Compute Preview Context
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
pr_number: ${{ steps.compute.outputs.pr_number }}
pr_branch: ${{ steps.compute.outputs.pr_branch }}
api_url: ${{ steps.compute.outputs.api_url }}
ui_url: ${{ steps.compute.outputs.ui_url }}
is_internal_pr: ${{ steps.compute.outputs.is_internal_pr }}
preview_enabled: ${{ steps.compute.outputs.preview_enabled }}
steps:
- name: Compute context
id: compute
env:
EVENT_NAME: ${{ github.event_name }}
EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
EVENT_PR_BRANCH: ${{ github.event.pull_request.head.ref }}
INPUT_PR_NUMBER: ${{ inputs.pr_number }}
INPUT_FORCE_ENABLE: ${{ inputs.force_enable }}
EVENT_REPO_FULL_NAME: ${{ github.event.pull_request.head.repo.full_name }}
WORKFLOW_REPO_FULL_NAME: ${{ github.repository }}
GITHUB_API_URL: ${{ github.api_url }}
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
PR_NUMBER="${EVENT_PR_NUMBER:-${INPUT_PR_NUMBER:-}}"
if [ -z "${PR_NUMBER}" ]; then
echo "Unable to determine PR number."
exit 1
fi
if ! [[ "${PR_NUMBER}" =~ ^[0-9]+$ ]]; then
echo "Invalid PR number: ${PR_NUMBER}"
exit 1
fi
if [ -n "${EVENT_PR_BRANCH:-}" ]; then
PR_BRANCH="${EVENT_PR_BRANCH}"
elif [ "${EVENT_NAME:-}" = "workflow_dispatch" ]; then
PR_BRANCH="$(
curl --connect-timeout 10 --max-time 30 -fsS \
-H "Authorization: Bearer ${GH_TOKEN}" \
-H "Accept: application/vnd.github+json" \
"${GITHUB_API_URL}/repos/${WORKFLOW_REPO_FULL_NAME}/pulls/${PR_NUMBER}" |
jq -r '.head.ref // empty'
)"
if [ -z "${PR_BRANCH}" ]; then
echo "Unable to resolve PR branch from GitHub API for PR #${PR_NUMBER}; using fallback."
PR_BRANCH="pr-${PR_NUMBER}"
fi
else
PR_BRANCH="pr-${PR_NUMBER}"
fi
IS_INTERNAL_PR="false"
if [ "${EVENT_NAME:-}" = "workflow_dispatch" ]; then
IS_INTERNAL_PR="true"
fi
if [ -n "${EVENT_REPO_FULL_NAME:-}" ] && [ "${EVENT_REPO_FULL_NAME}" = "${WORKFLOW_REPO_FULL_NAME}" ]; then
IS_INTERNAL_PR="true"
fi
API_URL="https://pr-${PR_NUMBER}-api.${PREVIEW_BASE_DOMAIN}"
UI_URL="https://pr-${PR_NUMBER}-ui.${PREVIEW_BASE_DOMAIN}"
PREVIEW_ENABLED="${PREVIEW_ENVIRONMENTS_ENABLED}"
if [ "${EVENT_NAME:-}" = "workflow_dispatch" ] && [ "${INPUT_FORCE_ENABLE:-false}" = "true" ]; then
PREVIEW_ENABLED="true"
fi
echo "pr_number=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
echo "pr_branch=${PR_BRANCH}" >> "$GITHUB_OUTPUT"
echo "api_url=${API_URL}" >> "$GITHUB_OUTPUT"
echo "ui_url=${UI_URL}" >> "$GITHUB_OUTPUT"
echo "is_internal_pr=${IS_INTERNAL_PR}" >> "$GITHUB_OUTPUT"
echo "preview_enabled=${PREVIEW_ENABLED}" >> "$GITHUB_OUTPUT"
- name: Summary
run: |
{
echo "## Preview Context"
echo "- PR: #${{ steps.compute.outputs.pr_number }}"
echo "- Branch: \`${{ steps.compute.outputs.pr_branch }}\`"
echo "- API URL: \`${{ steps.compute.outputs.api_url }}\`"
echo "- UI URL: \`${{ steps.compute.outputs.ui_url }}\`"
echo "- Internal PR: \`${{ steps.compute.outputs.is_internal_pr }}\`"
echo "- Preview flow enabled: \`${{ steps.compute.outputs.preview_enabled }}\`"
} >> "$GITHUB_STEP_SUMMARY"
preview-disabled:
name: Preview Flow Disabled
runs-on: ubuntu-latest
timeout-minutes: 5
needs: [compute-context]
if: needs.compute-context.outputs.preview_enabled != 'true'
steps:
- name: Explain disabled state
run: |
{
echo "## Preview Environments Disabled"
echo "Set repository variable \`PREVIEW_ENVIRONMENTS_ENABLED=true\` to activate provisioning + env injection."
} >> "$GITHUB_STEP_SUMMARY"
provision-tier1:
name: Provision Tier 1 (Railway)
runs-on: ubuntu-latest
timeout-minutes: 15
needs: [compute-context]
if: |
needs.compute-context.outputs.preview_enabled == 'true' &&
github.event.action != 'closed' &&
needs.compute-context.outputs.is_internal_pr == 'true'
outputs:
manage_db_url: ${{ steps.provision.outputs.manage_db_url }}
run_db_url: ${{ steps.provision.outputs.run_db_url }}
spicedb_endpoint: ${{ steps.provision.outputs.spicedb_endpoint }}
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
- name: Install Railway CLI
run: npm install -g @railway/cli@4.31.0
- name: Provision per-PR resources
id: provision
env:
CI: true
RAILWAY_API_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_TEMPLATE_ENVIRONMENT: ${{ vars.RAILWAY_TEMPLATE_ENVIRONMENT }}
RAILWAY_OUTPUT_SERVICE: ${{ vars.RAILWAY_OUTPUT_SERVICE || 'agents-api' }}
RAILWAY_MANAGE_DB_SERVICE: ${{ vars.RAILWAY_MANAGE_DB_SERVICE || 'doltgres' }}
RAILWAY_RUN_DB_SERVICE: ${{ vars.RAILWAY_RUN_DB_SERVICE || 'postgres' }}
RAILWAY_MANAGE_DB_TCP_PORT: ${{ vars.RAILWAY_MANAGE_DB_TCP_PORT || '5432' }}
RAILWAY_RUN_DB_TCP_PORT: ${{ vars.RAILWAY_RUN_DB_TCP_PORT || '5432' }}
RAILWAY_SPICEDB_SERVICE: ${{ vars.RAILWAY_SPICEDB_SERVICE || 'spicedb' }}
RAILWAY_SPICEDB_TCP_PORT: ${{ vars.RAILWAY_SPICEDB_TCP_PORT || '50051' }}
RAILWAY_SPICEDB_PRESHARED_KEY_KEY: ${{ vars.RAILWAY_SPICEDB_PRESHARED_KEY_KEY || 'SPICEDB_GRPC_PRESHARED_KEY' }}
RAILWAY_MANAGE_DB_URL_KEY: ${{ vars.RAILWAY_MANAGE_DB_URL_KEY || 'INKEEP_AGENTS_MANAGE_DATABASE_URL' }}
RAILWAY_RUN_DB_URL_KEY: ${{ vars.RAILWAY_RUN_DB_URL_KEY || 'INKEEP_AGENTS_RUN_DATABASE_URL' }}
RAILWAY_SPICEDB_ENDPOINT_KEY: ${{ vars.RAILWAY_SPICEDB_ENDPOINT_KEY || 'SPICEDB_ENDPOINT' }}
RAILWAY_MANAGE_DB_URL_TEMPLATE: ${{ vars.RAILWAY_MANAGE_DB_URL_TEMPLATE || '' }}
RAILWAY_RUN_DB_URL_TEMPLATE: ${{ vars.RAILWAY_RUN_DB_URL_TEMPLATE || '' }}
RAILWAY_SPICEDB_ENDPOINT_TEMPLATE: ${{ vars.RAILWAY_SPICEDB_ENDPOINT_TEMPLATE || '' }}
SPICEDB_PRESHARED_KEY: ${{ secrets.PREVIEW_SPICEDB_PRESHARED_KEY }}
PR_NUMBER: ${{ needs.compute-context.outputs.pr_number }}
run: bash .github/scripts/preview/provision-railway.sh
bootstrap-preview-auth:
name: Bootstrap Preview Auth
runs-on: ubuntu-latest
timeout-minutes: 20
needs: [compute-context, provision-tier1]
if: |
needs.compute-context.outputs.preview_enabled == 'true' &&
github.event.action != 'closed' &&
needs.compute-context.outputs.is_internal_pr == 'true'
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
- name: Install
uses: ./.github/composite-actions/install
- name: Install Railway CLI
run: npm install -g @railway/cli@4.31.0
- name: Seed preview admin user
env:
API_URL: ${{ needs.compute-context.outputs.api_url }}
RUN_DB_URL: ${{ needs.provision-tier1.outputs.run_db_url }}
SPICEDB_ENDPOINT: ${{ needs.provision-tier1.outputs.spicedb_endpoint }}
SPICEDB_TLS_ENABLED: false
RAILWAY_API_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_OUTPUT_SERVICE: ${{ vars.RAILWAY_OUTPUT_SERVICE || 'agents-api' }}
RAILWAY_RUN_DB_URL_KEY: ${{ vars.RAILWAY_RUN_DB_URL_KEY || 'INKEEP_AGENTS_RUN_DATABASE_URL' }}
RAILWAY_SPICEDB_ENDPOINT_KEY: ${{ vars.RAILWAY_SPICEDB_ENDPOINT_KEY || 'SPICEDB_ENDPOINT' }}
SPICEDB_PRESHARED_KEY: ${{ secrets.PREVIEW_SPICEDB_PRESHARED_KEY }}
PR_NUMBER: ${{ needs.compute-context.outputs.pr_number }}
TENANT_ID: default
INKEEP_AGENTS_MANAGE_UI_USERNAME: ${{ vars.PREVIEW_MANAGE_UI_USERNAME }}
INKEEP_AGENTS_MANAGE_UI_PASSWORD: ${{ secrets.PREVIEW_MANAGE_UI_PASSWORD }}
BETTER_AUTH_SECRET: ${{ secrets.PREVIEW_BETTER_AUTH_SECRET }}
run: bash .github/scripts/preview/bootstrap-preview-auth.sh
configure-vercel-preview:
name: Inject Vercel Preview Env Vars
runs-on: ubuntu-latest
timeout-minutes: 20
needs: [compute-context, provision-tier1]
if: |
needs.compute-context.outputs.preview_enabled == 'true' &&
github.event.action != 'closed' &&
needs.compute-context.outputs.is_internal_pr == 'true'
outputs:
api_deployment_url: ${{ steps.deploy.outputs.api_deployment_url }}
ui_deployment_url: ${{ steps.deploy.outputs.ui_deployment_url }}
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
- name: Install Railway CLI
run: npm install -g @railway/cli@4.31.0
- name: Upsert Vercel env vars for API + UI projects
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_API_PROJECT_ID: ${{ secrets.VERCEL_API_PROJECT_ID }}
VERCEL_MANAGE_UI_PROJECT_ID: ${{ secrets.VERCEL_MANAGE_UI_PROJECT_ID }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
PR_BRANCH: ${{ needs.compute-context.outputs.pr_branch }}
API_URL: ${{ needs.compute-context.outputs.api_url }}
UI_URL: ${{ needs.compute-context.outputs.ui_url }}
MANAGE_DB_URL: ${{ needs.provision-tier1.outputs.manage_db_url }}
RUN_DB_URL: ${{ needs.provision-tier1.outputs.run_db_url }}
SPICEDB_ENDPOINT: ${{ needs.provision-tier1.outputs.spicedb_endpoint }}
BETTER_AUTH_SECRET: ${{ secrets.PREVIEW_BETTER_AUTH_SECRET }}
SPICEDB_PRESHARED_KEY: ${{ secrets.PREVIEW_SPICEDB_PRESHARED_KEY }}
CI: true
RAILWAY_API_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_OUTPUT_SERVICE: ${{ vars.RAILWAY_OUTPUT_SERVICE || 'agents-api' }}
RAILWAY_MANAGE_DB_URL_KEY: ${{ vars.RAILWAY_MANAGE_DB_URL_KEY || 'INKEEP_AGENTS_MANAGE_DATABASE_URL' }}
RAILWAY_RUN_DB_URL_KEY: ${{ vars.RAILWAY_RUN_DB_URL_KEY || 'INKEEP_AGENTS_RUN_DATABASE_URL' }}
RAILWAY_SPICEDB_ENDPOINT_KEY: ${{ vars.RAILWAY_SPICEDB_ENDPOINT_KEY || 'SPICEDB_ENDPOINT' }}
PR_NUMBER: ${{ needs.compute-context.outputs.pr_number }}
run: bash .github/scripts/preview/upsert-vercel-preview-env.sh
- name: Trigger Vercel preview deploys
id: deploy
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_API_PROJECT_ID: ${{ secrets.VERCEL_API_PROJECT_ID }}
VERCEL_MANAGE_UI_PROJECT_ID: ${{ secrets.VERCEL_MANAGE_UI_PROJECT_ID }}
PR_BRANCH: ${{ needs.compute-context.outputs.pr_branch }}
PR_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
API_URL: ${{ needs.compute-context.outputs.api_url }}
UI_URL: ${{ needs.compute-context.outputs.ui_url }}
run: bash .github/scripts/preview/deploy-vercel-preview.sh
smoke-preview:
name: Smoke Test Preview URLs
runs-on: ubuntu-latest
timeout-minutes: 15
needs: [compute-context, provision-tier1, bootstrap-preview-auth, configure-vercel-preview]
if: |
needs.compute-context.outputs.preview_enabled == 'true' &&
github.event.action != 'closed' &&
needs.compute-context.outputs.is_internal_pr == 'true'
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
- name: Basic URL checks
id: smoke
continue-on-error: true
env:
API_URL: ${{ needs.compute-context.outputs.api_url }}
UI_URL: ${{ needs.compute-context.outputs.ui_url }}
TENANT_ID: default
INKEEP_AGENTS_MANAGE_UI_USERNAME: ${{ vars.PREVIEW_MANAGE_UI_USERNAME }}
INKEEP_AGENTS_MANAGE_UI_PASSWORD: ${{ secrets.PREVIEW_MANAGE_UI_PASSWORD }}
run: bash .github/scripts/preview/smoke-preview.sh
- name: Capture preview failure diagnostics
if: ${{ always() && steps.smoke.outcome == 'failure' }}
env:
API_URL: ${{ needs.compute-context.outputs.api_url }}
UI_URL: ${{ needs.compute-context.outputs.ui_url }}
TENANT_ID: default
INKEEP_AGENTS_MANAGE_UI_USERNAME: ${{ vars.PREVIEW_MANAGE_UI_USERNAME }}
INKEEP_AGENTS_MANAGE_UI_PASSWORD: ${{ secrets.PREVIEW_MANAGE_UI_PASSWORD }}
run: bash .github/scripts/preview/capture-preview-failure-diagnostics.sh
- name: Fetch Vercel runtime logs for API deployment
if: ${{ always() && steps.smoke.outcome == 'failure' }}
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_API_PROJECT_ID: ${{ secrets.VERCEL_API_PROJECT_ID }}
API_URL: ${{ needs.compute-context.outputs.api_url }}
API_DEPLOYMENT_URL: ${{ needs.configure-vercel-preview.outputs.api_deployment_url }}
run: bash .github/scripts/preview/fetch-vercel-runtime-logs.sh
- name: Fail job when smoke checks fail
if: ${{ steps.smoke.outcome == 'failure' }}
run: |
echo "Smoke checks failed"
exit 1
teardown-tier1:
name: Teardown Tier 1 (Railway)
runs-on: ubuntu-latest
timeout-minutes: 10
needs: [compute-context]
if: |
needs.compute-context.outputs.preview_enabled == 'true' &&
github.event.action == 'closed' &&
needs.compute-context.outputs.is_internal_pr == 'true'
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
- name: Install Railway CLI
run: npm install -g @railway/cli@4.31.0
- name: Teardown per-PR resources
env:
CI: true
RAILWAY_API_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
RAILWAY_PROJECT_ID: ${{ vars.RAILWAY_PROJECT_ID }}
RAILWAY_TEMPLATE_ENVIRONMENT: ${{ vars.RAILWAY_TEMPLATE_ENVIRONMENT }}
RAILWAY_OUTPUT_SERVICE: ${{ vars.RAILWAY_OUTPUT_SERVICE || 'agents-api' }}
PR_NUMBER: ${{ needs.compute-context.outputs.pr_number }}
run: bash .github/scripts/preview/teardown-railway.sh