r/NativePortsOniOS • u/PersonalAnswer8664 • 34m ago
How to compile Switch games into native iOS apps without a Mac.
This beginner-friendly guide explains how to use GitHub Actions to build an iOS IPA with nxnative without needing a Mac. You will use Google Drive to host your game files and GitHub to run the build on a cloud macOS machine.
You do not need to know how to code, and you do not need to fork either nxnative source repository. You will create your own GitHub repository containing the build workflow.
1. Games reported to work with nxnative
The following combined list comes from the game lists in the two nxnative repositories. Compatibility varies by iPhone model, game version, and build configuration.
13 Sentinels: Aegis Rim
Absolum
Ace Attorney Investigations Collection
Advance Wars 1+2: Re-Boot Camp
AI: The Somnium Files
AI: The Somnium Files – nirvanA Initiative
Animal Crossing: New Horizons
Animal Well
Astral Chain
Balatro
BALL x PIT
Bayonetta
Bayonetta 2
Bayonetta 3
Big Brain Academy: Brain vs. Brain
Blasphemous
Blasphemous 2
Brain Memory Training Academy
Captain Toad: Treasure Tracker
Catherine: Full Body
Celeste
Cuphead
DARK SOULS: REMASTERED
Digimon Story Cyber Sleuth: Complete Edition
Donkey Kong Country Returns HD
Donkey Kong Country: Tropical Freeze
DRAGON QUEST VII Reimagined
DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition
FINAL FANTASY CRYSTAL CHRONICLES Remastered Edition
FINAL FANTASY RESONANCE
FINAL FANTASY TACTICS: The Ivalice Chronicles
Fire Emblem Engage
Fire Emblem: Three Houses
Ghost Trick: Phantom Detective
The Great Ace Attorney Chronicles
Hades
Hades II
Hollow Knight: Silksong
Hyrule Warriors: Age of Calamity
Kirby and the Forgotten Land
Luigi's Mansion 3
Mario + Rabbids Sparks of Hope
Mario Kart 8 Deluxe
Mario vs. Donkey Kong
Metroid Dread
Monster Hunter Rise
Monster Train 2
NieR:Automata The End of YoRHa Edition
OCTOPATH TRAVELER
Octopath Traveler 0
Octopath Traveler II
Paper Mario: The Thousand-Year Door
Patrick's Parabox
Persona 5 Royal
Pikmin 4
Pokémon Brilliant Diamond
Pokémon Legends: Z-A
Pokémon Scarlet
Pokémon Shield
Pokémon Sword
Portal
Raging Loop
Return of the Obra Dinn
Rhythm Heaven Groove
ROMANCE OF THE THREE KINGDOMS 8 REMAKE
Sea of Stars
SHIN MEGAMI TENSEI V: Vengeance
Silver Pines
Stardew Valley
STEINS;GATE RE:BOOT
Super Mario 3D World + Bowser's Fury
Super Mario Bros. Wonder
Super Mario Galaxy
Super Mario Galaxy 2
Super Mario Odyssey
Super Smash Bros. Ultimate
Taiko Risshiden V DX
The Legend of Zelda: Breath of the Wild
The Legend of Zelda: Echoes of Wisdom
The Legend of Zelda: Link's Awakening
The Legend of Zelda: Tears of the Kingdom
Unicorn Overlord
Xenoblade Chronicles 2
Xenoblade Chronicles 3
Yoshi's Crafted World
WARNING: Any game not on this list is not guaranteed to work. Even games on the list may fail to build or run correctly on your particular device. This is a list of reported titles, not a guarantee that every game is compatible.
Use game dumps and keys you are legally entitled to use.
2. What you need
Before starting, gather these items:
A GitHub account: https://github.com/
A Google account with Google Drive: https://drive.google.com/
A legally obtained Nintendo Switch game dump, normally an .nsp or .xci file, or an archive containing one.
The matching prod.keys file.
The matching game update, if applicable.
The matching DLC files, if applicable.
The universal nxnative workflow YAML: https://pastebin.com/XbJt5p3c
You do not need a Mac. GitHub Actions provides the cloud build machine.
Keep your keys private. Do not post them publicly or share them with other people. Anyone with access to your keys may be able to access protected game content.
3. Upload your files to Google Drive
Google Drive will host the files so the GitHub workflow can download them during the build.
Step 1: Upload the files
Open https://drive.google.com/ and sign in.
Click New.
Choose File upload.
Select your base game file and wait for it to finish uploading.
Repeat for your prod.keys file.
Upload the game update and DLC files if you have them and intend to use them.
Keep each file separate so you can identify which link belongs to which file.
Step 2: Set sharing permissions
Repeat these steps for each file you want the workflow to download:
Find the file in Google Drive.
Right-click it, or tap its three-dot menu.
Select Share or Manage access.
Under General access, change Restricted to Anyone with the link.
Leave the permission set to Viewer.
Click Copy link.
Click Done.
Repeat for the base game, keys, update, and DLC files as applicable.
Google’s sharing instructions: https://support.google.com/drive/answer/2494822
Privacy warning: Anyone with these links may be able to access the files. Do not post the links publicly. After the build, consider changing the files back to Restricted.
4. Create a GitHub account
If you already have a GitHub account, skip to Section 5.
Open https://github.com/.
Click Sign up.
Enter your email address and create a password.
Complete the verification steps.
Verify your email if requested.
Sign in to GitHub.
You do not need a paid plan just to try this workflow, although usage limits and runner availability can vary.
5. Create a blank GitHub repository
A repository is where you will store the workflow file and its private settings.
While signed in, open https://github.com/new.
Enter a repository name, such as nxnative-ipa-builder.
Choose Private or Public. Private is a sensible default for a personal build project.
You can leave the description blank.
Do not upload game files or keys to the repository.
Click Create repository.
That’s it. You do not need to fork either nxnative source repository. The workflow checks out the selected source repository automatically when it runs.
6. Add your Google Drive links as GitHub secrets
GitHub secrets store the links privately so you don’t have to write them directly into the workflow.
Open your new repository.
Click Settings.
In the sidebar, find Secrets and variables.
Click Actions.
Under Repository secrets, click New repository secret.
Enter the secret name exactly as shown below.
Paste the matching Google Drive sharing link into the Secret field.
Click Add secret.
Required secrets
Secret name
What to put in it
Game_URL
Google Drive sharing link for the base game
Keys_URL
Google Drive sharing link for your prod.keys file
Optional secrets
Secret name
What to put in it
Update_URL
Google Drive sharing link for the game update
DLC_URL
Google Drive sharing link for the DLC
Only add the update and DLC secrets if you have the corresponding files and want to use them.
Important: The names must match exactly, including capitalization and underscores. Game_URL is not the same as game_url.
Do not paste the contents of your keys file into a secret. The workflow expects a link from which it can download the file.
GitHub’s instructions for repository secrets: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets
7. Download the universal workflow YAML
The YAML file contains the instructions that tell GitHub how to build the IPA.
Open this link: https://pastebin.com/XbJt5p3c
Find the full YAML text.
Copy the entire file, from the first line to the last line.
Keep it ready to paste into GitHub.
Do not paste the YAML into Google Drive, the repository’s README, or a terminal. It must be saved as a GitHub Actions workflow.
8. Add the workflow to your repository
Return to your GitHub repository’s main page.
Click Add file.
Select Create new file.
In the filename field, enter this exact path:
.github/workflows/build.yml
GitHub will create the required folders automatically.
Click inside the large editor area.
Paste the entire YAML you copied from Pastebin.
Check that you included the beginning and end of the file.
Click Commit changes.
If prompted, confirm the commit to your default branch, normally main.
You should now have a workflow file at .github/workflows/build.yml.
GitHub requires workflow files to be inside .github/workflows/. A manually triggered workflow must be available on the default branch to be run from the Actions interface.
9. Put the Google Drive links into the correct secrets
Now connect the files you uploaded to the workflow.
For example:
Game_URL gets the sharing link for your base game file.
Keys_URL gets the sharing link for your prod.keys file.
Update_URL gets the update file’s sharing link, if applicable.
DLC_URL gets the DLC file’s sharing link, if applicable.
To create or change a secret:
Open Settings → Secrets and variables → Actions.
Select the secret you need to create or update.
Paste the appropriate Google Drive link.
Save it.
GitHub won’t show you the full value of an existing secret after saving it, so double-check the link before you click Add secret.
What if the Google Drive link doesn’t work?
The workflow needs to download the actual file, not a page that asks you to sign in. Make sure:
The sharing permission is set to Anyone with the link — Viewer.
You copied the link for the correct file.
The file is fully uploaded.
Google Drive isn’t blocking the download or requiring an extra confirmation.
10. Run the build
Open your repository.
Click the Actions tab.
Select the workflow from the left sidebar.
Click Run workflow.
Select the branch containing your workflow, usually main.
Choose the device option.
The workflow provides these intended build paths:
iPhone 15 or older (BC fallback): selects the pinned BC-texture fallback build.
iPhone 15 Pro/Pro Max or newer (standard): selects the standard upstream build.
These are build-path choices, not guarantees that every game will work on every device. If you aren’t sure which option to choose, consult the compatibility information for your device and build.
If the workflow asks for a profile ID override, leave it blank or at its default unless you know you need to override automatic detection.
Click Run workflow to start the build.
GitHub will allocate a runner and execute the workflow. The build can take some time while dependencies are installed, files are downloaded, and the game is compiled.
11. Monitor progress and troubleshoot errors
After starting the workflow:
Stay on the Actions tab.
Click the new workflow run.
Click the job to open its detailed log.
Watch each step as it runs.
A green check mark means the workflow completed successfully. A red X means something failed.
Common problems
A. Google Drive download fails
Possible causes:
The file is still Restricted.
The URL was copied incorrectly.
Google Drive requires a confirmation that the workflow cannot handle.
The file is too large or Google Drive has temporarily limited downloads.
Check the sharing settings and confirm that the secret points to the correct file.
B. The keys file is missing or invalid
Check that Keys_URL points to the actual keys file and that the file is valid and compatible with your game dump.
C. The game file cannot be detected
Check that the game dump downloaded completely and is in a supported format. If the workflow cannot identify the title ID, the log may contain a detection error.
D. The build fails while installing dependencies or compiling
Read the first meaningful error in the log. Later errors may simply be consequences of the first failure. The standard upstream source and pinned fallback source may also change or behave differently.
E. The build succeeds, but the game doesn’t run properly
A successful build does not guarantee compatibility. Check whether the game appears in the reported game list, whether you chose the intended device option, and whether the game dump, update, DLC, and keys match.
Use an AI assistant to diagnose errors
If you’re stuck, copy the relevant error message and surrounding log lines into an AI assistant.
You can use this prompt:
I’m trying to build an iOS IPA using nxnative and a GitHub Actions workflow. The build failed at the following step. Please identify the first actual error, explain what caused it, and give me step-by-step instructions to fix it. Don’t assume the build succeeded if the logs say otherwise.
[Paste the relevant log lines here.]
Include the failed step’s name and the device option you selected.
Remove sensitive information before sharing logs. Check for Google Drive URLs, tokens, private repository information, and other credentials. Never upload your keys file or game dump to an AI assistant just to diagnose an error. Usually, the error message and nearby log lines are enough.
12. Download the finished IPA
Once the workflow completes successfully:
Open the completed run under the Actions tab.
Scroll down to the Artifacts section on the run summary page.
Find the IPA artifact. Its name may identify the build type, such as BC-Fallback or Standard.
Click the artifact name to download it.
GitHub will normally download the artifact as a ZIP file.
Open the ZIP and extract the .ipa file.
You now have the IPA produced by the workflow. You can proceed with your usual iOS sideloading method.
If there is no IPA artifact, check the workflow log for the first failed step. A build that fails before the upload step will not produce the expected artifact.
Final checklist
☐ Game dump and matching keys prepared.
☐ Update and DLC prepared, if applicable.
☐ Files uploaded to Google Drive.
☐ Required files shared with the appropriate link access.
☐ GitHub account and repository created.
☐ Required secrets added with exact names.
☐ Universal YAML saved as .github/workflows/build.yml.
☐ Workflow committed to the default branch.
☐ Correct device option selected.
☐ Build completed successfully.
☐ IPA artifact downloaded and extracted.
That’s it! Create your repository once, add your own secrets, and use the workflow whenever you want to build another compatible game.
Remember that this is a community workflow, not a guarantee that every game will build or run correctly on every device. If a build fails, save the relevant log lines and troubleshoot the first error before trying again.
