iOS Shortcuts + GitHub API

iOS Shortcuts + GitHub API: zero-infrastructure mobile memory capture

2026-03-08 · memory-context tools-infrastructure knowledge-management · medium · source → · wiki →

key claims

The GitHub Contents API `PUT /repos/{owner}/{repo}/contents/{path}` is callable from iOS Shortcuts via "Get Contents of URL" with method PUT, and requires `message` and `content` (base64-encoded, single-line) fields in the JSON body; a 201 response confirms the file is committed. The complete direct-write Shortcut requires approximately 8–11 actions: Format Date (timestamp), Ask for Input or Dictate Text (note text), Text (assemble Markdown content with front matter), Encode (base64, Line Wrap: None), Dictionary (build API request body), Get Contents of URL (PUT), Show Notification (confirm)
The Encode action's Line Wrap setting must be set to None; the default MIME-style wrapping inserts newlines every 76 characters, which causes the GitHub API to return HTTP 422 Unprocessable Entity. This is a non-obvious, single-tap configuration change that is a likely failure mode when building GitHub Contents API Shortcuts
Filename collisions in an inbox pattern are prevented by using second-precision timestamps (`yyyy-MM-dd-HH-mm-ss`); without seconds, two captures in the same minute with identical slugs would attempt to create the same file, returning HTTP 422 since no `sha` is provided for an update. The Format Date action in Shortcuts supports arbitrary date format strings, making second precision a trivial change
iOS Shortcuts has no native access to the iOS Keychain; a PAT must be hardcoded as a text value in the Shortcut definition, making the Shortcut sensitive and unsuitable for sharing via iCloud link. The correct mitigation is a fine-grained PAT with `Contents: write` on the Memory-System repo only, a 180–365 day expiry, and a calendar reminder for rotation — adequate security for personal notes on a biometric-locked device
A fine-grained PAT with `Contents: write` scoped to a single repository limits the blast radius of a leaked credential to the contents of that one repository; a classic `repo`-scoped PAT would expose all repositories. For personal memory data in a private repo, the fine-grained PAT is the correct credential choice
The GitHub Contents API primary rate limit is 5,000 authenticated requests per hour; a secondary limit applies to content-creating requests (approximately 80 per minute), neither of which constrains human-pace personal capture. At ten captures per hour, a user would consume 0.2% of the primary hourly limit
The GitHub code search API (`GET /search/code?q={keyword}+repo:{owner}/{repo}`) is callable from the same Shortcut, rate-limited to 10 authenticated requests per minute, and returns a JSON `items` array parseable by Shortcuts' "Get Dictionary Value" and "Repeat with Each" actions, enabling keyword retrieval with results openable in Safari. Code search is keyword-only (full-text grep over file contents), not semantic; it is sufficient for retrieving recent notes by distinctive terms
An Apple Watch face complication can trigger the capture Shortcut, enabling a hands-free workflow: tap complication → dictate note → file committed on GitHub, with all required actions (Dictate Text, Format Date, Text, Encode, Get Contents of URL, Show Notification) confirmed as watchOS-compatible. This achieves minimum-friction spontaneous capture without removing the iPhone from a pocket

Research Question

Can an iOS Shortcut write a timestamped .md file directly to a GitHub repo via the Contents API (PUT /repos/{owner}/{repo}/contents/{path}) with a stored Personal Access Token (PAT), with enough reliability and speed to serve as the primary mobile capture path? What are the limits: file naming, front-matter templating, base64 encoding within Shortcuts, rate limits, PAT security model, and can the same Shortcut call GitHub code search for keyword retrieval?

Findings

(Populated from §6 Synthesis above.)

Executive Summary

An iOS Shortcut can reliably write timestamped .md files directly to a GitHub repository via the Contents API using a stored PAT, and this direct-write path is the correct primary capture mechanism for the Memory-System repository because it commits files immediately without any intermediate Actions workflow. The non-obvious technical requirement is the Encode action's Line Wrap setting — defaulting to MIME-style 76-character wrapping, which the GitHub API rejects; setting Line Wrap to None is mandatory. The Shortcut requires a fine-grained PAT with Contents: write scoped to a single repository, hardcoded in the Shortcut (iOS Shortcuts has no native Keychain access), kept private, and rotated annually. The same infrastructure supports both a write Shortcut (capture) and a read Shortcut (keyword search via the GitHub code search API), and the capture Shortcut can run on Apple Watch as a face complication for hands-free dictation-to-commit.

Key Findings

The GitHub Contents API PUT /repos/{owner}/{repo}/contents/{path} is callable from iOS Shortcuts via "Get Contents of URL" with method PUT, and requires message and content (base64-encoded, single-line) fields in the JSON body; a 201 response confirms the file is committed. The complete direct-write Shortcut requires approximately 8–11 actions: Format Date (timestamp), Ask for Input or Dictate Text (note text), Text (assemble Markdown content with front matter), Encode (base64, Line Wrap: None), Dictionary (build API request body), Get Contents of URL (PUT), Show Notification (confirm).
The Encode action's Line Wrap setting must be set to None; the default MIME-style wrapping inserts newlines every 76 characters, which causes the GitHub API to return HTTP 422 Unprocessable Entity. This is a non-obvious, single-tap configuration change that is a likely failure mode when building GitHub Contents API Shortcuts.
Filename collisions in an inbox pattern are prevented by using second-precision timestamps (yyyy-MM-dd-HH-mm-ss); without seconds, two captures in the same minute with identical slugs would attempt to create the same file, returning HTTP 422 since no sha is provided for an update. The Format Date action in Shortcuts supports arbitrary date format strings, making second precision a trivial change.
iOS Shortcuts has no native access to the iOS Keychain; a PAT must be hardcoded as a text value in the Shortcut definition, making the Shortcut sensitive and unsuitable for sharing via iCloud link. The correct mitigation is a fine-grained PAT with Contents: write on the Memory-System repo only, a 180–365 day expiry, and a calendar reminder for rotation — adequate security for personal notes on a biometric-locked device.
A fine-grained PAT with Contents: write scoped to a single repository limits the blast radius of a leaked credential to the contents of that one repository; a classic repo-scoped PAT would expose all repositories. For personal memory data in a private repo, the fine-grained PAT is the correct credential choice.
The GitHub Contents API primary rate limit is 5,000 authenticated requests per hour; a secondary limit applies to content-creating requests (approximately 80 per minute), neither of which constrains human-pace personal capture. At ten captures per hour, a user would consume 0.2% of the primary hourly limit.
The GitHub code search API (GET /search/code?q={keyword}+repo:{owner}/{repo}) is callable from the same Shortcut, rate-limited to 10 authenticated requests per minute, and returns a JSON items array parseable by Shortcuts' "Get Dictionary Value" and "Repeat with Each" actions, enabling keyword retrieval with results openable in Safari. Code search is keyword-only (full-text grep over file contents), not semantic; it is sufficient for retrieving recent notes by distinctive terms.
An Apple Watch face complication can trigger the capture Shortcut, enabling a hands-free workflow: tap complication → dictate note → file committed on GitHub, with all required actions (Dictate Text, Format Date, Text, Encode, Get Contents of URL, Show Notification) confirmed as watchOS-compatible. This achieves minimum-friction spontaneous capture without removing the iPhone from a pocket.
The direct-write path (Contents API) is the correct primary path for the Memory-System repository, reversing the prior research conclusion that issue creation is preferred; that conclusion holds for the Research repo, which has an issue-to-backlog Actions workflow, but the Memory-System's zero-infrastructure constraint requires direct file creation to avoid adding a new workflow dependency. The additional authoring complexity (8–11 vs. 4–5 actions) is a one-time build cost, not a recurring usage cost.

Assumptions

Assumption: Round-trip latency is 1–3 seconds on Wi-Fi and 2–5 seconds on LTE. Justification: Inferred from general iOS Shortcuts execution overhead (sub-second for local actions) plus typical GitHub API response times (200–800 ms on Wi-Fi, 500–2000 ms on LTE). No published benchmark for this specific Shortcuts + GitHub Contents API flow was found during research.
Assumption: All required Shortcut actions (Dictate Text, Format Date, Text, Encode, Get Contents of URL, Show Notification) are compatible with watchOS Shortcuts execution. Justification: Apple's documentation lists supported Shortcuts action categories for Apple Watch, and these action types fall within supported categories. Dr. Drang's July 2024 working example uses an analogous action set. On-device testing is needed to confirm.

Analysis

The central question — whether the direct file write path is viable as primary capture — resolves to yes, with the caveat that it requires more careful Shortcut authoring than the issue creation path. The authoring complexity (base64 encoding with Line Wrap: None, filename construction, front-matter templating) is real but bounded and one-time. Once the Shortcut is built and validated on device, no additional complexity accrues.

The recommendation differs from the prior research item's preference for issue creation. That preference was grounded in the Research repo's context (an existing issue-to-backlog Actions workflow makes issues a valid capture path). The Memory-System context removes that workflow, making issue creation a half-step that adds infrastructure. The direct-write path is the complete path.

The PAT security posture is the weakest point of the design. iOS Shortcuts' lack of Keychain access is a platform-level constraint. [inference] The recommended mitigation (fine-grained PAT, minimal scope, private Shortcut, calendar-reminder rotation) is the best available option within the zero-infrastructure constraint. The security trade-off is acceptable for personal notes on a biometric-locked device, not for shared or professional contexts.

Code search as retrieval is a functional but limited path. It answers "find notes containing this keyword" but not "find notes semantically related to this concept." For personal memory capture where the user tends to use consistent terminology, keyword search is sufficient for most retrieval needs. Semantic retrieval (vector embeddings, LanceDB or similar) is out of scope for this item and would require local or server-side infrastructure.

Risks, Gaps, and Uncertainties

No on-device test conducted. The research identifies no theoretical barrier to the direct-write flow, but implementation-specific issues (Shortcuts version compatibility, API response parsing edge cases, watchOS action rendering) may surface during actual device testing. The Memory-System W-0008 implementation work must include a device test phase.
Apple Watch action compatibility is inferred. The claim that all required actions are watchOS-compatible is based on Apple documentation categories and one analogous working example, not a complete action-by-action compatibility check.
Siri transcription quality for technical terms. Hands-free dictation of technical terms, proper nouns, or unusual vocabulary may produce transcription errors. A confirmation step before the API call addresses this at the cost of one extra interaction.
PAT rotation discipline. If the PAT expires and is not rotated promptly, the Shortcut silently fails (GitHub returns 401). Adding a notification step that shows the API response status code to the user helps surface failures.

Open Questions

Should the Shortcut include a text review step (display transcribed text, confirm before committing) to catch Siri transcription errors? This adds one interaction but prevents bad data entering the memory system.
Is there value in a "browse recent captures" Shortcut using the Contents API GET /repos/{owner}/{repo}/contents/inbox (returns directory listing as JSON) plus "Choose from List" and "Open URLs"?
Does watchOS's Shortcuts execution environment introduce additional latency compared to iPhone execution for network-dependent actions like Get Contents of URL?
Could a companion app (e.g., a simple iOS app that exposes a Shortcuts App Intent with Keychain-backed token storage) eliminate the hardcoded PAT limitation without violating the zero-infrastructure constraint? This would be a native iOS app — infrastructure on-device but not server-side.

sources

[x] Research/completed/2026-03-02-agent-memory-management-context-injection.md — production markdown-bank patterns; context on why .md files are the right storage layer
[x] Research/completed/2026-03-02-ios-shortcuts-research.md — existing findings on iOS Shortcuts + GitHub API for this research repo; directly applicable
[x] GitHub Contents API docs
[x] GitHub Search API docs
[ ] Apple iOS Shortcuts User Guide
[x] iOS Shortcuts HTTP action docs (Get Contents of URL / Set Variable)
[x] GitHub REST API rate limits
[ ] davidamitchell/Memory-System BACKLOG.md W-0008 — the corresponding discovery item that this research informs

← newerLanceDB index rebuild speed from git

older →Inbox folder pattern