test(tmachine): add Debian installer profile

.github/workflows/integration-runner.yml

@@ -24,7 +24,7 @@ on:
         type: string
         default: >-
           [
-            {"environment":"ubuntu-docker-rootful","installer":"binaries","testsuite":"conformance"},
+            {"environment":"ubuntu-docker-rootful","installer":"deb","testsuite":"conformance"},
             {"environment":"fedora-podman-rootful","installer":"binaries","testsuite":"conformance"},
             {"environment":"fedora-podman-rootless","installer":"binaries","testsuite":"conformance"}
           ]

.github/workflows/prepare-integration-inputs.yml

@@ -11,6 +11,11 @@ on:
         required: false
         type: string
         default: ""
+      deb-artifact-name:
+        description: Debian package artifact to include in the tmachine inputs
+        required: false
+        type: string
+        default: ""
     outputs:
       source_sha:
         description: Source revision of the candidate artifacts
@@ -65,6 +70,22 @@ jobs:
           github-token: ${{ github.token }}
           run-id: ${{ inputs['artifact-run-id'] || github.run_id }}
 
+      - name: Download Debian package artifact
+        if: inputs['deb-artifact-name'] != ''
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ inputs['deb-artifact-name'] }}
+          path: artifacts/packages/download
+          github-token: ${{ github.token }}
+          run-id: ${{ inputs['artifact-run-id'] || github.run_id }}
+
+      - name: Stage Debian package input
+        if: inputs['deb-artifact-name'] != ''
+        run: |
+          set -euo pipefail
+          mv artifacts/packages/download/*.deb artifacts/packages/openshell.deb
+          rmdir artifacts/packages/download
+
       - name: Log in to GHCR
         run: echo "${{ github.token }}" | docker login ghcr.io -u "${GITHUB_ACTOR}" --password-stdin
 

.github/workflows/release-dev.yml

@@ -102,12 +102,14 @@ jobs:
       checkout-ref: ${{ github.sha }}
 
   prepare-integration:
-    needs: [build-binaries, build-images]
+    needs: [build-binaries, build-deb, build-images]
     permissions:
       actions: read
       contents: read
       packages: read
     uses: ./.github/workflows/prepare-integration-inputs.yml
+    with:
+      deb-artifact-name: deb-linux-amd64
 
   conformance-integration:
     needs: prepare-integration

.github/workflows/release-tag.yml

@@ -130,12 +130,14 @@ jobs:
       checkout-ref: ${{ needs.compute-versions.outputs.source_sha }}
 
   prepare-integration:
-    needs: [compute-versions, build-binaries, build-images]
+    needs: [compute-versions, build-binaries, build-deb, build-images]
     permissions:
       actions: read
       contents: read
       packages: read
     uses: ./.github/workflows/prepare-integration-inputs.yml
+    with:
+      deb-artifact-name: deb-linux-amd64
 
   conformance-integration:
     needs: prepare-integration

architecture/build.md

@@ -275,7 +275,7 @@ includes, templates, inventory, and requirements. The digest uses sorted
 relative paths, file contents, and executable permissions; source symlinks
 are unsupported. Both keys also retain the ordered playbook paths and contents,
 their base disk contents, and whether Galaxy is enabled; install keys
-include named binary inputs. The top-level `.roles` directory is excluded:
+include named artifact inputs. The top-level `.roles` directory is excluded:
 Galaxy release pins in `requirements.yaml` are treated as immutable, including
 any transitive dependency pins. Cache misses with Galaxy enabled reinstall
 the required roles and their dependencies before running playbooks.
@@ -286,7 +286,17 @@ the gateway, sandbox, and supervisor as separate binaries for their respective
 Dockerfiles. The helpers stage binaries under `artifacts/binaries` so local and
 CI builds expose the same inputs to tmachine and image assembly. The Ubuntu
 Docker and Fedora Podman environments import both local runtime images and
-configure the gateway to use them.
+configure the gateway to use them. The Ubuntu `deb` installer consumes
+`artifacts/packages/openshell.deb`; the `binaries` installer remains available
+for direct executable installation on every environment. Release Dev and
+Release Tag run Ubuntu conformance through the Debian package, while Fedora
+continues using direct executable installation until RPM coverage is available.
+The Debian qualification profile keeps candidate-image overrides outside the
+operator-owned gateway configuration: it writes a harness-owned file under
+`/var/lib/openshell-qualification` and selects it through the packaged systemd
+unit's `gateway.env` hook. Ordinary package installations continue to use the
+gateway's built-in runtime-image defaults unless the operator configures an
+override.
 
 ## Python Wheel Packaging
 

tests/ansible/playbooks/conformance/cli.yaml

@@ -39,6 +39,15 @@
           - conformance_archive.stat.isreg | default(false)
         fail_msg: OpenShell conformance test bundle did not contain tests.tar.zst
 
+    - name: Resolve installed OpenShell CLI
+      ansible.builtin.command:
+        argv:
+          - /bin/sh
+          - -c
+          - command -v openshell
+      register: openshell_cli
+      changed_when: false
+
     - name: Run OpenShell conformance archive
       ansible.builtin.command:
         argv:
@@ -51,7 +60,7 @@
           - /var/lib/openshell-conformance/tests
           - --no-capture
       environment:
-        OPENSHELL_BIN: /usr/local/bin/openshell
+        OPENSHELL_BIN: "{{ openshell_cli.stdout }}"
       register: conformance_result
       changed_when: false
       failed_when: false

tests/ansible/playbooks/features/provider-refresh/keycloak.yaml

@@ -49,6 +49,15 @@
           - provider_refresh_keycloak_test_archive.stat.isreg | default(false)
         fail_msg: Keycloak provider refresh test bundle did not contain tests.tar.zst
 
+    - name: Resolve installed OpenShell CLI
+      ansible.builtin.command:
+        argv:
+          - /bin/sh
+          - -c
+          - command -v openshell
+      register: openshell_cli
+      changed_when: false
+
     - name: Run Keycloak provider refresh archive
       ansible.builtin.command:
         argv:
@@ -61,7 +70,7 @@
           - /var/lib/openshell-provider-refresh/tests
           - --no-capture
       environment:
-        OPENSHELL_BIN: /usr/local/bin/openshell
+        OPENSHELL_BIN: "{{ openshell_cli.stdout }}"
         OPENSHELL_E2E_OIDC_ISSUER: http://127.0.0.1:8180/realms/openshell
         OPENSHELL_E2E_OIDC_USERNAME: admin@test
         OPENSHELL_E2E_OIDC_PASSWORD: admin

tests/ansible/playbooks/openshell-deb.yaml

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+---
+- name: Install OpenShell Debian package
+  hosts: all
+  gather_facts: false
+  tasks:
+    - name: Wait for SSH
+      ansible.builtin.wait_for_connection:
+
+    - name: Copy OpenShell Debian package
+      become: true
+      ansible.builtin.copy:
+        src: "{{ openshell_deb }}"
+        dest: /var/tmp/openshell.deb
+        mode: "0644"
+
+    - name: Install OpenShell Debian package
+      become: true
+      ansible.builtin.apt:
+        deb: /var/tmp/openshell.deb
+
+    - name: Copy OpenShell runtime images
+      become: true
+      ansible.builtin.copy:
+        src: "{{ item.src }}"
+        dest: "/var/tmp/{{ item.name }}.tar"
+        mode: "0644"
+      loop:
+        - name: openshell-sandbox
+          src: "{{ openshell_sandbox_image }}"
+        - name: openshell-supervisor
+          src: "{{ openshell_supervisor_image }}"
+
+    - name: Load OpenShell runtime images
+      become: true
+      ansible.builtin.command:
+        argv:
+          - docker
+          - load
+          - --input
+          - "/var/tmp/{{ item }}.tar"
+      loop:
+        - openshell-sandbox
+        - openshell-supervisor
+
+    # The package normally starts from its built-in runtime-image defaults.
+    # Qualification instead pins the candidate images staged by tmachine, so
+    # keep that override separate from the operator-owned gateway.toml.
+    - name: Create OpenShell qualification configuration directory
+      become: true
+      ansible.builtin.file:
+        path: /var/lib/openshell-qualification
+        state: directory
+        owner: root
+        group: root
+        mode: "0755"
+
+    - name: Configure candidate OpenShell runtime images for qualification
+      become: true
+      ansible.builtin.copy:
+        dest: /var/lib/openshell-qualification/gateway.toml
+        owner: root
+        group: root
+        mode: "0644"
+        content: |
+          [openshell]
+          version = 2
+
+          [openshell.drivers.docker]
+          sandbox_runtime_image = "docker.io/openshell/sandbox:tmachine"
+          supervisor_image = "docker.io/openshell/supervisor:tmachine"
+
+    - name: Create OpenShell environment directory
+      ansible.builtin.file:
+        path: /home/tmachine/.config/openshell
+        state: directory
+        mode: "0700"
+
+    - name: Select qualification gateway configuration
+      ansible.builtin.copy:
+        dest: /home/tmachine/.config/openshell/gateway.env
+        mode: "0600"
+        content: |
+          OPENSHELL_GATEWAY_CONFIG=/var/lib/openshell-qualification/gateway.toml
+
+    - name: Start tmachine user manager
+      ansible.builtin.include_role:
+        name: tmachine_user_manager
+
+    - name: Start packaged OpenShell gateway service
+      ansible.builtin.systemd_service:
+        name: openshell-gateway.service
+        scope: user
+        daemon_reload: true
+        enabled: true
+        state: started
+      environment:
+        XDG_RUNTIME_DIR: /run/user/1000
+        DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus
+
+    - name: Wait for OpenShell gateway
+      ansible.builtin.wait_for:
+        host: 127.0.0.1
+        port: 17670
+        timeout: 60
+
+    - name: Register packaged OpenShell gateway
+      ansible.builtin.include_role:
+        name: openshell_client
+      vars:
+        openshell_client_gateway_endpoint: https://127.0.0.1:17670
+        openshell_client_gateway_name: openshell

tests/ansible/playbooks/podman-rootless.yaml

@@ -9,29 +9,9 @@
     - name: Wait for SSH
       ansible.builtin.wait_for_connection:
 
-    - name: Enable lingering for tmachine
-      become: true
-      ansible.builtin.command:
-        argv:
-          - loginctl
-          - enable-linger
-          - tmachine
-      changed_when: false
-
-    - name: Resolve tmachine UID
-      ansible.builtin.command:
-        argv:
-          - id
-          - -u
-          - tmachine
-      changed_when: false
-      register: tmachine_uid
-
     - name: Start tmachine user manager
-      become: true
-      ansible.builtin.systemd_service:
-        name: "user@{{ tmachine_uid.stdout }}.service"
-        state: started
+      ansible.builtin.include_role:
+        name: tmachine_user_manager
 
     - name: Enable rootless Podman socket
       become: true
@@ -43,5 +23,5 @@
         state: started
       environment:
         HOME: /home/tmachine
-        XDG_RUNTIME_DIR: "/run/user/{{ tmachine_uid.stdout }}"
-        DBUS_SESSION_BUS_ADDRESS: "unix:path=/run/user/{{ tmachine_uid.stdout }}/bus"
+        XDG_RUNTIME_DIR: /run/user/1000
+        DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus

tests/ansible/roles/openshell_client/tasks/main.yaml

@@ -2,13 +2,13 @@
 # SPDX-License-Identifier: Apache-2.0
 
 ---
-- name: Register OpenShell gateway for tmachine test client
+- name: Register OpenShell gateway for test client
   ansible.builtin.command:
     argv:
-      - /usr/local/bin/openshell
+      - openshell
       - gateway
       - add
-      - http://127.0.0.1:17670
+      - "{{ openshell_client_gateway_endpoint | default('http://127.0.0.1:17670') }}"
       - --local
       - --name
-      - tmachine
+      - "{{ openshell_client_gateway_name | default('tmachine') }}"

tests/ansible/roles/openshell_gateway/tasks/main.yaml

@@ -43,7 +43,7 @@
   become_user: "{{ openshell_gateway_user }}"
   ansible.builtin.command:
     argv:
-      - /usr/local/bin/openshell-gateway
+      - openshell-gateway
       - generate-certs
       - --output-dir
       - /var/lib/openshell/pki

tests/ansible/roles/openshell_gateway/templates/gateway.service.j2

@@ -11,7 +11,7 @@ User={{ openshell_gateway_user }}
 Group={{ openshell_gateway_user }}
 Environment=HOME={{ openshell_gateway_home }}
 {% block service %}{% endblock %}
-ExecStart=/usr/local/bin/openshell-gateway --config /etc/openshell/gateway.toml
+ExecStart=openshell-gateway --config /etc/openshell/gateway.toml
 Restart=on-failure
 
 [Install]

tests/ansible/roles/tmachine_user_manager/tasks/main.yaml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+---
+- name: Enable lingering for tmachine
+  become: true
+  ansible.builtin.command:
+    argv:
+      - loginctl
+      - enable-linger
+      - tmachine
+  changed_when: false
+
+- name: Start tmachine user manager
+  become: true
+  ansible.builtin.systemd_service:
+    name: user@1000.service
+    state: started

tests/config.nix

@@ -84,6 +84,18 @@ let
           openshell_sandbox_image = "../artifacts/images/openshell-sandbox-tmachine.tar";
         };
       }
+      {
+        name = "deb";
+        use_galaxy = false;
+        playbooks = [
+          "ansible/playbooks/openshell-deb.yaml"
+        ];
+        inputs = {
+          openshell_deb = "../artifacts/packages/openshell.deb";
+          openshell_supervisor_image = "../artifacts/images/openshell-supervisor-tmachine.tar";
+          openshell_sandbox_image = "../artifacts/images/openshell-sandbox-tmachine.tar";
+        };
+      }
     ];
 
     testsuites = [