# 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?