GitHub Machine User vs GitHub App vs Deploy Keys

A GitHub machine user is the credential teams reach for first and need least often. It is a second user account, created by a person, that exists only to run automation. A GitHub App or a deploy key covers most automation jobs with less to go wrong. This guide sets out what GitHub’s terms allow for a bot account, which credential fits CI and releases, and how seats, 2FA and ownership work when its owner leaves.

Every quotation here comes from GitHub’s own documentation, linked at first use and checked 2026-10-28.

What a GitHub machine user is, and what GitHub’s terms allow

An account a human creates and stays responsible for, used only for automation

GitHub’s page on account types is direct: “User accounts are intended for humans, but you can create accounts to automate activity on GitHub.” It names the pattern — “This type of account is called a machine user” — with CI as the example.

The Terms of Service then attach conditions. As the Terms define it, a machine account is one an individual human sets up, accepts the Terms for and gives a valid email address to, and that human answers for what it does. Its purpose is confined to automated tasks.

One free machine account on top of your free personal account

One person or legal entity may keep no more than one free account, and the Terms add: “You may maintain no more than one free machine account in addition to your free Personal Account.”

So a free pair is the ceiling: your own account, plus one machine account you run. That is a limit on free accounts rather than on bot identities; whether a paid plan allows more, and what they cost in seats, is a billing question for that plan. Our guide to GitHub account grades and the terms goes further into the account-count rule and GitHub’s enforcement powers.

No automated account creation, and one owner of record per account

Two further limits apply. The deploy keys documentation puts the first plainly: “This means that you cannot automate the creation of accounts.” Accounts registered by bots are not permitted, so a pool of machine users cannot be generated on demand.

The second concerns sharing, and it is narrower than it looks. The Terms limit a personal login to one person, but machine accounts carry a carve-out in the same section: “Multiple users may direct the actions of a machine account, but the owner of the Account is ultimately responsible for the machine’s actions.” So a team may run one bot account together, provided one named human answers for it. The Terms also state, “You may not share API tokens to exceed GitHub’s rate limitations”, which rules out spreading automation across identities for capacity.

GitHub machine user vs GitHub App vs deploy keys at a glance

Scope: one repository, chosen repositories or an organization

A deploy key is deliberately narrow, described by GitHub as “an SSH key that grants access to a single repository.” An App is installed on the repositories you select, across organizations if needed. A machine user sits at the other end: it sees whatever you invite it to, which is its main risk.

Seats and billing: what GitHub’s docs say for each

GitHub’s comparison of Apps and OAuth apps counts a machine user account against an Enterprise seat and leaves App bots out of it. The page on deciding when to build an App generalises: “unlike a user, a GitHub App does not consume a GitHub seat.”

What happens when the person who set it up leaves

An App installation outlives the installer: “GitHub Apps remain installed even when the person who initially installed the app leaves the organization.” A deploy key also keeps working, which is good for uptime and bad for hygiene: nothing prompts anyone to remove it.

A machine user keeps working too, but its responsible human has gone: someone must inherit the mailbox, the 2FA secret and the accountability, and that handover is the step teams forget.

When a deploy key is enough

One repository, read-only by default, write access optional

GitHub deploy keys are the smallest credential available for a server that clones one repository. The documentation sets the default: “Deploy keys are read-only by default, but you can give them write access when adding them to a repository.” Be careful with that option: the same page notes that a key with write access can do what an organization member with admin access can.

The trade-offs: no expiry, often no passphrase, not tied to membership

The documented drawbacks read as a checklist. A deploy key reaches one repository. Keys are, in GitHub’s words, “usually not protected by a passphrase, making the key easily accessible if the server is compromised.” They are “credentials that don’t have an expiry date.” And they “aren’t linked directly to organization membership”, so removing a person changes nothing. Keep a list of which key lives on which host, and never reuse one.

When a GitHub App is the better credential

Not tied to a user, doesn’t consume a seat, survives staff changes

For a bot, a build, a checks integration or anything acting on repositories for the team, an App is the route GitHub points at. Because an App installed on an organization is not dependent on a user, your automation does not inherit one person’s employment status.

Permissions and short-lived tokens

An App asks for fine-grained permissions rather than broad scopes, and GitHub’s guidance states plainly that “GitHub Apps use short lived tokens.” Lifetimes and the exact permission set move with the product, so check the current documentation as you build.

GitHub Actions for automation inside a repository

Ask first whether the work belongs in GitHub Actions, which suits continuous integration, deployment and project tasks inside one repository and whose workflows “only have access to the resources of the repository that they are set up for.” If your pipeline never leaves the repository, it needs no extra account and no long-lived key.

When you still need a GitHub machine user account

If you land here, GitHub’s documented setup sequence is short:

1. Create the account yourself, as the human who accepts the Terms for it, with a mailing list address your team controls.
2. Turn on 2FA with an authenticator app and store the TOTP secret in your organization’s password manager.
3. Run the ssh-keygen procedure on the server and attach the public key to the machine user account.
4. Give it access to the repositories you want to automate: as a collaborator on a personal repository, as an outside collaborator on an organization repository, or through a team that already has access to those repositories. Prefer the team route, for the reason below.
5. Scope any token it needs, and record who owns the account.

One server that needs SSH access to several repositories

Check whether an App covers it, because the same deploy keys page points this exact case at one: “If your server needs to access repositories across one or more organizations, you can use a GitHub App to define the access you need, and then generate tightly-scoped, installation access tokens from that GitHub App.” Clone over HTTPS with that token and there is no second account to own; those tokens are tightly scoped, carry an expiry, and have to be regenerated from code.

The machine user is for the remainder: tooling that insists on a real login, or on SSH as a user. One account with one key per server then beats a deploy key per repository per machine, which is how key inventories become unknowable. GitHub calls a single machine user for deploy scripts fine; treat it as that last resort, not the default for a multi-repository host.

Personal repositories grant collaborators read and write; organizations can restrict

The documentation is blunt about a limitation people meet late: “Only organizations can restrict machine users to read-only access”, and “Personal repositories always grant collaborators read/write access.” If a bot only needs to read and the repository sits under a personal account, you cannot hold it to read-only. That alone is a reason to move shared repositories into an organization.

GitHub machine user PAT: scope a token to what the bot needs

When a machine user needs API access as well as Git access, a GitHub machine user PAT is the usual answer, and where over-permissioning creeps in. Create a fine-grained token, limit it to the repositories and permissions the automation actually uses, give it an expiry, and keep it in your organization’s secret store rather than a repository file or a chat thread. Label what each token is for; an unlabeled token is one nobody dares revoke.

2FA, ownership and seats for a bot account

Enable 2FA with an authenticator app and store the TOTP secret centrally

GitHub’s page on bots and service accounts with 2FA gives the recipe. Configure 2FA with an authenticator app, then “Store the TOTP secret that’s offered during 2FA setup in the password manager used by your organization.” It also advises against keeping the account password there: reset it through the shared mailbox when someone needs to sign in, and generate codes from the stored secret with a command-line tool.

If your team does keep bot codes in a phone app, read moving authenticator codes to a new phone before anyone upgrades a handset: recovery for a shared account is far worse than for a personal one.

Use an email address your team controls

The same page says to set up a mailing list for the account with the owners as members, and to add that address as a verified email on the account. A personal inbox is the wrong place for a bot’s password resets and security alerts, and ties the account to one employee.

Organizations that require 2FA remove accounts without it

If your organization enforces 2FA, an unattended account without it will not stay: GitHub warns that such accounts are removed from the organization and lose access to its repositories. Enable 2FA when you create the account, not after the enforcement date.

What not to do with extra GitHub accounts

More free accounts than the terms allow

A rate limit or a free-tier ceiling is not an invitation to open more logins; the Terms address sharing tokens to exceed rate limits directly. If one identity is not enough capacity, the documented answer is a credential with a higher limit, not more accounts. GitHub’s REST API rate limits page describes an App installation’s hourly limit as growing with the repositories and users it covers, and higher again on a GitHub Enterprise Cloud organization.

Automated starring, following or other inauthentic activity

GitHub’s Acceptable Use Policies prohibit fake accounts and automated inauthentic activity, including the rank abuse that automated starring or following amounts to, and cover the secondary markets that spread it. A bot that stars, follows or opens issues to manufacture interest is outside the rules however it was created.

Seeded commits or stars are test data, never reputation

Any contribution graph, star or follower count on an account you did not build through real work is test data and nothing more. It does not make the account credible, and presenting it as a history to employers or clients is misrepresentation. The same goes for account age: a join date says when an account was registered and nothing about who ran it, as checking GitHub and other account creation dates explains.

Bought accounts versus the free machine-user route

PVAVRT sells GitHub accounts, and for CI, deployments and releases the free machine user, a GitHub App or a deploy key is still the right route. The terms allow one free machine account set up by a person responsible for it, and the Acceptable Use Policies bar reselling access to the service: buying an account breaks GitHub’s terms, and GitHub can suspend it at any time. The GitHub account grades PVAVRT lists are sold for legitimate marketing, automation, QA testing and account-management work, on units you treat as disposable test infrastructure, never as a credential a production build depends on.

Which credential to choose: GitHub App vs machine user vs deploy key

Work down this order and stop at the first line that fits.

1. The job lives inside one repository: use GitHub Actions.
2. One server needs that one repository: use a deploy key, read-only unless write access is required.
3. Automation acts on several repositories or outside GitHub: build a GitHub App, and clone with an installation access token where a server needs Git access.
4. A tool insists on a real login or on SSH as a user: create one machine user, with a team-controlled email address, 2FA from the start, a scoped token, and a named owner.

Write that owner’s name next to the account, and review it when anyone leaves.

Weighing a GitHub account for a legitimate QA project against GitHub’s terms? Ask about PVAVRT’s GitHub grades on Telegram @pvavrt, and expect to be told when a free machine user or an App is the better answer.