From 0a438d0731bd1187a2b7bd76230e3ba8d61a7ca1 Mon Sep 17 00:00:00 2001
From: Enguerrand Allamel <enguerrand.allamel@ledger.fr>
Date: Fri, 13 Sep 2024 10:53:01 +0200
Subject: [PATCH] chore: rework action readme

---
 actions/attest/README.md         | 12 ++++++++----
 actions/sign-blob/README.md      | 12 ++++++++----
 actions/sign-container/README.md | 12 ++++++++----
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/actions/attest/README.md b/actions/attest/README.md
index 9981a35..53962ae 100644
--- a/actions/attest/README.md
+++ b/actions/attest/README.md
@@ -1,4 +1,4 @@
-# Action: attest
+# GitHub Action: `attest`
 
 <!-- action-docs-description source="action.yml" -->
 ## Description
@@ -9,6 +9,9 @@ This action is used to generate a provenance file and to sign it (attestation in
 ## Usage
 
 ### Permissions
+
+To enable this action to work properly, ensure the following permissions are set in your workflow:
+
 ```yaml
 permissions:
     id-token: write
@@ -16,6 +19,9 @@ permissions:
 ```
 
 ### Example Workflow
+
+Here's how you can use the `attest` action within your workflow:
+
 ```yaml
 jobs:
   release:
@@ -44,8 +50,6 @@ jobs:
 <!-- action-docs-outputs source="action.yml" -->
 
 
-<!-- action-docs-runs source="action.yml" -->
 ## Runs
 
-This action is a `composite` action.
-<!-- action-docs-runs source="action.yml" -->
\ No newline at end of file
+This action is a **composite action**, which allows us to combine multiple workflow steps into a single, reusable action. This promotes modularity and simplifies our workflows.
\ No newline at end of file
diff --git a/actions/sign-blob/README.md b/actions/sign-blob/README.md
index eccdaaf..1f8420e 100644
--- a/actions/sign-blob/README.md
+++ b/actions/sign-blob/README.md
@@ -1,4 +1,4 @@
-# Action: sign-blob
+# GitHub Action: `sign-blob`
 
 <!-- action-docs-description source="action.yml" -->
 ## Description
@@ -9,12 +9,18 @@ This action is used to sign blobs in keyless mode based on Github OIDC token.
 ## Usage
 
 ### Permissions
+
+To enable this action to work properly, ensure the following permissions are set in your workflow:
+
 ```yaml
 permissions:
     id-token: write
 ```
 
 ### Example Workflow
+
+Here's how you can use the `sign-blob` action within your workflow:
+
 ```yaml
 jobs:
   release:
@@ -40,8 +46,6 @@ jobs:
 <!-- action-docs-outputs source="action.yml" -->
 
 
-<!-- action-docs-runs source="action.yml" -->
 ## Runs
 
-This action is a `composite` action.
-<!-- action-docs-runs source="action.yml" -->
\ No newline at end of file
+This action is a **composite action**, which allows us to combine multiple workflow steps into a single, reusable action. This promotes modularity and simplifies our workflows.
diff --git a/actions/sign-container/README.md b/actions/sign-container/README.md
index 171bc6a..9a61360 100644
--- a/actions/sign-container/README.md
+++ b/actions/sign-container/README.md
@@ -1,4 +1,4 @@
-# Action: sign-blob
+# GitHub Action: `sign-container`
 
 <!-- action-docs-description source="action.yml" -->
 ## Description
@@ -9,12 +9,18 @@ This action is used to sign a container image with a list of tags in keyless mod
 ## Usage
 
 ### Permissions
+
+To enable this action to work properly, ensure the following permissions are set in your workflow:
+
 ```yaml
 permissions:
     id-token: write
 ```
 
 ### Example Workflow
+
+Here's how you can use the `sign-container` action within your workflow:
+
 ```yaml
 jobs:
   release:
@@ -42,8 +48,6 @@ jobs:
 <!-- action-docs-outputs source="action.yml" -->
 
 
-<!-- action-docs-runs source="action.yml" -->
 ## Runs
 
-This action is a `composite` action.
-<!-- action-docs-runs source="action.yml" -->
\ No newline at end of file
+This action is a **composite action**, which allows us to combine multiple workflow steps into a single, reusable action. This promotes modularity and simplifies our workflows.
\ No newline at end of file