feat: use GitHub App instead of PAT for PR submissions

Replace BOT_TOKEN (personal access token) with a proper GitHub App:
- uses actions/create-github-app-token@v1 to generate short-lived
  tokens scoped to the target skill repo
- PRs authored by ovos-localize[bot], not a personal account
- App needs: Contents (read/write) + Pull requests (read/write)
- Config: LOCALIZE_APP_ID (variable) + LOCALIZE_APP_PRIVATE_KEY (secret)

Updated docs/deployment.md with step-by-step GitHub App setup guide.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JarbasAl

.github/workflows/submit_translation.yml

@@ -19,12 +19,21 @@ jobs:
           echo "branch=${{ github.event.client_payload.branch }}" >> "$GITHUB_OUTPUT"
           echo "author=${{ github.event.client_payload.author }}" >> "$GITHUB_OUTPUT"
 
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.LOCALIZE_APP_ID }}
+          private-key: ${{ secrets.LOCALIZE_APP_PRIVATE_KEY }}
+          owner: ${{ steps.payload.outputs.org }}
+          repositories: ${{ steps.payload.outputs.repo }}
+
       - name: Checkout target repo
         uses: actions/checkout@v4
         with:
           repository: ${{ steps.payload.outputs.org }}/${{ steps.payload.outputs.repo }}
           ref: ${{ steps.payload.outputs.branch }}
-          token: ${{ secrets.BOT_TOKEN }}
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Create branch and commit
         env:
@@ -43,8 +52,8 @@ jobs:
           # Write content (base64 decoded)
           echo "$CONTENT" | base64 -d > "$FILE_PATH"
 
-          git config user.name "OVOS Localize Bot"
-          git config user.email "noreply@openvoiceos.org"
+          git config user.name "ovos-localize[bot]"
+          git config user.email "ovos-localize[bot]@users.noreply.github.com"
           git add "$FILE_PATH"
           git commit -m "translate(${LANG}): update ${FILE_KEY}
 
@@ -57,7 +66,7 @@ Submitted by @${AUTHOR} via OVOS Localize"
 
       - name: Create Pull Request
         env:
-          GH_TOKEN: ${{ secrets.BOT_TOKEN }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
           ORG: ${{ steps.payload.outputs.org }}
           REPO: ${{ steps.payload.outputs.repo }}
           BASE: ${{ steps.payload.outputs.branch }}

docs/deployment.md

@@ -10,44 +10,66 @@ In the repo settings → Pages → Source: deploy from `dev` branch, root `/`.
 
 The SPA (`index.html`) and data files (`data/`) are served directly.
 
-### 2. Configure the bot token
-
-Translation submissions work via a GitHub Action that creates PRs on behalf of users. This requires a **bot token** stored as a repository secret.
-
-**Create a fine-grained PAT for the bot:**
-1. Go to [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
-2. Name: `ovos-localize-bot`
-3. Resource owner: `OpenVoiceOS`
-4. Repository access: **All repositories** (the bot needs to create branches + PRs on any skill repo)
-5. Permissions:
-   - **Contents**: Read and write (to commit files)
+### 2. Create a GitHub App
+
+Translation submissions work via a GitHub Action that creates PRs on skill repos. This uses a **GitHub App** (not a personal token) so PRs come from a bot identity.
+
+**Create the App:**
+1. Go to **github.com/organizations/OpenVoiceOS/settings/apps/new**
+2. Fill in:
+   - **Name**: `ovos-localize`
+   - **Homepage URL**: `https://openvoiceos.github.io/ovos-localize/`
+   - **Webhook**: uncheck "Active" (not needed)
+3. **Permissions → Repository permissions**:
+   - **Contents**: Read and write (to create branches and commit files)
    - **Pull requests**: Read and write (to open PRs)
-6. Generate and copy the token
-
-**Add as repo secret:**
-1. Go to the ovos-localize repo → Settings → Secrets → Actions
-2. New repository secret: `BOT_TOKEN` = the token you just created
+4. **Where can this app be installed?**: "Only on this account"
+5. Click **Create GitHub App**
+6. Note the **App ID** shown on the settings page
+
+**Generate a private key:**
+1. On the App settings page, scroll to "Private keys"
+2. Click **Generate a private key** — downloads a `.pem` file
+
+**Install the App:**
+1. Go to the App's page → **Install App**
+2. Select the **OpenVoiceOS** organization
+3. Choose **All repositories** (the bot needs access to any skill repo)
+4. Click **Install**
+
+**Add to the ovos-localize repo:**
+1. Settings → **Variables → Actions** → New variable:
+   - Name: `LOCALIZE_APP_ID`, Value: the App ID from step 6
+2. Settings → **Secrets → Actions** → New secret:
+   - Name: `LOCALIZE_APP_PRIVATE_KEY`, Value: paste the entire contents of the `.pem` file
 
 ### 3. How it works
 
 ```
 User (browser)                    GitHub
-─────────────                    ──────
+──────────────                    ──────
 1. Edit translation
 2. Click "Submit"
 3. POST /repos/OpenVoiceOS/     ──→  repository_dispatch event
    ovos-localize/dispatches          (event_type: submit-translation)
                                       │
                                       ▼
                                  submit_translation.yml runs:
-                                 - Checks out target skill repo
-                                 - Creates translate/{lang}/{file} branch
-                                 - Commits the translated file
-                                 - Opens PR to dev branch
-                                 - PR body mentions @username
+                                 ├── actions/create-github-app-token
+                                 │   generates a short-lived token
+                                 │   scoped to the target skill repo
+                                 ├── Checks out target skill repo
+                                 ├── Creates translate/{lang}/{file} branch
+                                 ├── Commits as ovos-localize[bot]
+                                 └── Opens PR to dev branch
+                                     (mentions @username in body)
 ```
 
-The user's token only needs permission to trigger dispatches on ovos-localize. The `BOT_TOKEN` secret handles the actual repo writes and PR creation.
+**Key properties:**
+- The GitHub App token is **short-lived** (expires in 1 hour) and scoped to the single target repo
+- PRs appear as authored by `ovos-localize[bot]` — not tied to any personal account
+- No personal tokens or service accounts needed for the bot side
+- The user's token only needs permission to trigger `repository_dispatch` on the ovos-localize repo
 
 ### 4. Daily data refresh
 
@@ -63,3 +85,10 @@ Users create a fine-grained PAT scoped to the `ovos-localize` repo only, with:
 - **Actions**: Read and write (to trigger `repository_dispatch`)
 
 This is the minimum permission needed. Users never get write access to skill repos.
+
+### 6. Summary of secrets/variables
+
+| Name | Type | Where | Purpose |
+|------|------|-------|---------|
+| `LOCALIZE_APP_ID` | Variable | ovos-localize repo | GitHub App ID |
+| `LOCALIZE_APP_PRIVATE_KEY` | Secret | ovos-localize repo | GitHub App private key (.pem) |