chore: improve jfrog-login documentation (#38)

* chore: improve jfrog-login documentation - remove the `action-docs` currently not used * chore(jfrog-login): update documenation and make style simpler * chore(jfrog-login): remove blank lines * chore(jfrog-login: remove blank lines --------- Co-authored-by: Enguerrand Allamel <[email protected]>
LedgerHQ · Sep 13, 2024 · a0a4869 · a0a4869
1 parent 74053fc
commit a0a4869
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 19 deletions.
diff --git a/actions/jfrog-login/README.md b/actions/jfrog-login/README.md
@@ -1,20 +1,29 @@
-# Action: jfrog-login
+# GitHub Action: `jfrog-login`
 
 <!-- action-docs-description source="action.yml" -->
 ## Description
 
-This action is used to login to the JFrog Plateform of Ledger (Artifactory, Xray, etc.).
+The `jfrog-login` GitHub Action facilitates a secure login to Ledger's JFrog platform, which includes services such as **Artifactory** and **Xray**. By using OIDC authentication, this action ensures secure access to manage artifacts, perform security scans, and interact with the JFrog APIs and CLI without handling sensitive credentials manually.
+This action is designed for seamless integration within Ledger's CI/CD pipeline, allowing developers to securely interact with JFrog services while automating critical parts of the software supply chain.
 <!-- action-docs-description source="action.yml" -->
 
 ## Usage
 
-### Permissions
+### Required Permissions
+
+To enable this action to work properly, ensure the following permissions are set in your workflow:
+
 ```yaml
 permissions:
-    id-token: write
+  id-token: write
 ```
 
+This grants the action permission to generate the OIDC token required for authentication with JFrog.
+
 ### Example Workflow
+
+Here's how you can use the `jfrog-login` action within your workflow:
+
 ```yaml
 jobs:
   release:
@@ -25,22 +34,21 @@ jobs:
         uses: LedgerHQ/actions-security/actions/jfrog-login@actions/jfrog-login-1
 ```
 
-## Inputs
-This actions require no inputs.
-
 <!-- action-docs-outputs source="action.yml" -->
 ## Outputs
 
 | name | description |
 | --- | --- |
-| `oidc-token` | <p>From JFrog CLI: JFrog OIDC token generated by the Setup JFrog CLI when setting oidc-provider-name.</p> |
-| `oidc-user` | <p>From JFrog CLI: JFrog OIDC username from the OIDC token generated by the Setup JFrog CLI when setting oidc-provider-name.</p> |
-| `jfrog-url` | <p>Jfrog URL to be used for the JFrog API / CLI</p> |
+| `oidc-token` | <p>OIDC token generated by JFrog CLI for secure API/CLI interactions, using the Setup JFrog CLI step with the configured oidc-provider-name.</p> |
+| `oidc-user` | <p>Username extracted from the OIDC token during authentication.</p> |
+| `jfrog-url` | <p>Base URL of Ledger's JFrog platform to be used for subsequent API/CLI operations.</p> |
 <!-- 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" -->
+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.
+
+## Additional Information
+
+- This action securely manages the OIDC-based login for Ledger's JFrog platform, removing the need for manual credential handling.
+- Ensure your GitHub repository and workflows are configured to use OIDC for maximum security and efficiency.
diff --git a/actions/jfrog-login/action.yml b/actions/jfrog-login/action.yml
@@ -1,16 +1,18 @@
-name: "[Ledger Security] Login to JFrog"
+name: "[Ledger Security] JFrog Login"
 author: LedgerHQ
-description: "This action is used to login to the JFrog Plateform of Ledger (Artifactory, Xray, etc.)."
+description: |
+  The `jfrog-login` GitHub Action facilitates a secure login to Ledger's JFrog platform, which includes services such as **Artifactory** and **Xray**. By using OIDC authentication, this action ensures secure access to manage artifacts, perform security scans, and interact with the JFrog APIs and CLI without handling sensitive credentials manually.
+  This action is designed for seamless integration within Ledger's CI/CD pipeline, allowing developers to securely interact with JFrog services while automating critical parts of the software supply chain.
 
 outputs:
   oidc-token:
-    description: "From JFrog CLI: JFrog OIDC token generated by the Setup JFrog CLI when setting oidc-provider-name."
+    description: "OIDC token generated by JFrog CLI for secure API/CLI interactions, using the Setup JFrog CLI step with the configured oidc-provider-name."
     value: ${{ steps.setup-jfrog-cli.outputs.oidc-token }}
   oidc-user:
-    description: "From JFrog CLI: JFrog OIDC username from the OIDC token generated by the Setup JFrog CLI when setting oidc-provider-name."
+    description: "Username extracted from the OIDC token during authentication."
     value: ${{ steps.setup-jfrog-cli.outputs.oidc-user }}
   jfrog-url:
-    description: "Jfrog URL to be used for the JFrog API / CLI"
+    description: "Base URL of Ledger's JFrog platform to be used for subsequent API/CLI operations."
     value: "https://jfrog.ledgerlabs.net"
 
 runs: