From 213b93ecf6c2d16e5d5ae0f06d144c136596e9c2 Mon Sep 17 00:00:00 2001
From: Ivan Dlugos <dlugos.ivan@gmail.com>
Date: Mon, 20 Oct 2025 16:48:45 +0200
Subject: [PATCH] docs(updater): Update authentication documentation for
 ssh-key and api-token inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update the updater README to accurately document both authentication inputs
that were added in v3.1.0:

- Fix api-token input: change from required:true to required:false
- Add comprehensive documentation for ssh-key input parameter
- Add usage examples showing ssh-key alone and combined with api-token
- Add Authentication section with three clear options and guidance
- Clarify that CI runs on PRs when using SSH keys for git operations

The documentation now reflects that both inputs are optional and can be used
independently or together, providing users clear guidance on which
authentication method to choose based on their requirements.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 updater/README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/updater/README.md b/updater/README.md
index a25f4e5..96cbfea 100644
--- a/updater/README.md
+++ b/updater/README.md
@@ -107,6 +107,28 @@ jobs:
           name: Cocoa SDK
           post-update-script: scripts/post-update.sh  # Receives args: $1=old version, $2=new version
           api-token: ${{ secrets.CI_DEPLOY_KEY }}
+
+  # Authentication with SSH deploy key (git operations via SSH, API via default token)
+  cocoa-ssh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: getsentry/github-workflows/updater@v3
+        with:
+          path: modules/sentry-cocoa
+          name: Cocoa SDK
+          ssh-key: ${{ secrets.CI_DEPLOY_KEY }}
+
+  # Authentication with both SSH key and API token (git via SSH, API via token)
+  # This is useful when you need CI to run on created PRs and use a deploy key
+  cocoa-ssh-and-token:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: getsentry/github-workflows/updater@v3
+        with:
+          path: modules/sentry-cocoa
+          name: Cocoa SDK
+          ssh-key: ${{ secrets.CI_DEPLOY_KEY }}
+          api-token: ${{ secrets.CI_GITHUB_TOKEN }}
 ```
 
 ## Inputs
@@ -153,11 +175,53 @@ jobs:
   * type: string
   * required: false
   * default: ''
-* `api-token`: Token for the repo. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`.
+* `api-token`: GitHub API token for repository operations. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`.
   If you provide the usual `${{ github.token }}`, no followup CI will run on the created PR.
-  If you want CI to run on the PRs created by the Updater, you need to provide custom user-specific auth token.
+  If you want CI to run on the PRs created by the Updater, you need to provide a custom user-specific auth token.
+  Not required if `ssh-key` is provided, but can be used together with `ssh-key` for GitHub API operations.
   * type: string
-  * required: true
+  * required: false
+  * default: ''
+* `ssh-key`: SSH private key for repository authentication (e.g., deploy key). Can be used alone or together with `api-token`.
+  When used alone, the action will use SSH for git operations and fall back to the default GitHub token for API operations.
+  When used with `api-token`, SSH is used for git operations and the token is used for GitHub API operations.
+  * type: string
+  * required: false
+  * default: ''
+
+## Authentication
+
+The updater supports multiple authentication methods. Choose based on your requirements:
+
+### Option 1: API Token Only (Default)
+
+```yaml
+api-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+* **Use when**: Standard GitHub token authentication is sufficient
+* **Limitation**: If using `${{ github.token }}`, CI workflows won't run on created PRs
+* **Solution**: Use a personal access token or GitHub App token to enable CI on PRs
+
+### Option 2: SSH Key Only
+
+```yaml
+ssh-key: ${{ secrets.CI_DEPLOY_KEY }}
+```
+
+* **Use when**: Repository access requires SSH (e.g., deploy keys)
+* **Behavior**: Git operations use SSH (CI will run on PRs since commits are made with SSH key), API operations use default GitHub token
+
+### Option 3: SSH Key + API Token (Recommended for Deploy Keys)
+
+```yaml
+ssh-key: ${{ secrets.CI_DEPLOY_KEY }}
+api-token: ${{ secrets.CI_GITHUB_TOKEN }}
+```
+
+* **Use when**: You need both deploy key access AND want to control the API token used for GitHub operations
+* **Behavior**: Git operations use SSH deploy key, API operations use provided token
+* **Benefits**: Full control over authentication for both git and API operations
 
 ### Post-Update Script Example