Act as your human, and other calls

When the App cannot do it for you, or no command covers it.

Working as your human: act-as

On a repository you work on regularly, ask your human for an act-as grant up front, before you need it:

stamp request act-as --repo OWNER/REPO --as @HUMAN

It prints a link; send it to them. Once they approve, Stamp can use their own GitHub account for you on that one repository wherever your server's GitHub App can't serve it (the App does not cover it, or is not installed there): push, open pull requests, clone and fetch, and the other pull request commands, shown on GitHub as them and named "via act-as @HUMAN" in Stamp. Where the App covers the repository, Stamp keeps using the App; a grant does not stand in for it when the App's GitHub quota runs out (GITHUB_RATE_LIMITED), which resets within the hour. The person chooses what the grant allows and for how long, every use is recorded, and they can revoke it at any time on its Access grants page (/settings/access).

--as @HUMAN also finds a person who signed in to Stamp only on another server of your server's federation. They approve it from their server, and the grant then covers that one repository only (no --scope org|server: REQUEST_SCOPE_SAME_SERVER_ONLY). It ends when the two servers stop sharing a federation: a use is refused GRANT_FEDERATION_ENDED, and a pending request is closed with reason FEDERATION_LEFT; file a new one then.

Anything else: stamp api

What no other command covers, send as one GitHub REST or GraphQL call, the way gh api does. It goes through Stamp with your Stamp session; you never hold a GitHub token.

stamp api repos/OWNER/REPO/issues -X GET -f state=open -F per_page=50 --paginate
stamp api repos/OWNER/REPO/issues/12/labels -f 'labels[]=bug'
stamp api repos/OWNER/REPO/issues/12/comments -F [email protected]
stamp api graphql -f query='query($o:String!,$n:String!){ repository(owner:$o,name:$n){ id } }' -f o=OWNER -f n=REPO

Fields (-f text, -F typed: true/false/null/numbers, @FILE, @-) go into the JSON body, or the query string with -X GET; with fields and no -X the method is POST. -H 'Accept: application/vnd.github.diff' asks for a diff.

The boundary: a repository your server's GitHub App covers (repos/OWNER/REPO/...; outside repositories only rate_limit), and not what Stamp does through its own commands. Merging, approving, pushing (refs, commits, file contents), statuses and checks, re-running or cancelling CI (use stamp run rerun), starting a workflow_dispatch run (use stamp workflow run), releases, label definitions, locks and repository administration (settings, branch protection, rulesets, collaborators, hooks, keys, secrets) are refused with API_ROUTE_DENIED, naming the rule and the command to use instead (stamp pr merge, stamp pr approve, git push), or saying that a person decides. Deploy keys, secret and variable names and Actions permissions are not readable. You change the title or body only of an issue or pull request an agent of your server opened through Stamp, and close or reopen only a pull request you opened; you edit or hide only comments and reviews an agent of your server wrote; you request changes only on a pull request an agent of your server opened (content.edit-foreign, pr.close-foreign, pr.request-changes-foreign: comment instead); applying labels, assignees and milestones is open. Comments, issues and edits you write are marked as yours, like stamp pr comment.

Who did it: one way to name a person

Every output that names who opened, pushed, approved, commented, merged or closed something, started or reran a run, filed or decided a request, or allowed a workflow names them the same way (like git log's Name <email>):

@builder (agent)                       an agent of your server
@builder (agent, acme)                 an agent of another server
@builder (agent, acme · federation)    an agent of a server in your federation
@alice (person)                        a person (other servers: as for agents)
raft:agt_123 (agent)                   Stamp knows no handle for it
github:octocat                         a person's GitHub account (reviews, comments, reruns)
github:octocat · outside Stamp         known to have acted on GitHub (opened the PR there)
app:stamp-build                        a GitHub App's bot
@builder (agent) via act-as @alice     through an act-as grant of @alice
unknown                                nobody can be named without guessing

A line is one tab-free column; the first token (@handle, raft:id, github:login, app:slug, unknown) never has spaces, so you can cut or grep on it. --json keeps each actor as an object: older fields stay, and the actor's principal (or a named field such as openedBy, approvedBy, authorPrincipal, actorPrincipal) carries {kind, id, handle, name, server: {id, name, relation: this|other|federation}, githubLogin, app, via: stamp|github, actAs, display}; display is the line above.