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
repoandworkflow; - 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"
Scroll sideways to see the whole table
| Fine-grained PAT | Classic PAT | |
|---|---|---|
| Repositories reachable | Only those you pick (plus read-only public repos) | Everything you can access |
| Permission granularity | Per permission, read vs write | Broad scopes (repo = full control of private repos) |
| Multiple orgs in one token | No | Yes |
| Org approval possible | Yes | No (orgs can only allow/block) |
| Expiry | Set at creation; orgs may enforce a maximum | Optional; recommended |
| Blast radius if leaked | Small, if you scoped it | Large |
| Works with every API | Not yet | Mostly |
Exact permissions to trigger GitHub Actions
From the REST docs and the fine-grained permissions table:
Scroll sideways to see the whole table
| Action | Fine-grained | Classic |
|---|---|---|
Run a workflow_dispatch workflow (POST .../actions/workflows/{id}/dispatches) | Actions: write | repo |
Send repository_dispatch (POST .../dispatches) | Contents: write | repo |
| List workflows in a private repo | Actions: read | repo |
| Edit workflow files in the repo | Workflows: write | workflow |
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
- Prefer fine-grained, scoped to the specific repositories your app or Shortcut needs.
- Grant the minimum: Actions: write to dispatch; add read permissions (such as Contents: read) only if the tool needs them.
- Always set an expiry, and put a reminder to rotate it.
- One token per app/device, named clearly, so you can revoke just that one.
- Use classic only when you hit a documented gap (e.g. multiple organizations), and then consider a separate GitHub account or narrower setup.
- Revoke immediately if a phone is lost: Settings → Developer settings → Personal access tokens.
- 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"
- GitHub → your avatar → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
- Token name: something you'll recognize when revoking, such as
iphone-actions-button. - Expiration: pick a date. 30 or 90 days is a reasonable rhythm for a phone; the organization may set a maximum.
- Resource owner: your account, or the organization that owns the repositories. One token covers one owner.
- Repository access: Only select repositories, then pick just the repositories with workflows you want to run.
- 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
- 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
- Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).
- Note: e.g.
iphone-actions-button. - Expiration: choose one. "No expiration" exists, but GitHub recommends setting one.
- Scopes: tick
repoonly. Leaveworkflowunticked. You needworkflowonly to create or change files under.github/workflows(scopes reference). - 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
Scroll sideways to see the whole table
| Response | Usual cause | Fix |
|---|---|---|
401 Bad credentials | Token mistyped, expired, or revoked | Generate a new one; check the expiry date |
404 Not Found on a repo you know exists | Token doesn't include that repository, or the resource owner is wrong. GitHub returns 404 instead of 403 for private resources you can't see | Edit the fine-grained token's repository list, or create it under the right owner |
403 Resource not accessible by personal access token | Missing permission, such as Actions: write | Edit the token and add the permission |
403 mentioning an organization policy | Org forbids this token type, or approval is pending | Use 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 trigger | Merge the workflow to that branch |
| Works for personal repos, fails for org repos | One fine-grained token can't span owners | Create 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.
- Create the new token with the same settings and a clear name, such as
iphone-actions-button-2. - Paste it into the app or shortcut and run something harmless.
- 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
- Does the app say which permissions it needs, and why? If not, ask, or pick another tool.
- Is the token limited to the repositories you'll actually use?
- Does it have an expiry date, with a calendar reminder to rotate it?
- Can you name it so you'll recognize it when you need to revoke it?
- Does the app say where the token is stored, and whether it ever leaves the device?
- 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.
Related
- How to Trigger GitHub Actions from Your iPhone: 7 Options Compared
- workflow_dispatch vs repository_dispatch vs REST API vs gh CLI
- iOS Shortcuts for GitHub Actions: DIY vs a dedicated app
- Pocket Actions changelog
Last checked: 2026-11-01 (GitHub Docs: managing personal access tokens; REST workflows/repositories; fine-grained permissions table).
