diff --git a/.github/workflows/roles-readme.yml b/.github/workflows/roles-readme.yml
new file mode 100644
index 00000000..1cecdbe5
--- /dev/null
+++ b/.github/workflows/roles-readme.yml
@@ -0,0 +1,41 @@
+---
+name: create roles readme
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [main]
+    paths:
+      - 'roles/*/meta/argument_specs.yml'
+      - 'roles/*/meta/main.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'roles/*/meta/argument_specs.yml'
+      - 'roles/*/meta/main.yml'
+jobs:
+  readme:
+    name: create roles readme
+    runs-on: ubuntu-latest
+    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 --config-file .aar_doc.yml . markdown
+
+      - name: Push README
+        if: github.event_name != 'pull_request'
+        uses: github-actions-x/commit@v2.9
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'update readme'
+          files: README.md
+          rebase: true