How to audit GitHub outside collaborators and machine users: Find, justify and remove standing repository access

Outside collaborators and machine users are the GitHub accounts most likely to keep repository access long after anyone remembers why they have it. Outside collaborators sit outside your teams and, on GitHub Enterprise Cloud, outside SAML single sign-on; machine users are ordinary personal accounts run by scripts, with passwords and tokens your organisation must look after. This runbook shows how to list both, see exactly which repositories and roles they hold, decide what to keep, remove the rest and stop the list growing back. It is for GitHub organisation owners, platform teams and security engineers on GitHub.com or GitHub Enterprise. For the wider control set, see the GitHub Organisation Security Checklist.

This is an independent guide from NHI Mgmt Group, based on GitHub's public documentation and REST API description as of November 2026. It is not sponsored or reviewed by GitHub. Product features change, so confirm settings against GitHub's current documentation.

Key takeaways

• Repository admins can invite by default. Anyone with admin access to a repository can add outside collaborators unless an owner restricts it, so the list grows without central review.
• The REST API gives you the full picture. GET /orgs/{org}/outside_collaborators lists the accounts; GET /repos/{owner}/{repo}/collaborators?affiliation=outside shows each one's role_name per repository.
• SAML does not cover them. GitHub documents that outside collaborators are not required to use SAML SSO, so your identity provider's leaver process does not remove them.
• Machine users are humans' accounts used by machines. GitHub's terms require a responsible human owner; each one holds a password, tokens and often SSH keys, and consumes a licence. GitHub Apps are the documented alternative.
• Removal is clean but final for forks. Removing a collaborator deletes their forks of private repositories, but not local clones, so pair removal with credential and secret review.

When you need this

• Periodic access review: quarterly review of external and non-human access, often required by NIST SP 800-53 AC-2 Account Management and PS-7 External Personnel Security.
• End of a contract or vendor engagement: contractors and agencies are a common reason for outside collaborator access, and nothing on GitHub expires it automatically. MITRE ATT&CK tracks abuse of such access as T1199 Trusted Relationship and T1078 Valid Accounts.
• Before enforcing two-factor authentication: GitHub warns that outside collaborators without 2FA are removed when the requirement is turned on, including bots and service accounts. Find machine users first so automation does not break.
• Licence clean-up: outside collaborators on private repositories, and machine users, consume paid licences.

Before you start

You need:

• Permissions: organisation owner for the full outside collaborator list and the audit log; repository admin is enough for per-repository collaborator lists. Use a fine-grained token or a GitHub App with read-only organisation and repository administration access for scripts.
• Tools: the GitHub CLI (gh api with --paginate) or any HTTP client. All API calls below are read-only until the removal step.
• Context: your contractor and vendor register, HR leaver data and the list of known automation accounts, so each account can be matched to an owner.

Step-by-step

Steps 1 to 6 are read-only. Step 7 changes access and is partly reversible. Step 8 changes organisation settings.

1. List outside collaborators.

   gh api --paginate "/orgs/<org>/outside_collaborators?filter=all&per_page=100" --jq '.[].login'
   gh api --paginate "/orgs/<org>/outside_collaborators?filter=2fa_disabled&per_page=100" --jq '.[].login'
   gh api --paginate "/orgs/<org>/outside_collaborators?filter=2fa_insecure&per_page=100" --jq '.[].login'

   The 2fa_insecure filter returns collaborators using methods that GitHub does not count as secure. On an enterprise, People > Outside collaborators shows the same across all organisations and can filter by organisation.
2. Map each collaborator to repositories and roles. List repositories, then the outside collaborators on each:

   gh api --paginate "/orgs/<org>/repos?type=all&per_page=100" --jq '.[].full_name'
   gh api --paginate "/repos/<org>/<repo>/collaborators?affiliation=outside&per_page=100" \
     --jq '.[] | [.login, .role_name] | @tsv'

   The permission query parameter (pull, triage, push, maintain, admin) narrows the list, for example to find every outside collaborator with admin. In the web interface, People > Outside collaborators then Manage on a user shows the same per-repository view.
3. List pending invitations. Open invitations become access the moment they are accepted. Check GET /repos/{owner}/{repo}/invitations for each repository and GET /orgs/{org}/failed_invitations for the organisation, and cancel anything nobody can explain.
4. Identify machine users. GitHub has no machine user flag, so combine signals across both the outside collaborator list and the member list (GET /orgs/{org}/members?role=all):
   • Naming and profile: names such as -bot, -ci, svc- or deploy, team mailbox addresses, no profile activity.
   • Behaviour: audit log activity at fixed intervals, from CI runner or server addresses, with no web sign-ins.
   • Credentials: on Enterprise Cloud with SAML, GET /orgs/{org}/credential-authorizations lists the personal access tokens, SSH keys and OAuth tokens authorised for the organisation, filterable by login.
   • Records: CI and deployment configuration that references the account.
   Record a named human owner for every machine user, as GitHub's terms of service require someone responsible for each machine account.
5. Find last activity. On Enterprise Cloud, query GET /orgs/{org}/audit-log with a phrase such as actor:<login> and include=all to include Git events. By default the endpoint returns events from the past three months; use the created qualifier in the phrase for older ones. Accounts with no activity in 90 days and no documented seasonal use are removal candidates. See the GitHub Audit Log Detection Guide for streaming and retention.
6. Review with owners. For each account confirm: who sponsors it, which repositories it still needs, the lowest role that works, and an end date. Use the decision table below.
7. Reduce or remove access.
   • Lower a role: change the collaborator's role on the repository in Settings > Collaborators and teams.
   • Remove from one repository: DELETE /repos/{owner}/{repo}/collaborators/{username}, or Manage access > Remove access to this repository.
   • Remove from the organisation: DELETE /orgs/{org}/outside_collaborators/{username}, or select users and choose Remove from all repositories.
   • Demote a member: PUT /orgs/{org}/outside_collaborators/{username} converts a member to an outside collaborator. They leave all teams but keep access to repositories they were added to directly or through former teams, so review that access straight away.
   For machine users that stay, revoke unused personal access tokens and SSH keys, rotate the password, enable secure 2FA held in a vault, and plan migration to a GitHub App.
8. Stop the list growing back. On Enterprise Cloud, go to Settings > Member privileges, and under Repository outside collaborators deselect Allow repository administrators to invite outside collaborators to repositories for this organization, then save. Enterprise owners can enforce the same policy for every organisation.

Decision table

Machine user or GitHub App

GitHub's own documentation sets out the trade-off. A machine user is a personal account with a username and password that you must secure, it consumes a licence, and its tokens act with everything the account can reach. A GitHub App bot cannot sign in, does not consume a licence, keeps working when the person who installed it leaves, and uses short-lived installation tokens scoped to chosen repositories and permissions. Keep a machine user only where an App cannot do the job, for example some enterprise-level APIs, and treat it as a privileged non-human identity with an owner, vaulted credentials and a review date. See How to audit GitHub Apps and OAuth apps in an organisation and the GitHub Personal Access Tokens Security Guide.

Verify it worked

• Re-run steps 1 and 2. Removed accounts are gone and remaining ones hold the agreed roles.
• Check the audit log for org.remove_outside_collaborator, repo.remove_member and repo.update_member events matching your change list.
• Confirm the policy change by finding org.update_member_repository_invitation_permission in the audit log, and confirm that repository admins can no longer send invitations.
• Check automation that used a machine user: pipelines run and no new 401 or 403 errors appear.

Rollback and common errors

Rollback: re-invite the user to the specific repositories with the agreed role. For a former member converted to an outside collaborator, GitHub saves their membership privileges for three months, so re-inviting them within that time can restore them. Forks of private repositories deleted on removal do not come back.

Hardening afterwards

1. Alert on new access. Stream the audit log to your SIEM and alert on org.add_outside_collaborator, repository_invitation.create and repo.update_member where the role is admin.
2. Require secure 2FA for members and outside collaborators, after machine users have vaulted secure 2FA, so new accounts cannot join without it.
3. Prefer Enterprise Managed Users for long-term contractors where licensing allows, so repository collaborators are provisioned and removed by your IdP.
4. Retire machine users in favour of GitHub Apps, workflow tokens and OIDC federation. See How to Restrict GITHUB_TOKEN Permissions in Workflows and How to find unused GitHub deploy keys and SSH keys.
5. Repeat quarterly and at every contract end, and record decisions as access review evidence. See How to Run an Access Review for Service Accounts.

Small and large organisations

A small organisation can run steps 1 and 2 in the web interface in under an hour and rely on owners to approve every invitation. Large organisations and enterprises should script the API calls into a scheduled report across all organisations, restrict invitations to owners, and route requests through a ticket with an expiry date, because repository admins in hundreds of repositories will otherwise keep adding access.

Metrics

• Outside collaborators with a sponsor and end date: target 100%.
• Outside collaborators with admin: count per organisation, trending to zero.
• Accounts inactive for 90 days: outside collaborators and machine users with no audit log activity.
• Machine users remaining: count, with migration dates to GitHub Apps.
• Accounts without secure 2FA: results from the 2fa_disabled and 2fa_insecure filters. Target zero.

Framework mapping

Practitioner checklist

• List outside collaborators with the all, 2fa_disabled and 2fa_insecure filters.
• Map each collaborator to repositories and role_name, and flag every admin.
• Review and cancel unexplained pending and failed invitations.
• Identify machine users among collaborators and members and give each a named owner.
• Check last activity in the audit log, including Git events where available.
• Remove or reduce access using the decision table, and review converted members' remaining access.
• Revoke unused tokens and keys on machine users that stay, and plan migration to GitHub Apps.
• Restrict outside collaborator invitations to owners and alert on new additions.
• Repeat quarterly and at every contract end.

Standards and references

• GitHub Docs: Adding outside collaborators to repositories in your organization
• GitHub Docs: Removing an outside collaborator from an organization repository
• GitHub Docs: Setting permissions for adding outside collaborators
• GitHub Docs: REST API endpoints for outside collaborators
• GitHub Docs: REST API endpoints for collaborators
• GitHub Docs: Requiring two-factor authentication in your organization
• GitHub Docs: Differences between GitHub Apps and OAuth apps
• GitHub: Terms of Service

Related NHI Mgmt Group resources: GitHub Organisation Security Checklist · How to audit GitHub Apps and OAuth apps in an organisation · GitHub Personal Access Tokens Security Guide · GitHub Audit Log Detection Guide · GitHub Organisation Compromise Playbook