GRM-16: test: add molecule lifecycle scenarios, integration tests, and docs

- Add multi-instance molecule scenario verifying isolated data/config dirs
- Add lifecycle molecule scenario testing stop/disable/enable/start sequence
- Update default and binary verify playbooks for template unit assertions
- Add integration tests for full CLI lifecycle and multi-instance support
- Add pytest integration marker and --no-cov Makefile target
- Update README with lifecycle commands, multi-instance examples, and architecture
- Update Makefile with start/stop/enable/disable/status/remove targets
- Update .env.example with GRM_LANG documentation

ansible/roles/gitea-runner/molecule/binary/verify.yml

@@ -22,16 +22,27 @@
       ansible.builtin.command: docker --version
       changed_when: false
 
-    - name: Check systemd service file exists
+    - name: Check systemd template unit exists
       ansible.builtin.stat:
-        path: "/etc/systemd/system/gitea-runner-molecule-test-runner.service"
+        path: "/etc/systemd/system/gitea-runner@.service"
       register: service_stat
 
-    - name: Assert service file exists
+    - name: Assert template unit exists
       ansible.builtin.assert:
         that:
           - service_stat.stat.exists
-        fail_msg: "Systemd service file is missing"
+        fail_msg: "Systemd template unit is missing"
+
+    - name: Check instance data directory exists
+      ansible.builtin.stat:
+        path: "{{ gitea_runner_data_dir }}"
+      register: data_dir_stat
+
+    - name: Assert instance data directory exists
+      ansible.builtin.assert:
+        that:
+          - data_dir_stat.stat.exists
+        fail_msg: "Instance data directory is missing"
 
     - name: Check prune timer exists
       ansible.builtin.stat:

ansible/roles/gitea-runner/molecule/default/verify.yml

@@ -33,6 +33,28 @@
           - timer_stat.stat.exists
         fail_msg: "Docker prune timer is missing"
 
+    - name: Check systemd template unit exists
+      ansible.builtin.stat:
+        path: "/etc/systemd/system/gitea-runner@.service"
+      register: service_stat
+
+    - name: Assert template unit exists
+      ansible.builtin.assert:
+        that:
+          - service_stat.stat.exists
+        fail_msg: "Systemd template unit is missing"
+
+    - name: Check instance data directory exists
+      ansible.builtin.stat:
+        path: "{{ gitea_runner_data_dir }}"
+      register: data_dir_stat
+
+    - name: Assert instance data directory exists
+      ansible.builtin.assert:
+        that:
+          - data_dir_stat.stat.exists
+        fail_msg: "Instance data directory is missing"
+
     - name: Check config file exists in data directory
       ansible.builtin.stat:
         path: "{{ gitea_runner_data_dir }}/config.yaml"

ansible/roles/gitea-runner/molecule/lifecycle/converge.yml

@@ -0,0 +1,11 @@
+---
+- name: Converge
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    runner_name: "lifecycle-test-runner"
+    skip_runner_registration: true
+  roles:
+    - role: gitea-runner

ansible/roles/gitea-runner/molecule/lifecycle/molecule.yml

@@ -0,0 +1,40 @@
+---
+driver:
+  name: docker
+
+platforms:
+  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
+    image: ${MOLECULE_PLATFORM_IMAGE:-geerlingguy/docker-ubuntu2204-ansible:latest}
+    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
+    volumes:
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+    cgroupns_mode: host
+    privileged: true
+    pre_build_image: true
+
+provisioner:
+  name: ansible
+  playbooks:
+    converge: converge.yml
+    prepare: ../common/prepare.yml
+    side_effect: side_effect.yml
+  env:
+    ANSIBLE_ROLES_PATH: "../../.."
+
+scenario:
+  test_sequence:
+    - dependency
+    - cleanup
+    - destroy
+    - syntax
+    - create
+    - prepare
+    - converge
+    - idempotence
+    - side_effect
+    - verify
+    - cleanup
+    - destroy
+
+verifier:
+  name: ansible

ansible/roles/gitea-runner/molecule/lifecycle/side_effect.yml

@@ -0,0 +1,36 @@
+---
+- name: Stop runner instance
+  hosts: all
+  become: true
+  vars:
+    runner_name: "lifecycle-test-runner"
+  tasks:
+    - name: Stop gitea-runner systemd instance
+      ansible.builtin.systemd:
+        name: "gitea-runner@{{ runner_name }}"
+        state: stopped
+        daemon_reload: true
+
+    - name: Disable gitea-runner systemd instance
+      ansible.builtin.systemd:
+        name: "gitea-runner@{{ runner_name }}"
+        enabled: false
+        daemon_reload: true
+
+- name: Re-enable and start runner
+  hosts: all
+  become: true
+  vars:
+    runner_name: "lifecycle-test-runner"
+  tasks:
+    - name: Enable gitea-runner systemd instance
+      ansible.builtin.systemd:
+        name: "gitea-runner@{{ runner_name }}"
+        enabled: true
+        daemon_reload: true
+
+    - name: Start gitea-runner systemd instance
+      ansible.builtin.systemd:
+        name: "gitea-runner@{{ runner_name }}"
+        state: started
+        daemon_reload: true

ansible/roles/gitea-runner/molecule/lifecycle/verify.yml

@@ -0,0 +1,41 @@
+---
+- name: Verify
+  hosts: all
+  become: true
+  pre_tasks:
+    - name: Load role defaults
+      ansible.builtin.include_vars:
+        dir: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/defaults"
+  tasks:
+    - name: Check systemd template unit exists
+      ansible.builtin.stat:
+        path: "/etc/systemd/system/gitea-runner@.service"
+      register: template_stat
+
+    - name: Assert template unit exists
+      ansible.builtin.assert:
+        that:
+          - template_stat.stat.exists
+        fail_msg: "Systemd template unit is missing"
+
+    - name: Check instance is enabled
+      ansible.builtin.systemd:
+        name: "gitea-runner@lifecycle-test-runner"
+      register: service_status
+
+    - name: Assert instance is enabled
+      ansible.builtin.assert:
+        that:
+          - service_status.status.LoadState == 'loaded'
+        fail_msg: "Systemd instance is not loaded"
+
+    - name: Check instance data directory exists after lifecycle
+      ansible.builtin.stat:
+        path: "/var/lib/gitea-runner/lifecycle-test-runner"
+      register: data_dir_stat
+
+    - name: Assert instance data directory exists
+      ansible.builtin.assert:
+        that:
+          - data_dir_stat.stat.exists
+        fail_msg: "Instance data directory is missing after lifecycle"

ansible/roles/gitea-runner/molecule/multi-instance/converge.yml

@@ -0,0 +1,22 @@
+---
+- name: Converge first runner instance
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    runner_name: "molecule-runner-a"
+    skip_runner_registration: true
+  roles:
+    - role: gitea-runner
+
+- name: Converge second runner instance
+  hosts: all
+  become: true
+  vars:
+    gitea_url: "http://localhost:3000"
+    registration_token: "fake-token-for-testing"
+    runner_name: "molecule-runner-b"
+    skip_runner_registration: true
+  roles:
+    - role: gitea-runner

ansible/roles/gitea-runner/molecule/multi-instance/molecule.yml

@@ -0,0 +1,39 @@
+---
+driver:
+  name: docker
+
+platforms:
+  - name: ${MOLECULE_PLATFORM_NAME:-ubuntu-2204}
+    image: ${MOLECULE_PLATFORM_IMAGE:-geerlingguy/docker-ubuntu2204-ansible:latest}
+    command: ${MOLECULE_PLATFORM_COMMAND:-sleep infinity}
+    volumes:
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+    cgroupns_mode: host
+    privileged: true
+    pre_build_image: true
+
+provisioner:
+  name: ansible
+  playbooks:
+    converge: converge.yml
+    prepare: ../common/prepare.yml
+  env:
+    ANSIBLE_ROLES_PATH: "../../.."
+
+scenario:
+  test_sequence:
+    - dependency
+    - cleanup
+    - destroy
+    - syntax
+    - create
+    - prepare
+    - converge
+    - idempotence
+    - side_effect
+    - verify
+    - cleanup
+    - destroy
+
+verifier:
+  name: ansible

ansible/roles/gitea-runner/molecule/multi-instance/verify.yml

@@ -0,0 +1,63 @@
+---
+- name: Verify
+  hosts: all
+  become: true
+  pre_tasks:
+    - name: Load role defaults
+      ansible.builtin.include_vars:
+        dir: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/defaults"
+  tasks:
+    - name: Check systemd template unit exists
+      ansible.builtin.stat:
+        path: "/etc/systemd/system/gitea-runner@.service"
+      register: template_stat
+
+    - name: Assert template unit exists
+      ansible.builtin.assert:
+        that:
+          - template_stat.stat.exists
+        fail_msg: "Systemd template unit is missing"
+
+    - name: Check first instance data directory exists
+      ansible.builtin.stat:
+        path: "/var/lib/gitea-runner/molecule-runner-a"
+      register: data_a_stat
+
+    - name: Assert first instance data directory exists
+      ansible.builtin.assert:
+        that:
+          - data_a_stat.stat.exists
+        fail_msg: "First instance data directory is missing"
+
+    - name: Check second instance data directory exists
+      ansible.builtin.stat:
+        path: "/var/lib/gitea-runner/molecule-runner-b"
+      register: data_b_stat
+
+    - name: Assert second instance data directory exists
+      ansible.builtin.assert:
+        that:
+          - data_b_stat.stat.exists
+        fail_msg: "Second instance data directory is missing"
+
+    - name: Check first instance config exists
+      ansible.builtin.stat:
+        path: "/etc/gitea-runner/molecule-runner-a/config.yaml"
+      register: config_a_stat
+
+    - name: Assert first instance config exists
+      ansible.builtin.assert:
+        that:
+          - config_a_stat.stat.exists
+        fail_msg: "First instance config file is missing"
+
+    - name: Check second instance config exists
+      ansible.builtin.stat:
+        path: "/etc/gitea-runner/molecule-runner-b/config.yaml"
+      register: config_b_stat
+
+    - name: Assert second instance config exists
+      ansible.builtin.assert:
+        that:
+          - config_b_stat.stat.exists
+        fail_msg: "Second instance config file is missing"