100 lines
3.5 KiB
Markdown
100 lines
3.5 KiB
Markdown
# Tobserver Agent Setup
|
|
|
|
Use this reference before first use and whenever SSH authentication, branch protection, AGit submission, or helper installation changes.
|
|
|
|
## Security model
|
|
|
|
The same Codeberg account, `oibot`, creates AGit pull requests and later performs a human web merge. Safety therefore depends on two separate capabilities:
|
|
|
|
- SSH may submit AGit changes but protected `main` rejects direct, force, and deletion pushes.
|
|
- The agent has no write-capable Codeberg API token or authenticated browser session. Only the human web session merges or changes repository settings.
|
|
|
|
This model does not provide separate agent attribution or independently enforceable approval by another account.
|
|
|
|
## Protect `main`
|
|
|
|
In `oibot/Tobserver` → **Settings** → **Branches**, create an exact rule for `main` that:
|
|
|
|
- forbids direct pushes for everyone, including `oibot` and repository owners;
|
|
- has no user, team, deploy-key, or administrator push bypass;
|
|
- forbids force pushes and branch deletion;
|
|
- requires pull-request merging;
|
|
- retains required checks and conversation resolution when configured.
|
|
|
|
Inspect the saved rule in the UI. Do not test protection by making a potentially successful push to Tobserver `main`; use a disposable repository for a push-level test.
|
|
|
|
## Configure the personal SSH identity
|
|
|
|
Normal Codeberg remotes must select the personal key explicitly even if another key is loaded:
|
|
|
|
```sshconfig
|
|
Host codeberg.org
|
|
HostName codeberg.org
|
|
User git
|
|
IdentityFile ~/.ssh/id_ed25519
|
|
IdentitiesOnly yes
|
|
```
|
|
|
|
Verify without pushing:
|
|
|
|
```sh
|
|
ssh -T git@codeberg.org
|
|
```
|
|
|
|
Expected identity: `oibot`.
|
|
|
|
## Install from the Agent Skills catalog
|
|
|
|
Pin `https://codeberg.org/oibot/agent-skills.git` as a non-flake Nix input. Load `create-skill` and `tobserver-change` from that pinned source.
|
|
|
|
Expose the helper on `PATH` by packaging the canonical bundled file `tobserver-change/scripts/tobserver-agent`; do not keep a second editable helper copy in dotfiles. Provide these runtime commands:
|
|
|
|
- Bash
|
|
- Git and OpenSSH
|
|
- curl
|
|
- jq
|
|
- Nix
|
|
- nixpkgs-fmt
|
|
- Gitleaks
|
|
- standard core utilities including `base64`
|
|
|
|
Run after installation:
|
|
|
|
```sh
|
|
tobserver-agent --help
|
|
```
|
|
|
|
## Confirm tokenless operation
|
|
|
|
The helper may perform unauthenticated `GET` requests to the public API under:
|
|
|
|
```text
|
|
https://codeberg.org/api/v1/repos/oibot/Tobserver
|
|
```
|
|
|
|
It must not read a Keychain Codeberg token, send an authorization header, call a write API, approve, or merge.
|
|
|
|
AGit submissions use only:
|
|
|
|
```text
|
|
ssh://git@codeberg.org/oibot/Tobserver.git
|
|
HEAD:refs/for/main/tobserver-agent-<unique-topic>
|
|
```
|
|
|
|
## Retire `oibot-agent`
|
|
|
|
Retire old credentials only after the catalog-backed helper successfully creates and linearly revises one unmerged test PR:
|
|
|
|
1. Confirm no open PR or active workspace still depends on `oibot-agent`.
|
|
2. Remove the `codeberg-tobserver-agent` SSH alias.
|
|
3. Unload the bot key with `ssh-add -d ~/.ssh/oibot-agent`.
|
|
4. Revoke the bot API token and remove its macOS Keychain entry.
|
|
5. Remove the bot SSH key and repository access in Codeberg.
|
|
6. Archive or delete the account only after confirming it owns no required repository or audit artifact.
|
|
7. Delete local bot key files only after explicit confirmation and any desired backup.
|
|
|
|
Do not rewrite historical commits or PRs to erase the old account name.
|
|
|
|
## Recovery
|
|
|
|
Until the new workflow passes end to end, keep old credentials available but do not load the bot key globally. If cutover fails, restore the previous pinned skill revision; never weaken `main` protection as a rollback shortcut.
|