> For the complete documentation index, see [llms.txt](https://docs.forestall.io/forestall/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forestall.io/forestall/edges/github/gh_collaborator.md).

# GH\_COLLABORATOR

## Summary

|                              |                                                                            |
| ---------------------------- | -------------------------------------------------------------------------- |
| **Forestall ACL Alias**      | GH\_COLLABORATOR                                                           |
| **Edge Type**                | Relationship                                                               |
| **Affected Object Types**    | GitHub Repositories                                                        |
| **Exploitation Certainty**   | N/A (structural)                                                           |
| **GitHub Role / Permission** | Any direct repository permission (pull / triage / push / maintain / admin) |

## Description

`GH_COLLABORATOR` is a **structural relationship** recording that a user has been granted access **directly on a repository** — as a collaborator on the repository itself, not through a team. The permission level is stored on the edge as the `Permission` property: `pull`, `triage`, `push`, `maintain`, or `admin`.

Only **direct** grants are modelled (collected with `affiliation=direct`). Access a user inherits through team membership is represented by `GH_IN_TEAM` → `GH_HAS_ACCESS` instead, so the two paths stay distinct.

This edge captures all direct user access regardless of level. The privileged subset is derived into separate attack-path edges:

* A direct collaborator with `admin` also gets `GH_ADMIN`.
* A direct collaborator with `push`/`maintain` on an unprotected default branch also gets `GH_PUSH_TO_DEFAULT`.

Direct collaborator grants are worth attention because they bypass team-based access governance: they are easy to add ad hoc and easy to forget, and outside collaborators frequently appear here.

## Identification

### GitHub Web Interface

1. Open the repository → **Settings → Collaborators and teams**.
2. The **People** section lists every user with direct access and their role (Read / Triage / Write / Maintain / Admin).

### GitHub CLI

List direct collaborators on a repository and their permission:

```bash
gh api "repos/{org}/{repo}/collaborators?affiliation=direct" --paginate \
  --jq '.[] | {login: .login, role: .role_name}'
```

Check a specific user's effective permission:

```bash
gh api "repos/{org}/{repo}/collaborators/{username}/permission" --jq '.permission'
```

## Exploitation

Not applicable — this is a structural relationship, not a traversable attack path. The security-relevant capabilities a direct collaborator holds are exploited through the privileged edges built on top of it (`GH_ADMIN`, `GH_PUSH_TO_DEFAULT`).

## Mitigation

1. **Prefer team-based access over direct collaborators.** Managing access through teams keeps grants reviewable and consistent; direct grants drift out of governance.
2. **Audit direct collaborators regularly**, especially outside collaborators and anyone holding `write` or above. Remove access that is no longer needed.
3. **Grant the least sufficient permission.** Use `read`/`triage` unless the user must push, and reserve `admin` for genuine repository administrators.

## Detection

| Event                | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `repo.add_member`    | A user was added as a collaborator on the repository |
| `repo.remove_member` | A collaborator was removed from the repository       |
| `repo.update_member` | A collaborator's permission level was changed        |

Alert on direct grants of `write`/`admin`, on access granted to outside collaborators, and on permission escalations performed outside an approved change process.

## References

* <https://docs.github.com/en/rest/collaborators/collaborators#list-repository-collaborators>
* <https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization>