Fine-Grained vs Classic GitHub Tokens: Which to Give a Mobile App

Disclosure: I build Pocket Actions, an iPhone app that asks you to paste a GitHub personal access token (PAT). That's exactly why this post exists: if you're going to hand a token to any app — mine included — you should know what it can do. Facts below come from GitHub Docs (linked) as of the last-checked date.

Why this matters on a phone

Many mobile GitHub tools don't use "Sign in with GitHub"; they ask for a PAT. The same goes for an iOS Shortcut that calls the GitHub API. The token then sits on a device you carry everywhere. If it leaks, whoever has it can act as you within the token's limits. So the useful question isn't "which token is better in general" but "what's the smallest token that still does the job?"

The two token types (per GitHub)

GitHub's PAT documentation describes them like this.

Fine-grained personal access tokens — GitHub recommends these whenever possible:

  • limited to resources of one user or one organization;
  • can be limited to specific repositories;
  • use fine-grained permissions (e.g. Actions: read/write, Contents: read/write) instead of broad scopes;
  • organization owners can require approval;
  • you can create up to 50 of them;
  • note: they "always include read-only access to all public repositories on GitHub."

Personal access tokens (classic) — "less secure":

  • a classic token "can access every repository that you can access" — all your personal repos and all repos in organizations you belong to;
  • uses scopes like repo and workflow;
  • some things only work with classic tokens (see below).

Both are tied to the user who made them. GitHub automatically removes PATs unused for a year and "highly recommend[s]" setting an expiration.

Where fine-grained tokens still fall short

GitHub lists these gaps for fine-grained tokens:

  • contributing to public repos where you aren't a member;
  • repos where you're an outside or repository collaborator;
  • accessing multiple organizations at once;
  • Packages;
  • the Checks API;
  • user-owned Projects.

Also, a few REST endpoints only accept classic tokens; each endpoint's docs say so. Some organizations block classic tokens entirely (requests then fail with 403), and some block fine-grained ones.

Comparison for "paste into an app"

Comparison for "paste into an app"
Fine-grained PATClassic PAT
Repositories reachableOnly those you pick (plus read-only public repos)Everything you can access
Permission granularityPer permission, read vs writeBroad scopes (repo = full control of private repos)
Multiple orgs in one tokenNoYes
Org approval possibleYesNo (orgs can only allow/block)
ExpirySet at creation; orgs may enforce a maximumOptional; recommended
Blast radius if leakedSmall, if you scoped itLarge
Works with every APINot yetMostly

Exact permissions to trigger GitHub Actions

From the REST docs and the fine-grained permissions table:

Exact permissions to trigger GitHub Actions
ActionFine-grainedClassic
Run a workflow_dispatch workflow (POST .../actions/workflows/{id}/dispatches)Actions: writerepo
Send repository_dispatch (POST .../dispatches)Contents: writerepo
List workflows in a private repoActions: readrepo
Edit workflow files in the repoWorkflows: writeworkflow

So a fine-grained token for "a button that runs my workflows" can be: one or a few repositories, Actions: write, an expiry. Metadata: read is included automatically. Apps usually do more than dispatch, though: listing workflows needs Actions: read (included in Actions: read and write), and reading a workflow file to build an input form needs Contents: read. Check what each app asks for.

What about the apps that ask for classic scopes?

Be skeptical of any app — including mine — that asks for more than it needs.

Pocket Actions needs only the repo scope on a classic token. The in-app guide used to pre-select workflow as well, but per GitHub's docs dispatching a workflow needs only repo; workflow is for changing workflow files, which Pocket Actions never does. So the guide is being changed to select repo only. If your existing token also has workflow, you can replace it with a repo-only token.

For a fine-grained token, Pocket Actions needs Actions: Read and write (to list and run workflows) and Contents: Read-only (to read the workflow file and build the input form) on the repositories you want to use. The app's code accepts fine-grained tokens and doesn't check token type or scopes, so it should work — but I haven't tested it on a device yet, so treat it as unverified. Organization repositories may also need fine-grained tokens to be allowed by the org. The token is stored only in the device's secure storage and not sent to any Pocket Actions server (there isn't one).

Practical rules

  1. Prefer fine-grained, scoped to the specific repositories your app or Shortcut needs.
  2. Grant the minimum: Actions: write to dispatch; add read permissions (such as Contents: read) only if the tool needs them.
  3. Always set an expiry, and put a reminder to rotate it.
  4. One token per app/device, named clearly, so you can revoke just that one.
  5. Use classic only when you hit a documented gap (e.g. multiple organizations), and then consider a separate GitHub account or narrower setup.
  6. Revoke immediately if a phone is lost: Settings → Developer settings → Personal access tokens.
  7. Never paste tokens into notes, chats or docs. Store them only where the app keeps them.

Creating each token, click by click

Menu labels below follow GitHub's token creation guide. GitHub sometimes renames them, so look for the closest match.

A fine-grained token for "run my workflows"

  1. GitHub → your avatar → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
  2. Token name: something you'll recognize when revoking, such as iphone-actions-button.
  3. Expiration: pick a date. 30 or 90 days is a reasonable rhythm for a phone; the organization may set a maximum.
  4. Resource owner: your account, or the organization that owns the repositories. One token covers one owner.
  5. Repository access: Only select repositories, then pick just the repositories with workflows you want to run.
  6. Permissions → Repository permissions:
    • Actions: Read and write (list and dispatch workflows)
    • Contents: Read-only, only if the app reads workflow files (Pocket Actions does, to build input forms)
    • Metadata: Read-only is added automatically
  7. Generate token and copy it straight into the app. GitHub shows it only once.

If the resource owner is an organization that requires approval, the token stays pending until an owner approves it, and API calls fail until then.

A classic token with repo only

  1. Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).
  2. Note: e.g. iphone-actions-button.
  3. Expiration: choose one. "No expiration" exists, but GitHub recommends setting one.
  4. Scopes: tick repo only. Leave workflow unticked. You need workflow only to create or change files under .github/workflows (scopes reference).
  5. Generate token and copy it.

Test the token before you trust it

Check the token from a computer before you paste it into a phone. Keep it in an environment variable so it doesn't end up in your shell history, and don't paste it into chats or documents.

read -s GITHUB_TOKEN && export GITHUB_TOKEN

# 1) Can the token see the repository?
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO

# 2) Can it list workflows?
curl -s \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows | head -n 20

# 3) Can it dispatch? (Starts a real run. Use a harmless workflow.)
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/hello.yml/dispatches \
  -d '{"ref":"main"}'

Expected results: 200, a JSON list, and a 2xx. Per GitHub's current REST docs, a successful workflow dispatch returns 200 with workflow_run_id, run_url and html_url (docs). Whether older API versions still return an empty 204 is unconfirmed, so treat any 2xx as success. For classic tokens, the response header X-OAuth-Scopes lists the token's scopes. For fine-grained tokens, a failed request may carry X-Accepted-GitHub-Permissions, which tells you which permission the endpoint wanted (troubleshooting the REST API). Add -i to curl to see headers.

A harmless workflow for step 3:

# .github/workflows/hello.yml
name: hello
on: workflow_dispatch
jobs:
  hi:
    runs-on: ubuntu-latest
    steps:
      - run: echo "dispatch works"

Errors and what they usually mean

Errors and what they usually mean
ResponseUsual causeFix
401 Bad credentialsToken mistyped, expired, or revokedGenerate a new one; check the expiry date
404 Not Found on a repo you know existsToken doesn't include that repository, or the resource owner is wrong. GitHub returns 404 instead of 403 for private resources you can't seeEdit the fine-grained token's repository list, or create it under the right owner
403 Resource not accessible by personal access tokenMissing permission, such as Actions: writeEdit the token and add the permission
403 mentioning an organization policyOrg forbids this token type, or approval is pendingUse the allowed type; ask an owner to approve
422 "does not have 'workflow_dispatch' trigger"Not a token problem: the workflow on ref lacks the triggerMerge the workflow to that branch
Works for personal repos, fails for org reposOne fine-grained token can't span ownersCreate a second token with the org as resource owner

(Exact error message wording isn't documented; treat the quoted text as typical, unconfirmed.)

Living with tokens on a phone

Where the token sits. It depends on the tool:

  • An iOS Shortcut keeps it in a Text or header field inside the shortcut. If you share the shortcut, the token goes with it, and if your shortcuts sync through iCloud, it syncs too.
  • A dedicated app should use the system secure storage. Pocket Actions keeps the token only in the device's secure storage, and there's no Pocket Actions server it could be sent to.
  • GitHub Mobile doesn't use a PAT at all.

Rotation without drama.

  1. Create the new token with the same settings and a clear name, such as iphone-actions-button-2.
  2. Paste it into the app or shortcut and run something harmless.
  3. Delete the old token in Developer settings.

If the phone is lost. Revoke the token first and worry about the device second. Revoking takes seconds and cuts off access no matter who has the phone. Then check the repository's Actions tab for runs you didn't start.

Keep the dangerous parts in GitHub. Even a perfectly scoped token can start a deploy. Put production jobs behind an environment with required reviewers (environments docs), so a leaked token can request a deploy but can't push it through alone.

A 30-second checklist before you paste a token into any app

  1. Does the app say which permissions it needs, and why? If not, ask, or pick another tool.
  2. Is the token limited to the repositories you'll actually use?
  3. Does it have an expiry date, with a calendar reminder to rotate it?
  4. Can you name it so you'll recognize it when you need to revoke it?
  5. Does the app say where the token is stored, and whether it ever leaves the device?
  6. Is anything dangerous (production deploys) protected by an environment with reviewers?

If you can answer yes to all six, the token type matters much less.

Which should you choose?

  • One app, one or two personal repos: fine-grained, those repos, Actions: write (+ any read the app documents), 30–90-day expiry.
  • Repos across several organizations: fine-grained can't span orgs; create one per org, or use classic with care.
  • Org blocks one type: use the type the org allows.
  • GitHub Mobile: no PAT needed — it signs in with your account.

A real example

I run an AI stock-evaluation workflow from my phone when I need it. Whatever app or Shortcut you use for something similar, the token behind it deserves the same care as a password.

Try Pocket Actions

If you trigger workflow_dispatch workflows from your phone, you can try it free for 5 runs a day. Limits: runs target main, no logs in the app, iOS only.

View Pocket Actions on the App Store

FAQ

Should I use a fine-grained or classic token? GitHub recommends fine-grained tokens whenever possible. Use classic only when you hit a documented limitation such as needing several organizations in one token.

What permission does a fine-grained token need to run workflow_dispatch? Actions: write on the target repository.

Does a classic token with repo scope access all my repositories? Yes. A classic token can access every repository you can access, including organization repositories.

Do fine-grained tokens expire? You choose an expiration when you create them; organizations can enforce a maximum lifetime. GitHub also removes tokens unused for a year.

Does Pocket Actions support fine-grained tokens? The app's code accepts fine-grained tokens, but I haven't tested this on a device yet. If you try it, grant Actions: Read and write + Contents: Read-only on the target repositories. For a classic token, repo alone is enough.

Last checked: 2026-11-01 (GitHub Docs: managing personal access tokens; REST workflows/repositories; fine-grained permissions table).