feat: workflow for roles readme (#705)

* chore: added aar_doc config

Signed-off-by: Nemental <[email protected]>

* feat: added initial state of roles readme workflow

Signed-off-by: Nemental <[email protected]>

* fix: runs on

Signed-off-by: Nemental <[email protected]>

* fix: install poetry

Signed-off-by: Nemental <[email protected]>

* feat: loop over all roles and install peotry with pip

Signed-off-by: Nemental <[email protected]>

* fix: working dir for poetry run

Signed-off-by: Nemental <[email protected]>

* fix: cli path

Signed-off-by: Nemental <[email protected]>

* chore: scale down matrix loop for testing

Signed-off-by: Nemental <[email protected]>

* fix: poetry run for py execution command

Signed-off-by: Nemental <[email protected]>

* fix: work dir for poetry run

Signed-off-by: Nemental <[email protected]>

* fix: cli.py path

Signed-off-by: Nemental <[email protected]>

* fix: roles path

Signed-off-by: Nemental <[email protected]>

* feat: push readme

Signed-off-by: Nemental <[email protected]>

* fix: on push branch master

Signed-off-by: Nemental <[email protected]>

* fix: uncomment other roles

Signed-off-by: Nemental <[email protected]>

* chore: limit trigger to master and arguments

Co-authored-by: Sebastian Gumprich <[email protected]>
Signed-off-by: Nemental <[email protected]>

* fix: push branch name

Co-authored-by: Sebastian Gumprich <[email protected]>
Signed-off-by: Nemental <[email protected]>

* refactor: simplify steps

Co-authored-by: Sebastian Gumprich <[email protected]>
Signed-off-by: Nemental <[email protected]>

* style: linting and styling

Signed-off-by: Nemental <[email protected]>

* chore: trigger for pull request

Signed-off-by: Nemental <[email protected]>

* fix: push only if ref is master

Signed-off-by: Nemental <[email protected]>

* chore: output diff of generated README

Signed-off-by: Nemental <[email protected]>

* fix: push readme in pull request

Signed-off-by: Nemental <[email protected]>

* docs: role var description text

Signed-off-by: Nemental <[email protected]>

* fix: aar_doc roles path

Signed-off-by: Nemental <[email protected]>

* fix: git diff

Signed-off-by: Nemental <[email protected]>

* fix: fetch all history and changed diff branch

Signed-off-by: Nemental <[email protected]>

* fix: run diff only for pr

Signed-off-by: Nemental <[email protected]>

* fix: remove fetch-depth and switch to normal diff

Signed-off-by: Nemental <[email protected]>

* fix: remove diff and set push-branch

Signed-off-by: Nemental <[email protected]>

* fix: head_ref with default ref_name for push-branch

Signed-off-by: Nemental <[email protected]>

---------

Signed-off-by: Nemental <[email protected]>
Co-authored-by: Sebastian Gumprich <[email protected]>

.aar_doc.yml

@@ -0,0 +1,44 @@
+output_template: |
+  <!-- BEGIN_ANSIBLE_DOCS -->
+
+  ## Supported Operating Systems
+
+  {%- for platform in metadata.galaxy_info.platforms %}
+  - {{ platform.name }}
+    {%- if "versions" in platform %}
+    - {{ platform.versions | default([]) | join(', ') }}
+    {%- endif %}
+  {%- endfor %}
+
+  ## Role Variables
+  {% for entrypoint in argument_specs.keys() %}
+  {%- set path, options=entrypoint_options[entrypoint][0] -%}
+  {%- for name, details in options.items() |sort() %}
+  - `{{ name }}`
+    - Default: `{{ details.display_default }}`
+    - Description: {{ details.display_description }}
+    - Type: {{ details.display_type }}
+    - Required: {{ details.display_required }}
+  {%- endfor %}
+  {%- endfor %}
+
+  ## Dependencies
+
+  {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
+  {%- for dependency in metadata.dependencies %}
+  - {{ dependency }}
+  {%- endfor %}
+  {%- else %}
+
+  None.
+  {%- endif %}
+
+  ## Example Playbook
+
+  ```
+  - hosts: all
+    roles:
+      - name: {{ role }}
+  ```
+
+  <!-- END_ANSIBLE_DOCS -->

.github/workflows/roles-readme.yml

@@ -0,0 +1,47 @@
+---
+name: create roles readme
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [master]
+    paths:
+      - 'roles/**/meta/argument_specs.yml'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'roles/**/meta/argument_specs.yml'
+
+jobs:
+  readme:
+    name: create roles readme
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        roles:
+          - mysql_hardening
+          - nginx_hardening
+          - os_hardening
+          - ssh_hardening
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install aar_doc
+        run: pip3 install aar_doc
+
+      - name: Run aar_doc
+        run: aar_doc roles/${{ matrix.roles }} markdown
+
+      - name: Push README
+        uses: github-actions-x/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push-branch: ${{ github.head_ref ?? github.ref_name }}
+          commit-message: 'update ${{ matrix.roles }} readme'
+          files: roles/${{ matrix.roles }}/README.md
+          rebase: true

roles/ssh_hardening/meta/argument_specs.yml

@@ -221,7 +221,7 @@ argument_specs:
       ssh_client_hardening:
         default: true
         type: bool
-        description: '`false` to stop harden the client.'
+        description: Set to `false` to stop harden the client.
       ssh_client_compression:
         default: false
         type: bool
@@ -256,7 +256,7 @@ argument_specs:
       ssh_server_hardening:
         default: true
         type: bool
-        description: '`false` to stop harden the server.'
+        description: Set to `false` to stop harden the server.
       ssh_server_match_address:
         default: ''
         description: Introduces a conditional block. If all of the criteria on the