# Ansible Role: Audita

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
audita_pipeline_modules: null
audita_output_schema: null
audita_llm_proposal_base_url: null
audita_llm_proposal_model: null
audita_llm_proposal_api_key_env: null
audita_llm_proposal_timeout: null
audita_llm_proposal_max_retries: null
audita_llm_validation_base_url: null
audita_llm_validation_model: null
audita_llm_validation_api_key_env: null
audita_llm_validation_timeout: null
audita_llm_validation_max_retries: null
audita_concurrency_total_llm: null
audita_concurrency_proposal_llm: null
audita_concurrency_validation_llm: null
audita_chunking_target_sections: null
audita_chunking_max_section_tokens: null
audita_chunking_min_section_tokens: null
audita_normalization_max_segment_gap: null
audita_normalization_ellipsis_gap: null
audita_normalization_max_segment_duration: null
audita_normalization_max_segment_tokens: null
audita_thresholds_glossary: null
audita_thresholds_homophones: null
audita_thresholds_spoken_word: null
audita_thresholds_grammar: null
audita_context_description: null
audita_diagnostics_work_dir: null
audita_diagnostics_retention: null
```

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`.

The configuration variables map directly to Audita's versioned YAML fields.
Every optional variable defaults to `null`; null values and their empty parent
sections are omitted, allowing Audita to retain ownership of its built-in
defaults. `audita_config_version` always renders as `version` and defaults to
`1`. The role writes the resulting file to `audita_config_path` as `root:root`
mode `0644`.

LLM API-key settings name environment variables through
`audita_llm_proposal_api_key_env` and `audita_llm_validation_api_key_env`; they
must never contain secret values. The repository-local integration suite
validates the rendered file 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. It covers
missing-binary and checkout rebuilds, caller-supplied Go with dependency
management disabled, metadata repair without rebuilding, configuration-only
convergence, and platform failures before isolated application state exists.
On a fresh host, default convergence may also install Git through APT, refresh
the APT cache, and install the Go Snap. Application state is limited to
`/usr/local/src/audita`, `/usr/local/bin/audita`, and
`/usr/local/etc/audita/config.yml`; temporary test-specific files remain inside
the suite's private temporary directory. The suite leaves the default release
and configuration installed:

```sh
tests/integration
```