From 92878b715f5a4a6e7a1730b398f4eb9d2a2431f9 Mon Sep 17 00:00:00 2001
From: Danilo Pianini <danilo.pianini@unibo.it>
Date: Thu, 16 Nov 2023 12:16:42 +0100
Subject: [PATCH] docs: update readme

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1ff8317..9646305 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,69 @@
-# true-yaml-actions
-A GitHub action that adds support for YAML anchors and merge keys in GitHub Actions
+# True YAML Actions
+
+I gave up hope of seeing [actions/runner#1182](https://github.com/actions/runner/issues/1182) fixed within my lifespan¹.
+I thus decided to write a very simple composite GitHub action that adds support for YAML anchors and merge keys in GitHub Actions.
+
+## How to use it
+
+Write your workflows into `.github/real-workflows`,
+freely using merge keys (`<<:`) and anchors (`*`),
+but writing all your anchors definitions in a header document,
+then write the real workflow separated by `---`, like this:
+
+```yaml
+anchor: &anchor
+  name: Test running on ${{github.repository}}
+  run: echo Commit ${{github.sha}} seems to be working
+
+---
+
+name: Test this action
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Test running on ${{github.repository}}
+        run: echo Commit ${{github.sha}} seems to be working
+      - <<: *anchor
+        run: echo Test merge keys
+      - *anchor
+```
+
+Now, create an additional workflow in `.github/workflows/autogen.yaml`
+(of course pick the name you like the most, the important thing is the workflow location)
+that looks like this: 
+
+```yaml
+name: Generate workflows
+
+on:
+  push:
+
+jobs:
+  generate-workflows:
+    permissions:
+      actions: write
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run locally
+        uses: 'DanySK/true-yaml-actions@master'
+        with:
+          token: ${{ github.token }}
+```
+
+If you want your updated workflows to trigger a new workflow,
+you must generate a new token with `workflows:write` permissions and use that in place of `${{ github.token }}`.
+
+That's it.
+
+![image](https://github.com/DanySK/true-yaml-actions/assets/1991673/ed6631c0-22a7-41bf-bff3-603aa7dfc434)
+
+
+1. I also honestly believe that GitHub Actions was built bottom-up, has great design flaws, and deserves a v2, but still, it's the best thing we have, so I can't help but love it ❤️