Sign in

Search issue titles and bodies, change requests and comments. Private repositories you cannot read are not included.
vole
Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

A free and open-source forge that lives in your Git repo.

Add agent workflow guide for Vole

22db80e2bb223726eb960a6a269d0409fa45c9f6 · Keenan Nemetz · 13d ago · parent c717d4eb

AGENTS.md +186

@@ -0,0 +1,186 @@
1 # Working in this repository
2
3 This repository is **Vole's own source tree**, and it uses **Vole** as its forge.
4 Issues, change requests, approvals, releases, and CI records live in Git on the
5 `vole` branch. There is no GitHub issue tracker in this workflow.
6
7 If you are an agent, start here, then use the CLI rather than guessing at a
8 forge API.
9
10 ## 1. Identify the instance and yourself
11
12 ```sh
13 git remote -v
14 ./vole whoami
15 ```
16
17 - The forge is whatever `origin` points at. Do not assume it is GitHub.
18 - Use `./vole` when it exists in the repository root; otherwise use `vole` from
19 `PATH`.
20 - `vole whoami` must print the account your SSH key resolves to. If it fails,
21 stop and ask for credentials or the correct instance. Do not fall back to a
22 name from `git config`.
23
24 ## 2. Do not use GitHub-shaped tools
25
26 This repository is not hosted on GitHub for its own work.
27
28 - Do **not** use `gh`, the GitHub API, or GitHub issue/PR URLs.
29 - Do **not** run `gh issue`, `gh pr`, or `git push` to a GitHub remote.
30 - If a tool or instruction assumes GitHub, adapt it to the Vole CLI below or ask.
31
32 The CLI is the write surface. The browser may have passkey login disabled, and
33 private repositories return `404` to anonymous visitors.
34
35 ## 3. Find or file an issue before changing code
36
37 Read the open work first:
38
39 ```sh
40 ./vole issue list --state open --format '%(id) %(title)'
41 ./vole issue list --state open -l security --format '%(id) %(title)'
42 ./vole issue show <full-id>
43 ```
44
45 Use the **full 26-character ULID** in scripts and issue bodies. The 8-character
46 prefixes shown by `%(shortid)` can collide.
47
48 The CLI writes the `vole` metadata branch directly, so issue and comment writes
49 need `maintain` access. A contributor without that role files issues and comments
50 in the browser instead.
51
52 File an issue with a body file for multiline Markdown:
53
54 ```sh
55 ./vole issue new \
56 --title "Short, specific title" \
57 -F /tmp/issue-body.md \
58 -l security -l p0 \
59 -a "$(./vole whoami)"
60 ```
61
62 Conventions used in this repository:
63
64 - Prefix priority in the title when it applies: `P0:`, `P1:`, `P2:`.
65 - Use lowercase labels with `-` or `_`, never spaces.
66 - Include **why**, **scope/checklist**, and **acceptance criteria**.
67 - Link related work with `#<full-ulid>` in the body.
68 - Assign the issue to yourself if you are going to work on it.
69
70 Useful labels include `security`, `p0`, `p1`, `p2`, `bug`, `availability`,
71 `auth`, `authz`, `ci`, `deployment`, `web`, `testing`, and `tracking`.
72
73 Before starting, comment with a short plan if the issue is not already clear:
74
75 ```sh
76 ./vole issue comment <full-id> -F -
77 ```
78
79 Close when the acceptance criteria are met:
80
81 ```sh
82 ./vole issue close <full-id>
83 ```
84
85 ## 4. Code changes and review
86
87 Git writes go over SSH. The normal loop is:
88
89 ```sh
90 git switch -c <branch>
91 # edit, test
92 git add <files>
93 git commit -m "Explain the change"
94 git push -u origin <branch>
95 ```
96
97 Then open a Vole change request if the branch should be reviewed:
98
99 ```sh
100 ./vole change new --title "..." --base main --head <branch> -F /tmp/change-body.md
101 ./vole change list --state open --format '%(id) %(title)'
102 ./vole change show <full-id>
103 ```
104
105 Important differences from a GitHub-style forge:
106
107 - The `vole` metadata branch is maintained by Vole. Do not hand-edit it or
108 force-push it.
109 - A contributor may only push under `refs/heads/contrib/<account>/`.
110 Contributors use the web to open change requests; the CLI `change new` writes
111 the metadata branch directly and needs `maintain`.
112 - Protected branches require an approved change request naming the exact head
113 commit. CI checks may also be required. Do not try to bypass the pre-receive
114 gate.
115 - Do not approve your own change request. Approval is an attestation by a
116 different account.
117 - CI for a contributor branch does not run until a maintainer allows that exact
118 tip. A new push waits again.
119
120 ## 5. CI and tests
121
122 Check workflows before pushing:
123
124 ```sh
125 ./vole workflow check
126 ```
127
128 Run the repository's verification workflow when a container runtime is
129 available:
130
131 ```sh
132 ./vole workflow run verify
133 ```
134
135 That workflow runs formatting, vet, build, packaging, link checks, and the race
136 test suite. If it cannot run locally because no container runtime is available,
137 run the relevant underlying commands (`gofmt`, `go vet ./...`,
138 `go test -race ./...`) and say which check you could not run.
139
140 ## 6. Releases and sites
141
142 Only use these when the task explicitly asks for them:
143
144 ```sh
145 ./vole release create <tag> -F notes.md
146 ./vole release attach <tag> <file>...
147 ./vole pages deploy [--branch <name>]
148 ```
149
150 ## 7. Local administration
151
152 Local admin commands read the instance config. Prefer the environment variable:
153
154 ```sh
155 VOLE_CONFIG=/path/to/vole.toml ./vole admin account list
156 ```
157
158 `vole admin --config <path> <command>` currently loses the subcommand on some
159 paths; see issue `01M5XCJVEZAX8SQNQMDZZF9FRJ`. Use `VOLE_CONFIG` until that is
160 fixed.
161
162 Do not change instance-wide access rules, create accounts, retire accounts, or
163 delete repositories unless the task explicitly asks. Those are instance-admin
164 operations and are audited.
165
166 ## 8. Safety rules
167
168 - Never put secrets, tokens, private keys, or credentials in an issue, comment,
169 commit message, workflow log, or release note.
170 - Never force-push `main`, the `vole` metadata branch, or a protected branch.
171 - Do not disable tests, checks, hooks, or validation to make a change pass.
172 - Do not close or edit another account's issue/comment unless you are repairing
173 data as an admin and the action is explicitly requested.
174 - Keep unrelated changes out of the commit.
175 - If the CLI does not support what you need, ask instead of inventing a second
176 workflow.
177
178 ## 9. Where the details live
179
180 - [docs/cli.md](docs/cli.md) — full CLI reference
181 - [docs/issues.md](docs/issues.md) — issue format and rules
182 - [docs/change-requests.md](docs/change-requests.md) — review and approval flow
183 - [docs/workflows.md](docs/workflows.md) — workflow format
184 - [docs/runner.md](docs/runner.md) — CI runners and job trust
185 - [docs/configuration.md](docs/configuration.md) — instance configuration
186 - [docs/architecture.md](docs/architecture.md) — trust model and storage layout