Build an iOS app from GitHub Codespaces

Use a browser-based Linux codespace for the repository and coding agent, then hand Xcode compilation, signing, and TestFlight delivery to a cloud Mac.

September 9, 2026 · 8 min read

GitHub Codespaces can be the development workspace for an iOS app, even from a Windows computer, Chromebook, or tablet. The repository, editor, terminal, and coding agent run in a cloud Linux container. Xcode does not run in that container, so the native iOS build and signing must run on a separate cloud Mac.

The practical route is Codespaces for source work, NoMac for Xcode and App Store delivery, and TestFlight for testing on a real iPhone.

What runs where

GitHub says a codespace is a cloud-hosted development environment and can be used in a browser or desktop VS Code. Its Codespaces features guide explicitly supports working from a browser or tablet. That makes it a good match for a persistent coding agent and a separate remote build service.

What the repository must contain

A clean codespace starts from Git. Anything available only on an old developer machine does not exist there. Commit every reproducible input:

• ·The complete Xcode project or workspace and a shared application scheme.
• ·Swift, Objective-C, JavaScript, Dart, and native project source as applicable.
• ·Assets, configuration templates, entitlements, and privacy manifest.
• ·Package and framework lockfiles.
• ·Scripts required by the build, using repository-relative paths.

Keep credentials, generated output, local databases, build folders, and dependency caches out of Git. The cloud Mac should reproduce them from declared inputs.

Create a reproducible codespace

GitHub Codespaces reads .devcontainer/devcontainer.json to create a development container. GitHub's dev container introduction explains how the file defines tools, runtimes, extensions, and setup commands.

A small Node-enabled starting point looks like this:

{
  "name": "iOS source workspace",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  }
}

Add only tools the project actually uses. For portable Swift packages, install the current Linux Swift toolchain and official Swift extension. For React Native, pin Node and the package manager. For Flutter, pin the Flutter SDK and commit pubspec.lock. Codespaces should reproduce source work; Xcode remains outside the container.

Connect NoMac securely

For a short-lived personal codespace, you can use the device flow:

npx @nomac/cli login

A deleted codespace loses its local configuration. For a repeatable setup, create a scoped NoMac API key in the dashboard and store it as a Codespaces secret named NOMAC_API_KEY. GitHub's Codespaces secrets guide explains how to restrict a personal development secret to selected repositories. Never write the value into devcontainer.json.

The NoMac CLI reads NOMAC_API_KEY from the environment. Restart the codespace after adding a new secret so GitHub injects it.

Connect the coding agent

Install the agent inside the codespace and register the NoMac stdio server. For example:

# Claude Code
claude mcp add nomac -- npx @nomac/cli mcp

# OpenAI Codex
codex mcp add nomac -- npx @nomac/cli mcp

The local MCP process can read the codespace working tree, so push_project sends the exact current source. Add an instruction file telling the agent which local checks to run and that the iOS target requires a remote smoke build.

The browser-to-TestFlight loop

1. Make and review a focused change

Let the agent inspect first, implement one feature, and report changed files. Review project settings, entitlements, dependency definitions, and data migrations carefully.

2. Run Linux-supported checks

Run portable Swift tests, JavaScript tests, Flutter tests, linters, formatting, and backend tests inside the codespace. These are fast but do not prove the iOS application target.

3. Run the authoritative iOS smoke build

Call push_project, start workflow=smoke, and poll status. Retrieve get_failure before editing after a failure.

Run all supported checks in this codespace. Then push the complete project
to NoMac and run a smoke build. If it fails, separate source, dependency,
project, and signing causes. Explain the evidence before making a fix.

4. Create a real-device checkpoint

Start workflow=release only after the smoke build passes. Apple processes the upload, then TestFlight makes it available on the iPhone. Test the main task and return screenshots and reproduction steps to the browser agent.

Limits to understand

• ·No local Xcode, SwiftUI preview, iOS Simulator, Instruments, or Apple debugger.
• ·A stopped codespace preserves storage, but a deleted one removes local-only configuration.
• ·Compute and storage usage can incur GitHub charges; stop idle environments.
• ·Browser editing is convenient, but very large visual diffs are easier on a desktop.
• ·Codespaces secrets are available to processes in the environment; grant repository access narrowly.

Who should use this setup?

It fits people on locked-down Windows computers, Chromebooks, tablets, or frequently changing devices; students who want a reproducible environment; and teams that want the same source tools for every contributor. A Linux VPS is better when you want complete control and a continuously running agent. A remote interactive Mac is better for simulator-heavy UI work.

Once the TestFlight build is stable, finish with the easiest App Store publishing workflow for 2026. Codespaces remains the workspace; NoMac remains the Apple release boundary.