# Ansible Role: Notarius

Installs and configures [Notarius](https://gitea.maximumdirect.net/eric/notarius)
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
facts and uses privilege escalation only for dependency installation and
root-owned application state.

## Variables

```yaml
notarius_version: v0.8.1
notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
notarius_source_dir: /usr/local/src/notarius
notarius_binary_path: /usr/local/bin/notarius
notarius_manage_build_dependencies: true
notarius_go_snap_channel: 1.26/stable
notarius_go_binary: /snap/bin/go
notarius_config_path: /usr/local/etc/notarius/config.yml
notarius_config_owner: root
notarius_config_group: root
notarius_config_directory_mode: "0755"
notarius_config_file_mode: "0644"
notarius_config_version: 5
notarius_promptkit_profile_dir: null
notarius_promptkit_profile_file: null
notarius_promptkit_transient_retries: null
notarius_promptkit_local_backend_endpoint: null
notarius_promptkit_local_backend_concurrency_limit: null
notarius_configkit_imports: null
notarius_pipelines: null
notarius_concurrency_total_llm: null
notarius_concurrency_stage_workers_extract: null
notarius_output_directory: null
notarius_cache_chunk_plans_mode: null
notarius_cache_chunk_plans_directory: null
notarius_cache_checkpoints_enabled: null
notarius_cache_checkpoints_directory: null
notarius_debug_directory: null
```

When `notarius_manage_build_dependencies` is `false`, Git and the executable
selected by `notarius_go_binary` must already be available. Otherwise, the role
installs Git with APT and the classic Go Snap from `notarius_go_snap_channel`.
It checks out `notarius_version` authoritatively, builds `./cmd/notarius`
directly to `notarius_binary_path`, and rebuilds only when that checkout changes
or the binary is absent. The source tree is recursively owned by `root:root`;
the binary is `root:root` mode `0755`.

Configuration variables map directly to Notarius's versioned YAML fields.
Every optional value defaults to `null`, so it and any empty parent section are
omitted and Notarius retains ownership of its built-in defaults. The role always
emits `notarius_config_version` as `version`. It manages
`notarius_config_path | dirname` and the resulting file with
`notarius_config_owner`, `notarius_config_group`,
`notarius_config_directory_mode`, and `notarius_config_file_mode`. The
standalone defaults are `root:root`, directory mode `0755`, and file mode
`0644`; composing roles may override this generic configuration interface.
`notarius_pipelines` is the native mapping supplied by the caller; the role
does not merge or rewrite it. For example, inventory can compose fragments in
the ordinary way:

```yaml
notarius_pipelines: "{{ notarius_pipeline_group_one | combine(notarius_pipeline_group_two) }}"
```

`notarius_configkit_imports` is the complete native ConfigKit import list. It
is caller-owned composition input: the role renders it into the root document
but does not create or merge imported fragments. Relative import paths resolve
from the managed root configuration directory.

PromptKit profile values identify profile sources or a local backend endpoint;
they never contain credentials. Supply any credential environment variables
outside this role.

`notarius_promptkit_transient_retries` renders
`promptkit.transient_retries` when set. The null default omits it so Notarius
retains its native retry behavior; integer `0` disables additional eligible
transient transport attempts.

## Example

```yaml
- hosts: notarius_hosts
  roles:
    - role: ansible-role-notarius
```

## Validation

The repository-local integration suite installs its pinned collection, runs
syntax checking and production-profile lint, and exercises the default CLI and
native configuration validation before requiring clean repeated convergence.
It verifies an explicitly selected Notarius release, combines missing-binary
recovery with a caller-supplied Go executable while dependency management is
disabled, and covers one representative configuration with null omission,
intentional falsey values, caller-side pipeline composition through a
test-owned ConfigKit import, and native validation and inspection. It mutates
only the managed source, binary, configuration, a test-owned imported fragment,
and a private temporary directory, then restores the default deployment during
cleanup.

```sh
tests/integration
```