feat(kiloclaw): add GitHub machine user to secret catalog (#1074)

<!-- PR title format: type(scope): description — e.g., feat(auth): add
SSO login -->
<!-- Keep the title under 72 characters, use imperative mood, no
trailing period. -->

## Summary

- Add GitHub as a tool-category entry in the secret catalog with three
fields: Username, Email, and Personal Access Token
- Users can enter GitHub credentials directly in the Settings tab under
a new "Tools" section
- Boot script (`start-openclaw.sh`) configures `gh` CLI auth and `git`
identity on machine startup, and cleans up credentials on removal
- Inline security note recommends using a dedicated GitHub account with
a minimally-scoped fine-grained PAT


## Verification
## Validation

- **Username**: alphanumeric + hyphens, no leading/trailing/consecutive
hyphens (GitHub rules)
- **Email**: basic email format (`user@domain.tld`)
- **PAT**: classic (`ghp_`) or fine-grained (`github_pat_`) prefixes
only; OAuth/Actions tokens rejected with clear message

  ## Test plan

[x] `pnpm typecheck` — clean
[x] `pnpm lint` — clean
[x] `pnpm run format:check` — clean
[x] `pnpm --filter @kilocode/kiloclaw-secret-catalog test` — 54 tests
pass
[x] `pnpm --filter kiloclaw test` — 596 tests pass
[x] Manual: spun up a KiloClaw instance, configured GitHub credentials
(username: `kiloclaw-bot`, email: `kiloclaw-bot@example.com`, PAT:
fine-grained token), redeployed, verified `gh auth status` and `git
config --global user.name/email` set correctly on the machine
[x] Manual: removed GitHub credentials, redeployed, verified `gh auth
status` shows logged out and git identity cleared


## Visual Changes

- New **Tools** section appears between Channels and Google Account in
Settings tab
- GitHub entry shows Username, Email, and PAT fields with per-field
validation
- Shield icon + inline security note on the Save button row: recommends
dedicated account + scoped PAT with links to GitHub docs
- `helpText` below entry links to GitHub token settings

## Reviewer Notes
- **No OpenClaw config patching needed** — unlike channels
(Telegram/Discord/Slack) which are OpenClaw plugins requiring
`openclaw.json` patches, GitHub is system-level tooling. The boot script
configures `gh` CLI and `git` identity; the agent uses them via exec.
- **Credential cleanup on removal** — the `else` branch in
start-openclaw.sh runs `gh auth logout` and unsets git config so
removing credentials actually de-authenticates the machine (persistent
volume would otherwise retain stale creds).
- **`allFieldsRequired: true`** — intentional for the machine user use
case (committing code needs all three). A future read-only token-only
entry would be a separate catalog item.
- **`actionRowExtra` prop** — generic slot on `SecretEntrySection` for
injecting content on the button row. Currently only used for GitHub's
security note but available for future tool entries.

<!-- Optional: reviewer focus areas, edge cases, or context that helps
review quickly. -->

Author: St0rmz1

kiloclaw/AGENTS.md

@@ -172,6 +172,7 @@ Before submitting any change:
 2. Update tests in the same PR -- do not defer
 3. Do not reintroduce optional `userId` or `sandboxId` parameters (they are always required)
 4. If changing `start-openclaw.sh`, bump the cache bust in the Dockerfile
+5. If adding or changing user-facing features, add a changelog entry to `src/app/(app)/claw/components/changelog-data.ts` (newest first)
 
 ## Test Targets by Change Type
 

kiloclaw/Dockerfile

@@ -113,8 +113,8 @@ RUN mkdir -p /root/.openclaw \
     && mkdir -p /root/clawd/skills
 
 # Copy startup script
-# Build cache bust: 2026-03-11-v61-kilo-cli
-RUN echo "9"
+# Build cache bust: 2026-03-12-v62-github-machine-user
+RUN echo "10"
 COPY start-openclaw.sh /usr/local/bin/start-openclaw.sh
 COPY openclaw-pairing-list.js /usr/local/bin/openclaw-pairing-list.js
 COPY openclaw-device-pairing-list.js /usr/local/bin/openclaw-device-pairing-list.js

kiloclaw/packages/secret-catalog/src/__tests__/catalog.test.ts

@@ -37,7 +37,7 @@ describe('Secret Catalog', () => {
 
   describe('Icon validation', () => {
     it('all icon values are valid SecretIconKey members', () => {
-      const validIcons: Set<SecretIconKey> = new Set(['send', 'discord', 'slack', 'key']);
+      const validIcons: Set<SecretIconKey> = new Set(['send', 'discord', 'slack', 'key', 'github']);
       for (const entry of SECRET_CATALOG) {
         expect(validIcons.has(entry.icon)).toBe(true);
       }
@@ -108,6 +108,9 @@ describe('Secret Catalog', () => {
         'DISCORD_BOT_TOKEN',
         'SLACK_BOT_TOKEN',
         'SLACK_APP_TOKEN',
+        'GITHUB_TOKEN',
+        'GITHUB_USERNAME',
+        'GITHUB_EMAIL',
       ]);
 
       const catalogEnvVars = new Set(FIELD_KEY_TO_ENV_VAR.values());
@@ -122,6 +125,9 @@ describe('Secret Catalog', () => {
       expect(FIELD_KEY_TO_ENV_VAR.get('discordBotToken')).toBe('DISCORD_BOT_TOKEN');
       expect(FIELD_KEY_TO_ENV_VAR.get('slackBotToken')).toBe('SLACK_BOT_TOKEN');
       expect(FIELD_KEY_TO_ENV_VAR.get('slackAppToken')).toBe('SLACK_APP_TOKEN');
+      expect(FIELD_KEY_TO_ENV_VAR.get('githubToken')).toBe('GITHUB_TOKEN');
+      expect(FIELD_KEY_TO_ENV_VAR.get('githubUsername')).toBe('GITHUB_USERNAME');
+      expect(FIELD_KEY_TO_ENV_VAR.get('githubEmail')).toBe('GITHUB_EMAIL');
     });
 
     it('ENV_VAR_TO_FIELD_KEY is the exact reverse of FIELD_KEY_TO_ENV_VAR', () => {
@@ -136,6 +142,9 @@ describe('Secret Catalog', () => {
       expect(ENV_VAR_TO_FIELD_KEY.get('DISCORD_BOT_TOKEN')).toBe('discordBotToken');
       expect(ENV_VAR_TO_FIELD_KEY.get('SLACK_BOT_TOKEN')).toBe('slackBotToken');
       expect(ENV_VAR_TO_FIELD_KEY.get('SLACK_APP_TOKEN')).toBe('slackAppToken');
+      expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_TOKEN')).toBe('githubToken');
+      expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_USERNAME')).toBe('githubUsername');
+      expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_EMAIL')).toBe('githubEmail');
     });
   });
 
@@ -160,6 +169,9 @@ describe('Secret Catalog', () => {
       expect(FIELD_KEY_TO_ENTRY.get('discordBotToken')?.id).toBe('discord');
       expect(FIELD_KEY_TO_ENTRY.get('slackBotToken')?.id).toBe('slack');
       expect(FIELD_KEY_TO_ENTRY.get('slackAppToken')?.id).toBe('slack');
+      expect(FIELD_KEY_TO_ENTRY.get('githubToken')?.id).toBe('github');
+      expect(FIELD_KEY_TO_ENTRY.get('githubUsername')?.id).toBe('github');
+      expect(FIELD_KEY_TO_ENTRY.get('githubEmail')?.id).toBe('github');
     });
   });
 
@@ -172,9 +184,15 @@ describe('Secret Catalog', () => {
       expect(channels[2].id).toBe('slack');
     });
 
-    it('returns empty array for categories with no entries', () => {
+    it('returns all tool entries sorted by order', () => {
       const tools = getEntriesByCategory('tool');
-      expect(tools).toEqual([]);
+      expect(tools.length).toBe(1);
+      expect(tools[0].id).toBe('github');
+    });
+
+    it('returns empty array for categories with no entries', () => {
+      const providers = getEntriesByCategory('provider');
+      expect(providers).toEqual([]);
     });
   });
 
@@ -188,8 +206,16 @@ describe('Secret Catalog', () => {
       expect(keys.size).toBe(4);
     });
 
-    it('returns empty set for categories with no entries', () => {
+    it('returns all tool field keys', () => {
       const keys = getFieldKeysByCategory('tool');
+      expect(keys).toContain('githubToken');
+      expect(keys).toContain('githubUsername');
+      expect(keys).toContain('githubEmail');
+      expect(keys.size).toBe(3);
+    });
+
+    it('returns empty set for categories with no entries', () => {
+      const keys = getFieldKeysByCategory('provider');
       expect(keys.size).toBe(0);
     });
   });
@@ -272,6 +298,56 @@ describe('Secret Catalog', () => {
       expect(validateFieldValue('xapp-short', pattern)).toBe(false);
     });
 
+    it('accepts valid GitHub usernames', () => {
+      const pattern = '^[a-zA-Z\\d](?:[a-zA-Z\\d]|-(?=[a-zA-Z\\d])){0,38}$';
+      expect(validateFieldValue('octocat', pattern)).toBe(true);
+      expect(validateFieldValue('my-bot-user', pattern)).toBe(true);
+      expect(validateFieldValue('a', pattern)).toBe(true);
+      expect(validateFieldValue('User123', pattern)).toBe(true);
+    });
+
+    it('rejects invalid GitHub usernames', () => {
+      const pattern = '^[a-zA-Z\\d](?:[a-zA-Z\\d]|-(?=[a-zA-Z\\d])){0,38}$';
+      expect(validateFieldValue('-octocat', pattern)).toBe(false);
+      expect(validateFieldValue('octocat-', pattern)).toBe(false);
+      expect(validateFieldValue('my--name', pattern)).toBe(false);
+      expect(validateFieldValue('my_name', pattern)).toBe(false);
+      expect(validateFieldValue('user name', pattern)).toBe(false);
+    });
+
+    it('accepts valid email addresses', () => {
+      const pattern = '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$';
+      expect(validateFieldValue('bot@example.com', pattern)).toBe(true);
+      expect(validateFieldValue('my-bot@my-org.io', pattern)).toBe(true);
+    });
+
+    it('rejects invalid email addresses', () => {
+      const pattern = '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$';
+      expect(validateFieldValue('notanemail', pattern)).toBe(false);
+      expect(validateFieldValue('missing@domain', pattern)).toBe(false);
+      expect(validateFieldValue('has space@example.com', pattern)).toBe(false);
+    });
+
+    it('accepts valid GitHub classic tokens (ghp_)', () => {
+      const pattern = '^(ghp_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})$';
+      expect(validateFieldValue('ghp_' + 'A'.repeat(36), pattern)).toBe(true);
+      expect(validateFieldValue('ghp_' + 'abcDEF123456'.repeat(5), pattern)).toBe(true);
+    });
+
+    it('accepts valid GitHub fine-grained tokens (github_pat_)', () => {
+      const pattern = '^(ghp_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})$';
+      expect(validateFieldValue('github_pat_' + 'A'.repeat(22), pattern)).toBe(true);
+      expect(validateFieldValue('github_pat_' + 'abc_DEF_123'.repeat(5), pattern)).toBe(true);
+    });
+
+    it('rejects invalid GitHub tokens', () => {
+      const pattern = '^(ghp_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})$';
+      expect(validateFieldValue('ghp_short', pattern)).toBe(false);
+      expect(validateFieldValue('github_pat_short', pattern)).toBe(false);
+      expect(validateFieldValue('gho_invalidprefix', pattern)).toBe(false);
+      expect(validateFieldValue('invalid', pattern)).toBe(false);
+    });
+
     it('rejects empty strings', () => {
       const pattern = '^\\d{8,}:[A-Za-z0-9_-]{30,50}$';
       expect(validateFieldValue('', pattern)).toBe(false);
@@ -311,6 +387,21 @@ describe('Secret Catalog', () => {
       expect(slack?.fields.map(f => f.key)).toEqual(['slackBotToken', 'slackAppToken']);
     });
 
+    it('github entry has allFieldsRequired set', () => {
+      const github = SECRET_CATALOG_MAP.get('github');
+      expect(github?.allFieldsRequired).toBe(true);
+    });
+
+    it('github entry has exactly 3 fields', () => {
+      const github = SECRET_CATALOG_MAP.get('github');
+      expect(github?.fields.length).toBe(3);
+      expect(github?.fields.map(f => f.key)).toEqual([
+        'githubUsername',
+        'githubEmail',
+        'githubToken',
+      ]);
+    });
+
     it('telegram and discord do not have allFieldsRequired', () => {
       expect(SECRET_CATALOG_MAP.get('telegram')?.allFieldsRequired).toBeFalsy();
       expect(SECRET_CATALOG_MAP.get('discord')?.allFieldsRequired).toBeFalsy();

kiloclaw/packages/secret-catalog/src/catalog.ts

@@ -89,6 +89,50 @@ const SECRET_CATALOG_RAW = [
     helpText: 'Get tokens from Slack App Management. Both Bot Token and App Token are required.',
     helpUrl: 'https://api.slack.com/apps',
   },
+  {
+    id: 'github',
+    label: 'GitHub',
+    category: 'tool',
+    icon: 'github',
+    order: 1,
+    allFieldsRequired: true,
+    fields: [
+      {
+        key: 'githubUsername',
+        label: 'Username',
+        placeholder: 'my-bot-user',
+        placeholderConfigured: 'Enter new username to replace',
+        envVar: 'GITHUB_USERNAME',
+        validationPattern: '^[a-zA-Z\\d](?:[a-zA-Z\\d]|-(?=[a-zA-Z\\d])){0,38}$',
+        validationMessage:
+          'GitHub usernames can only contain alphanumeric characters and hyphens, and cannot start or end with a hyphen.',
+        maxLength: 39,
+      },
+      {
+        key: 'githubEmail',
+        label: 'Email',
+        placeholder: 'bot@example.com',
+        placeholderConfigured: 'Enter new email to replace',
+        envVar: 'GITHUB_EMAIL',
+        validationPattern: '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$',
+        validationMessage: 'Enter a valid email address.',
+        maxLength: 254,
+      },
+      {
+        key: 'githubToken',
+        label: 'Personal Access Token',
+        placeholder: 'github_pat_...',
+        placeholderConfigured: 'Enter new token to replace',
+        envVar: 'GITHUB_TOKEN',
+        validationPattern: '^(ghp_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})$',
+        validationMessage:
+          'Personal access tokens only: classic (ghp_) or fine-grained (github_pat_). OAuth and Actions tokens are not supported.',
+        maxLength: 300,
+      },
+    ],
+    helpText: 'Manage your token from the GitHub developer settings.',
+    helpUrl: 'https://github.com/settings/tokens?type=beta',
+  },
 ] as const satisfies readonly SecretCatalogEntry[];
 
 // Runtime validation — fails fast at module load if catalog data is malformed

kiloclaw/packages/secret-catalog/src/types.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 export const SecretCategorySchema = z.enum(['channel', 'tool', 'provider', 'custom']);
 
-export const SecretIconKeySchema = z.enum(['send', 'discord', 'slack', 'key']);
+export const SecretIconKeySchema = z.enum(['send', 'discord', 'slack', 'key', 'github']);
 
 /**
  * How a secret is delivered to the OpenClaw process at runtime.

kiloclaw/src/routes/kiloclaw.test.ts

@@ -11,7 +11,7 @@ describe('buildConfiguredSecrets', () => {
 
   it('returns all entries as false when no secrets are configured', () => {
     const result = buildConfiguredSecrets({});
-    expect(result).toEqual({ telegram: false, discord: false, slack: false });
+    expect(result).toEqual({ telegram: false, discord: false, slack: false, github: false });
   });
 
   it('marks entry as configured when encryptedSecrets has the env var key', () => {
@@ -60,17 +60,39 @@ describe('buildConfiguredSecrets', () => {
     expect(result.slack).toBe(true);
   });
 
+  it('marks github as configured only when all three fields are present', () => {
+    const partial = buildConfiguredSecrets({
+      encryptedSecrets: { GITHUB_TOKEN: envelope },
+    });
+    expect(partial.github).toBe(false);
+
+    const twoOfThree = buildConfiguredSecrets({
+      encryptedSecrets: { GITHUB_TOKEN: envelope, GITHUB_USERNAME: envelope },
+    });
+    expect(twoOfThree.github).toBe(false);
+
+    const full = buildConfiguredSecrets({
+      encryptedSecrets: {
+        GITHUB_TOKEN: envelope,
+        GITHUB_USERNAME: envelope,
+        GITHUB_EMAIL: envelope,
+      },
+    });
+    expect(full.github).toBe(true);
+  });
+
   it('does not use legacy channels fallback for non-channel category entries', () => {
     // If a non-channel entry were added, legacy channels storage should not count
     // This tests that CHANNEL_FIELD_KEYS gate is effective — a key not in the
     // channel category won't match even if present in config.channels
     const result = buildConfiguredSecrets({
       channels: { someNonChannelKey: envelope },
     });
-    // All current entries are channels, so this just verifies no crash
+    // Channel entries should be false, tool entries unaffected by legacy channels
     expect(result.telegram).toBe(false);
     expect(result.discord).toBe(false);
     expect(result.slack).toBe(false);
+    expect(result.github).toBe(false);
   });
 
   it('uses entry.id as the result key', () => {
@@ -79,7 +101,7 @@ describe('buildConfiguredSecrets', () => {
     expect(keys).toContain('telegram');
     expect(keys).toContain('discord');
     expect(keys).toContain('slack');
-    expect(keys).toHaveLength(3);
+    expect(keys).toHaveLength(4);
   });
 
   it('treats null values as not configured', () => {

kiloclaw/start-openclaw.sh

@@ -212,6 +212,34 @@ if [ "${KILOCLAW_KILO_CLI:-}" = "true" ]; then
     echo "Kilo CLI auto-configuration enabled"
 fi
 
+# ============================================================
+# GITHUB CONFIGURATION
+# ============================================================
+if [ -n "${GITHUB_TOKEN:-}" ]; then
+    echo "Configuring GitHub access..."
+
+    echo "$GITHUB_TOKEN" | gh auth login --with-token 2>/dev/null \
+        && gh auth setup-git 2>/dev/null \
+        && echo "gh CLI authenticated" \
+        || echo "WARNING: gh auth login failed"
+
+    if [ -n "${GITHUB_USERNAME:-}" ]; then
+        git config --global user.name "$GITHUB_USERNAME"
+        echo "git user.name set to $GITHUB_USERNAME"
+    fi
+    if [ -n "${GITHUB_EMAIL:-}" ]; then
+        git config --global user.email "$GITHUB_EMAIL"
+        echo "git user.email set to $GITHUB_EMAIL"
+    fi
+else
+    # Clean up any previously stored credentials from the persistent volume
+    # so that removing GitHub secrets actually de-authenticates the machine.
+    gh auth logout --hostname github.com 2>/dev/null || true
+    git config --global --unset user.name 2>/dev/null || true
+    git config --global --unset user.email 2>/dev/null || true
+    echo "GitHub: not configured (credentials cleared)"
+fi
+
 # ============================================================
 # PATCH CONFIG (channels, gateway auth, exec policy)
 # ============================================================

src/app/(app)/claw/components/SecretEntrySection.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import type React from 'react';
 import { useState } from 'react';
 import { AlertCircle, Save, X } from 'lucide-react';
 import { toast } from 'sonner';
@@ -22,12 +23,14 @@ export function SecretEntrySection({
   mutations,
   onSecretsChanged,
   isDirty,
+  actionRowExtra,
 }: {
   entry: SecretCatalogEntry;
   configured: boolean;
   mutations: ClawMutations;
   onSecretsChanged?: (entryId: string) => void;
   isDirty: boolean;
+  actionRowExtra?: React.ReactNode;
 }) {
   const [tokens, setTokens] = useState<Record<string, string>>({});
   const [formatError, setFormatError] = useState<string | null>(null);
@@ -156,6 +159,7 @@ export function SecretEntrySection({
             Remove
           </Button>
         )}
+        {actionRowExtra}
       </div>
 
       <p className="text-muted-foreground text-xs">