iOS Shortcuts for research capture and query

Research Question

What iOS Shortcuts workflows provide the most value for a personal research system hosted on GitHub — covering both low-friction research capture (adding a URL or idea to the backlog from anywhere on iOS) and lightweight query (checking recent research or asking a question against the corpus) — and what GitHub APIs or existing delivery channels do they depend on?

Findings

Executive Summary

iOS Shortcuts calling the GitHub Issues API via "Get Contents of URL" is the correct and simplest path for mobile research capture — three to five Shortcut actions create a labeled GitHub issue from any iOS context, including the Safari Share Sheet and Siri voice dictation. The same design handles both Share Sheet and Siri entry points by branching on whether a URL was passed as input. Authentication requires a GitHub fine-grained PAT (Issues: write scope) hardcoded in the Shortcut definition, which is the only practical on-device storage mechanism for API tokens in iOS Shortcuts. Wiki query is covered for free by a one-action "Open URLs" shortcut pointing to the published wiki Home page. A search-capable query shortcut is deferred, blocked on a workflow_dispatch-triggered search workflow that does not yet exist.

Key Findings

1. iOS Shortcuts "Get Contents of URL" supports arbitrary HTTP methods, custom headers, and JSON request bodies, making GitHub REST API calls fully feasible from iOS without any intermediary app or service. This is confirmed by a GitHub employee's published working shortcut (island94.org, January 2024) and independently by a tutorial at theporteur.com.

2. Issue creation (POST /repos/{owner}/{repo}/issues) is the recommended capture implementation path because it requires no base64 encoding, no filename construction, and no Markdown template assembly — only a title and optional body are needed in the JSON request body. The direct file creation path (Contents API) requires 3–4 additional Shortcuts actions including the Encode action (Base64, Line Wrap: None) and is significantly more fragile.

3. Share Sheet integration requires enabling "Show in Share Sheet" with Accepted Types: URL in the Shortcut's settings; the shared URL is received as the Shortcut's input via the Shortcut Input magic variable. A single shortcut handles both the Share Sheet path (URL provided) and the Siri/tap path (no URL) via conditional logic.

4. When a Shortcut is triggered via "Hey Siri, [shortcut name]", the "Ask for Input" action reads the prompt aloud and accepts voice-dictated text hands-free without any screen interaction. When triggered by tapping in the Shortcuts app, the same action shows an on-screen text input field; dictation requires tapping the microphone icon.

5. A GitHub fine-grained PAT with Issues: write scope on the target repository is the minimum credential required for the capture shortcut; Contents: write is required only if direct file creation is used instead of issue creation. Neither scope grants read access to other repositories or allows workflow triggers — the blast radius of a leaked token is minimal.

6. iOS Shortcuts has no native access to the iOS Keychain, so the PAT must be stored as a hardcoded text value in the Shortcut definition. The standard community practice is to store the token inline, keep the Shortcut private (not shared via iCloud link), and use a fine-grained PAT with minimal scope and a reasonable expiry (90–365 days).

7. The GitHub wiki quick-access shortcut is a single "Open URLs" action pointing to github.com; this is trivially implementable and adds Siri invocability over a plain Safari bookmark. The wiki is already published and maintained by the publish-wiki.yml workflow established in 2026-03-01-github-wiki-research-content.md.

8. GitHub Actions workflow_dispatch is triggerable from iOS Shortcuts using the same "Get Contents of URL" pattern as issue creation, with endpoint POST /repos/{owner}/{repo}/actions/workflows/{workflow_file}/dispatches and JSON body {"ref": "main", "inputs": {...}}. This pattern is confirmed by the island94.org GitHub employee post and independently by theporteur.com.

9. The GitHub iOS app does not provide a native "Dispatch Workflow" Siri Shortcuts action; all workflow automation from iOS Shortcuts requires constructing the API call manually in "Get Contents of URL". This was confirmed by web search — no native Shortcuts action for workflow dispatch exists in the GitHub iOS app as of March 2026.

10. The query shortcut using workflow_dispatch is feasible but asynchronous — the Shortcut triggers the workflow, which must run and post results (as an issue or comment) before the user can view them. For synchronous query, opening the wiki and using Safari's built-in find-in-page covers the primary use case at zero implementation cost.

Assumptions

• Assumption: The issue-to-backlog GitHub Actions workflow identified in 2026-02-27-simple-process-for-adding-research-item.md is implemented or will be implemented. Justification: The prior research item recommended this workflow as the owner's capture path; if it is not yet built, the capture shortcut still creates a labeled issue that is visible in the GitHub iOS app and on the web, requiring only a manual move rather than automatic conversion.

• Assumption: The repository wiki is enabled in GitHub Settings (required for the wiki quick-access shortcut to return a page rather than a 404). Justification: The completed 2026-03-01-github-wiki-research-content.md item notes that the wiki must be enabled once in Settings; the publish workflow's existence implies this has been done.

• Assumption: The owner's iPhone is running iOS 13 or later. Justification: "Get Contents of URL" with custom headers and JSON body requires iOS 13+. iOS 13 was released in 2019; any current iPhone runs iOS 16 or later.

Analysis

The primary design decision — issue creation vs. direct file creation — resolves clearly in favour of issue creation on two axes: simplicity (fewer actions, no base64 encoding, no filename construction) and integration (leverages the existing issue-to-backlog workflow, preserving the clean capture-then-structure separation validated by Zettelkasten principles in prior research). The direct file creation path is not wrong but creates a single-responsibility Shortcut that duplicates logic already present in the Python CLI and the Actions workflow, without adding value.

The query shortcut decision resolves as: wiki first (synchronous, zero-cost, good enough for most queries), workflow_dispatch second (asynchronous, requires a new search workflow, higher value for non-trivial queries). The MCP server approach (from 2026-03-02-chat-conversational-interface.md) is explicitly not applicable to iOS users — the MCP server serves AI agent sessions, not mobile browser or Shortcuts contexts.

The PAT storage constraint is a real limitation but not a blocker. The security posture (fine-grained, minimal scope, on a personal device protected by biometrics) is adequate. The absence of native Keychain support in iOS Shortcuts is a platform limitation that Apple has not addressed; the community workaround (inline storage) is the only viable option.

Risks, Gaps, and Uncertainties

• Issue-to-backlog workflow gap: If the issues: [opened]-triggered workflow is not implemented, the capture shortcut produces an issue that requires manual conversion. The shortcut itself is still valuable (it creates a record in GitHub Issues accessible from the iOS app), but the fully automated pipeline requires the Actions workflow.
• PAT expiry: A fine-grained PAT with a 90-day expiry requires editing the Shortcut every 90 days. This is a minor but real maintenance burden. A PAT with no expiry removes the burden but increases risk.
• Query shortcut unimplemented: The search workflow_dispatch shortcut requires a GitHub Actions workflow that accepts a query string, searches Research/completed/, and posts results as an issue. This workflow does not currently exist; building it is a reasonable follow-on.
• GitHub iOS app future changes: The GitHub app may add native Shortcuts actions in future releases, making the manual API approach obsolete. This is unlikely to be a problem — the manual approach would continue to work even if native actions are added.
• Siri recognition reliability: Hands-free capture depends on Siri correctly recognising the title dictation. For technical titles with acronyms or unusual terms, Siri may produce transcription errors. The "Ask for Input" dialog appears on screen to allow correction before submission.

Open Questions

• Should the issue-to-backlog GitHub Actions workflow be added to the backlog as a concrete implementation item, or is it already covered by the existing issue form (from 2026-02-27-simple-process-for-adding-research-item.md)?
• Would a workflow_dispatch-triggered search workflow (accepting a query input and posting results as an issue) be worth building? This is the "Option A query shortcut" from the Approach section. If yes, it warrants a backlog item.
• Is there value in a "Start Research" shortcut that moves a specific backlog item to in-progress by triggering the python -m src.main research start CLI via a workflow_dispatch event? This would give the owner a one-tap "start" action from iOS for items visible in the GitHub Issues list.

sources

• [x] Research/completed/2026-02-27-simple-process-for-adding-research-item.md — existing capture paths (agent CLI + GitHub issue form); iOS Shortcuts is the missing third path
• [x] Research/completed/2026-03-01-github-wiki-research-content.md — wiki as the readable delivery channel accessible from iOS Safari
• [x] Research/completed/2026-03-02-chat-conversational-interface.md — query interface conclusions (MCP for agents, not for mobile users)
• [ ] Research/backlog/2026-02-27-interface-and-delivery.md — upstream interface and delivery item
• [ ] Research/backlog/2026-03-02-chat-conversational-interface.md — query interface (dependency for query shortcut Option B)
• [x] GitHub REST API — Contents — PUT to create/update a file
• [x] GitHub REST API — Issues — POST to create an issue
• [x] GitHub REST API — Actions (workflow_dispatch)
• [x] Apple Shortcuts User Guide — Share Sheet, Get URL, Get Contents of URL, Ask for Input, Show Notification
• [x] Apple Shortcuts — Get Contents of URL action: supports arbitrary HTTP methods and headers (suitable for GitHub API calls)
• [x] Community iOS Shortcut examples for GitHub API calls — island94.org, theporteur.com, Apple Community discussions