jacobian · September 14, 2022 23:09 · Sep 14, 2022
diff --git a/robots.yaml.md b/robots.yaml.md
@@ -0,0 +1,111 @@
+# Robots policy for github projects
+
+This is a sketch of a proposal for a "robots.txt for github" -- a policy that defines what actions automated tooling can take against a given repository.
+
+## Identification
+
+Bots self-identify, and use `project/repo`-style naming. So code that lives at `https://github.com/jacobian/coolbot` identifies as `jacobian/coolbot`. Forks should generally use the upstream identifier until/unless they become different enough to warrent new names. This is a matter of judgement.
+
+## Policy file location: `.github/robots.yml`
+
+Policies live in `.github/robots.yml`. Well-behaved robots should consult this file before taking action.
+
+## Policy file contents
+
+Somewhat inspired by `robots.txt`, but in YAML to troll security researchers. I have no spec yet so here are examples:
+
+Robots may not interact with this repository:
+
+```yaml
+deny: *
+```
+
+Go hog wild:
+
+```yaml
+allow: *
+```
+
+Nobody is welcome except `jacobian/coolbot`:
+
+```yaml
+allow:
+  - jacobian/coolbot
+```
+
+That's the same as:
+
+```yaml
+deny: *
+allow:
+  - jacobian/coolbot
+```
+
+That is, an `allow` without a `deny` implies `deny: *`.
+
+The same is true of a deny list. This allows any bot, _except_ `jacobian/coolbot`:
+
+```yaml
+deny:
+  - jacobian/bot1
+```
+
+and that's the same as:
+
+```yaml
+allow: *
+deny:
+  - jacobian/coolbot
+```
+
+If there's both an `allow` and a `deny` list, an implicit `deny: *` should also be inferred. So given:
+
+```yaml
+allow:
+  - jacobian/coolbot
+deny:
+  - jacobian/otherbot
+```
+
+`jacobian/otherbot` clearly should stay away, but so should `jacobian/bot3` and all other bots. The above should be treated as:
+
+```yaml
+allow:
+  - jacobian/coolbot
+deny: *
+```
+
+### Organizational policies
+
+Bots can also be allowed or denied by organization. This policy welcomes bots from the Python Packaging Authority:
+
+```yaml
+allow:
+  - pypa/*
+```
+
+This policy welcome most bots, but none made by me:
+
+```yaml
+allow: *
+deny:
+  - jacobian/*
+```
+
+### Action policies
+
+Finally, policies may allow or deny specific actions. This policy allows `jacobian/coolbot` any action, and allows PyPA bots to open issues (but only open issues):
+
+```yaml
+allow:
+  - jacobian/coolbot
+  - pypa/*@issues
+```
+
+Valid actions are: 
+
+    - `issues`
+    - `pull_requests`
+
+TBD: more granular permissions e.g. "open issue", "comment on issue", etc?
+