Get started with Apple

You need a Mac. This page takes you from a fresh clone to the app running in the simulator.

• Xcode: the version the project currently requires is in the README. The project follows new Xcode releases quickly, so at times that is a beta from Apple Developer Downloads.
• Ruby: for Bundler and Fastlane, which run the linters and tests. The version is in .ruby-version.
• An Apple developer team ID, for code signing.

Third party libraries are Swift packages. Xcode resolves them on its own.

1. Fork home-assistant/iOS on GitHub.

2. Clone your fork and create a branch:

   Shell

   git clone https://github.com/<your-github-username>/iOS.git
   cd iOS
   git checkout -b fix-widget-refresh

Pick one way to get Ruby, then install the gems. With mise:

brew install mise
mise install
bundle install

With rbenv:

brew install rbenv ruby-build
rbenv install
bundle install

The Ruby version is in .ruby-version. If you already have a matching Ruby, bundle install is enough.

The app uses entitlements that need code signing, even in the simulator. Debug builds use automatic provisioning, but you need to tell Xcode which team and bundle IDs to use.

Create Configuration/HomeAssistant.overrides.xcconfig:

DEVELOPMENT_TEAM = YourTeamID
BUNDLE_ID_PREFIX = some.bundle.prefix

• DEVELOPMENT_TEAM is your team ID, from the Apple developer portal. It looks like ABCDEFG123.
• BUNDLE_ID_PREFIX is a prefix you control, so Xcode can create provisioning profiles for it.

Git ignores this file. Xcode generates the profiles for your team, and features your team doesn't have, like critical alerts, are turned off.

1. Open HomeAssistant.xcodeproj in Xcode.
2. Select the App-Debug scheme.
3. Select a simulator or your device.
4. Build and run.

Connect it to a test instance of Home Assistant if you can: each onboarding registers a new device on the server.

# Check formatting and lint, without changing files
bundle exec fastlane lint

# Fix what can be fixed automatically
bundle exec fastlane autocorrect

# Run the unit tests
bundle exec fastlane test

# Run autocorrect before every commit
bundle exec fastlane install_git_hooks

Working on the frontend and want to see it in the app? You don't need to build the app:

1. Install Xcode, and open the simulator from Xcode > Open Developer Tool > Simulator.
2. Download the ios-simulator artifact from a recent run of the CI workflow on main.
3. Drag the .app onto the simulator and launch it.
4. In Safari, turn on the Develop menu in the advanced settings. Then use Develop > Simulator to open Web Inspector on the app's web view.

The repository has instructions for AI coding tools in AGENTS.md, and skills in .agents/skills/, like ha-ios-architecture, ha-ios-testing, and ha-ios-workflow-ci. The pull request template asks whether you used AI, and how. Contribute with AI tools lists every skill, and explains what the AI policy asks of you.

• Read the architecture and the targets.
• Check the code style before your first pull request.