Install and configure Audita

README.md

@@ -1,3 +1,56 @@
-# ansible-role-audita
+# Ansible Role: Audita
 
-Ansible role to install the Audita transcript processor.
+Installs and configures [Audita](https://gitea.maximumdirect.net/eric/audita)
+from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
+facts and uses privilege escalation on tasks that install dependencies or
+manage root-owned application state.
+
+## Variables
+
+```yaml
+audita_version: v0.9.1
+audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
+audita_source_dir: /usr/local/src/audita
+audita_binary_path: /usr/local/bin/audita
+audita_manage_build_dependencies: true
+audita_go_snap_channel: 1.26/stable
+audita_go_binary: /snap/bin/go
+audita_config_path: /usr/local/etc/audita/config.yml
+audita_config:
+  version: 1
+```
+
+When `audita_manage_build_dependencies` is `false`, Git and the executable
+selected by `audita_go_binary` must already be available. Otherwise, the role
+installs Git with APT and the classic Go Snap from `audita_go_snap_channel`.
+
+The checkout is authoritative: local source changes are discarded while
+selecting `audita_version`. The role builds Audita directly to
+`audita_binary_path` using `audita_go_binary`, `CGO_ENABLED=0`, `GOWORK=off`,
+`GOTOOLCHAIN=local`, `-trimpath`, and release linker metadata. It rebuilds when
+the checkout changes or the binary is absent. The source tree is recursively
+owned by `root:root`; the binary is `root:root` mode `0755`.
+
+`audita_config` is the complete versioned YAML document, not an overlay on
+hidden defaults. The role writes it to `audita_config_path` as `root:root` mode
+`0644`. The repository-local integration suite validates it with Audita rather
+than executing the CLI during production convergence.
+
+## Example
+
+```yaml
+- hosts: audita_hosts
+  roles:
+    - role: ansible-role-audita
+```
+
+## Validation
+
+The integration driver installs pinned collection dependencies, runs syntax
+checking and ansible-lint, verifies the default release, file ownership and
+modes, executable behavior, and native configuration validation, then proves
+an immediate repeat is unchanged. It manages the default local installation:
+
+```sh
+tests/integration
+```