ci: GitHub App and sdk-bot environment for the automation #7

Sub-issue of #5. This needs an org admin. It is the same setup as the ai-openshell-sdk-go App and its sdk-bot environment on sdk-go (ai-openshell/sdk-go#2), repeated for this repository.

Why

The automation in #5 opens a PR for each new core release tag and keeps a drift issue up to date. Release tagging will use the same identity later. Pushes and PRs made with GITHUB_TOKEN don't trigger workflows, so bump PRs would get no CI. A personal token would make one person the last pusher, and main-integrity then wouldn't let them approve the PR. A GitHub App with narrow permissions avoids both problems.

Steps

1. Create the App

Go to ai-openshell → Settings → Developer settings → GitHub Apps → New GitHub App.

The App doesn't need Workflows permission: no automation edits files under .github/workflows/. Each workflow narrows its token further per job.

2. Generate a private key and note the Client ID

On the App's General page:

• Copy the Client ID, which starts with Iv. The workflows use the Client ID, not the numeric App ID.
• Under Private keys, click Generate a private key. That downloads a .pem file.

3. Install the App on sdk-python only

Install App → ai-openshell → Only select repositories → sdk-python.

4. Create the sdk-bot environment

Only main may deploy to the environment. That way a workflow on a pushed branch or a fork PR can't read the secrets or mint a bot token. This matches sdk-go.

In the UI: sdk-python → Settings → Environments → New environment, name it sdk-bot. Under Deployment branches and tags, choose Selected branches and tags and add the branch rule main. Don't add required reviewers, because the scheduled jobs run unattended.

Or with gh:

gh api -X PUT repos/ai-openshell/sdk-python/environments/sdk-bot \
  -F 'deployment_branch_policy[protected_branches]=false' \
  -F 'deployment_branch_policy[custom_branch_policies]=true'
gh api -X POST repos/ai-openshell/sdk-python/environments/sdk-bot/deployment-branch-policies \
  -f name=main -f type=branch

5. Add the two environment secrets

They are environment secrets on sdk-bot, not repository secrets.

gh secret set SDK_BOT_CLIENT_ID --repo ai-openshell/sdk-python --env sdk-bot --body '<client-id>'
gh secret set SDK_BOT_PRIVATE_KEY --repo ai-openshell/sdk-python --env sdk-bot < ai-openshell-sdk-python.*.private-key.pem

Then delete the local .pem file. If the key is ever needed again, generate a new one on the App page and revoke the old one.

6. Check the setup

gh api repos/ai-openshell/sdk-python/environments/sdk-bot \
  --jq '.deployment_branch_policy'
# {"custom_branch_policies":true,"protected_branches":false}
gh api repos/ai-openshell/sdk-python/environments/sdk-bot/deployment-branch-policies \
  --jq '.branch_policies[].name'
# main
gh secret list --repo ai-openshell/sdk-python --env sdk-bot
# SDK_BOT_CLIENT_ID, SDK_BOT_PRIVATE_KEY

The first real use comes when #5 lands: core-watch should open a bump PR as ai-openshell-sdk-python[bot], with CI running on it.

Notes

• Rulesets: the org rulesets dco and main-integrity cover only the default branch. The bot pushes to core/<tag> branches and opens PRs into main, so it needs no bypass. Its commits carry Signed-off-by, so DCO passes.
• Reusing the sdk-go App: adding sdk-python to the existing ai-openshell-sdk-go installation would also work. That needs the same environment and secrets, with a new private key for that App. A separate App keeps each repository's credentials independent and its bot name accurate, so please create the new one unless there's a reason not to.
• Later: the PyPI publishing environment is a separate issue. It uses trusted publishing (OIDC), not a secret.

Done when

• The ai-openshell-sdk-python App exists with the permissions above and is installed on sdk-python only.
• The sdk-bot environment exists, and only main can deploy to it.
• SDK_BOT_CLIENT_ID and SDK_BOT_PRIVATE_KEY are set as sdk-bot environment secrets.