feat(release): add managed source releases

.github/workflows/e2e.yml

@@ -77,18 +77,26 @@ jobs:
           api_server=false
           control_plane=false
           web_console=false
+          release_version_changed=false
+
+          # A release version selects all three component builds only after the
+          # Release PR merges to main. Pull request and merge queue events do not
+          # use this rule.
+          if [[ "${EVENT_NAME}" == "push" ]] && grep -qx "VERSION" <<<"${changed_files}"; then
+            release_version_changed=true
+          fi
 
           # These patterns MUST mirror each component's event-specific Konflux
           # CEL trigger in .tekton/hypershell-<component>-main-${pipeline_suffix}.yaml.
           # Only components whose path-filtered pipelines actually run may use
           # the event's commit-tagged image and wait for the corresponding check.
-          if grep -qE "^components/api-server/|^\\.tekton/hypershell-api-server-main-${pipeline_suffix}\\.yaml$" <<<"${changed_files}"; then
+          if [[ "${release_version_changed}" == "true" ]] || grep -qE "^components/api-server/|^\\.tekton/hypershell-api-server-main-${pipeline_suffix}\\.yaml$" <<<"${changed_files}"; then
             api_server=true
           fi
-          if grep -qE "^components/control-plane/|^\\.tekton/hypershell-control-plane-main-${pipeline_suffix}\\.yaml$|^Dockerfile$" <<<"${changed_files}"; then
+          if [[ "${release_version_changed}" == "true" ]] || grep -qE "^components/control-plane/|^\\.tekton/hypershell-control-plane-main-${pipeline_suffix}\\.yaml$|^Dockerfile$" <<<"${changed_files}"; then
             control_plane=true
           fi
-          if grep -qE "^components/web-console/|^packages/gateway-management-ui/|^\\.tekton/hypershell-web-console-main-${pipeline_suffix}\\.yaml$" <<<"${changed_files}"; then
+          if [[ "${release_version_changed}" == "true" ]] || grep -qE "^components/web-console/|^packages/gateway-management-ui/|^\\.tekton/hypershell-web-console-main-${pipeline_suffix}\\.yaml$" <<<"${changed_files}"; then
             web_console=true
           fi
 

.github/workflows/lint.yml

@@ -18,6 +18,18 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  lint-pull-request-title:
+    name: Conventional pull request title
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Check pull request title
+        env:
+          PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}
+        run: python3 scripts/release_policy.py check-title "${PULL_REQUEST_TITLE}"
+
   detect-changes:
     name: Detect changed components
     runs-on: ubuntu-24.04
@@ -60,6 +72,9 @@ jobs:
         with:
           go-version-file: hypershell/components/api-server/go.mod
           cache-dependency-path: hypershell/components/api-server/go.sum
+      - name: Verify linked build metadata
+        working-directory: hypershell/components/api-server
+        run: make check-build-metadata
       - name: Check formatting
         working-directory: hypershell/components/api-server
         run: |
@@ -249,6 +264,7 @@ jobs:
     name: Lint CI gate
     if: ${{ always() && !cancelled() }}
     needs:
+      - lint-pull-request-title
       - detect-changes
       - lint-api-server
       - lint-cli
@@ -262,6 +278,7 @@ jobs:
       - name: Check lint results
         env:
           DETECTION_RESULT: ${{ needs.detect-changes.result }}
+          PULL_REQUEST_TITLE_RESULT: ${{ needs.lint-pull-request-title.result }}
           API_SERVER_RESULT: ${{ needs.lint-api-server.result }}
           CLI_RESULT: ${{ needs.lint-cli.result }}
           CONTROL_PLANE_RESULT: ${{ needs.lint-control-plane.result }}
@@ -270,7 +287,7 @@ jobs:
           SDK_TYPESCRIPT_RESULT: ${{ needs.lint-sdk-typescript.result }}
           WEB_CONSOLE_RESULT: ${{ needs.lint-web-console.result }}
         run: |
-          for result in "${DETECTION_RESULT}" "${API_SERVER_RESULT}" "${CLI_RESULT}" "${CONTROL_PLANE_RESULT}" "${GATEWAY_MANAGEMENT_UI_RESULT}" "${PR_TEST_RESULT}" "${SDK_TYPESCRIPT_RESULT}" "${WEB_CONSOLE_RESULT}"; do
+          for result in "${PULL_REQUEST_TITLE_RESULT}" "${DETECTION_RESULT}" "${API_SERVER_RESULT}" "${CLI_RESULT}" "${CONTROL_PLANE_RESULT}" "${GATEWAY_MANAGEMENT_UI_RESULT}" "${PR_TEST_RESULT}" "${SDK_TYPESCRIPT_RESULT}" "${WEB_CONSOLE_RESULT}"; do
             if [[ "${result}" == failure || "${result}" == cancelled ]]; then
               echo "One or more lint jobs failed or were cancelled."
               exit 1

.github/workflows/release-please.yml

@@ -0,0 +1,58 @@
+name: Release Please
+
+on:
+  workflow_run:
+    workflows:
+      - E2E
+    types:
+      - completed
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: release-please-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    name: Update or publish the source release
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push' &&
+       github.event.workflow_run.head_branch == 'main')
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out the tested revision
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Decide whether Release Please must run
+        id: gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HEAD_REF: ${{ github.event.workflow_run.head_sha || github.sha }}
+        run: |
+          open_count="$(gh pr list --base main --label 'autorelease: pending' --state open --json number --jq 'length')"
+          if [[ "${open_count}" -gt 0 ]]; then
+            open_release_pr=true
+          else
+            open_release_pr=false
+          fi
+          decision="$(python3 scripts/release_policy.py should-run --head-ref "${HEAD_REF}" --open-release-pr "${open_release_pr}")"
+          echo "run=${decision}" >> "${GITHUB_OUTPUT}"
+
+      - name: Update the Release PR or publish the release
+        if: steps.gate.outputs.run == 'true'
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

.tekton/hypershell-api-server-main-merge-queue.yaml

@@ -28,9 +28,14 @@ spec:
   - name: image-expires-after
     value: 5d
   - name: dockerfile
-    value: Dockerfile
+    value: components/api-server/Dockerfile
   - name: path-context
-    value: components/api-server
+    value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-api-server-main-pull-request.yaml

@@ -28,9 +28,14 @@ spec:
   - name: image-expires-after
     value: 5d
   - name: dockerfile
-    value: Dockerfile
+    value: components/api-server/Dockerfile
   - name: path-context
-    value: components/api-server
+    value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-api-server-main-push.yaml

@@ -9,7 +9,7 @@ metadata:
     pipelinesascode.tekton.dev/max-keep-runs: "3"
     pipelinesascode.tekton.dev/on-cel-expression: event == "push" && target_branch
       == "main" && ( "components/api-server/***".pathChanged() || ".tekton/hypershell-api-server-main-push.yaml".pathChanged()
-      )
+      || "VERSION".pathChanged() )
   labels:
     appstudio.openshift.io/application: hypershell-main
     appstudio.openshift.io/component: hypershell-api-server-main
@@ -25,9 +25,14 @@ spec:
   - name: output-image
     value: quay.io/redhat-user-workloads/hcm-eng-prod-tenant/hypershell-main/hypershell-api-server-main:{{revision}}
   - name: dockerfile
-    value: Dockerfile
+    value: components/api-server/Dockerfile
   - name: path-context
-    value: components/api-server
+    value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-control-plane-main-merge-queue.yaml

@@ -31,6 +31,11 @@ spec:
     value: components/control-plane/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-control-plane-main-pull-request.yaml

@@ -31,6 +31,11 @@ spec:
     value: components/control-plane/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-control-plane-main-push.yaml

@@ -9,7 +9,7 @@ metadata:
     pipelinesascode.tekton.dev/max-keep-runs: "3"
     pipelinesascode.tekton.dev/on-cel-expression: event == "push" && target_branch
       == "main" && ( "components/control-plane/***".pathChanged() || ".tekton/hypershell-control-plane-main-push.yaml".pathChanged()
-      || "Dockerfile".pathChanged() )
+      || "Dockerfile".pathChanged() || "VERSION".pathChanged() )
   labels:
     appstudio.openshift.io/application: hypershell-main
     appstudio.openshift.io/component: hypershell-control-plane-main
@@ -28,6 +28,11 @@ spec:
     value: components/control-plane/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-web-console-main-merge-queue.yaml

@@ -31,6 +31,11 @@ spec:
     value: components/web-console/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-web-console-main-pull-request.yaml

@@ -31,6 +31,11 @@ spec:
     value: components/web-console/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

.tekton/hypershell-web-console-main-push.yaml

@@ -9,7 +9,8 @@ metadata:
     pipelinesascode.tekton.dev/max-keep-runs: "3"
     pipelinesascode.tekton.dev/on-cel-expression: event == "push" && target_branch
       == "main" && ( "components/web-console/***".pathChanged() || "packages/gateway-management-ui/***".pathChanged()
-      || ".tekton/hypershell-web-console-main-push.yaml".pathChanged() )
+      || ".tekton/hypershell-web-console-main-push.yaml".pathChanged() || "VERSION".pathChanged()
+      )
   labels:
     appstudio.openshift.io/application: hypershell-main
     appstudio.openshift.io/component: hypershell-web-console-main
@@ -28,6 +29,11 @@ spec:
     value: components/web-console/Dockerfile
   - name: path-context
     value: .
+  - name: build-args
+    value:
+    - VCS_REF={{revision}}
+  - name: build-args-file
+    value: build-version.env
   pipelineSpec:
     description: |
       This pipeline is ideal for building container images from a Containerfile while reducing network traffic.

AGENTS.md

@@ -0,0 +1,23 @@
+# HyperShell Agent Guidance
+
+Read [CLAUDE.md](CLAUDE.md) for the repository structure, commands, and
+development conventions.
+
+## Pull Requests
+
+Use a Conventional Commits title for each pull request:
+
+```text
+<type>(<optional-scope>)<optional-!>: <description>
+```
+
+If the title must contain a Jira key, put the key after the colon:
+
+```text
+feat(release): [HYPERSHELL-123] add managed source releases
+```
+
+Do not put the Jira key before the conventional type. The repository uses the
+pull request title as the squash commit subject. Release Please must be able to
+parse the type at the start of that subject. See [docs/releasing.md](docs/releasing.md)
+for the allowed types and release rules.

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.0
+
+This version is the source-release automation baseline.

CLAUDE.md

@@ -14,6 +14,25 @@ make hooks-install
 The pre-commit and pre-push hooks run the repository policy checks. Run the same
 checks manually with `make check`.
 
+## Pull Requests
+
+Use a Conventional Commits title for each pull request:
+
+```text
+<type>(<optional-scope>)<optional-!>: <description>
+```
+
+If the title must contain a Jira key, put the key after the colon:
+
+```text
+feat(release): [HYPERSHELL-123] add managed source releases
+```
+
+Do not put the Jira key before the conventional type. The repository uses the
+pull request title as the squash commit subject. Release Please must be able to
+parse the type at the start of that subject. See [release guidance](docs/releasing.md)
+for the allowed types and release rules.
+
 ## Structure
 
 - `components/api-server/` - Go REST + gRPC API microservice (rh-trex-ai framework), PostgreSQL-backed