iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
You can use Gitea Actions to automate iOS builds, but the jobs need a registered Gitea Runner and Xcode must be available on a suitable macOS host. A dependable pipeline separates the Gitea server, runner, build and archive steps, and Apple distribution. Compilation alone does not sign an app for a particular audience or guarantee App Store Connect will accept it.
What you need before building
- A supported Gitea instance: Gitea’s Quick Start lists version 1.19.0 or later as the requirement. Actions are enabled by default starting with 1.21.0, but repository-level Actions must also be enabled in the repository settings.
- A registered Gitea Runner: Actions define the workflow; a separately installed runner executes its jobs. Register it at the appropriate scope using a registration token, then run it as a service. Gitea recommends running a runner separately from the Gitea instance so they do not compete for resources. See the Gitea Runner documentation.
- A Mac with the required toolchain: For an Xcode-based iOS build, the job needs a macOS host with the Xcode version required by the project. Check that the macOS and Xcode versions work together before configuring the runner; Apple’s upload guidance also notes that accepted Xcode versions are time-sensitive.
- Signing and distribution access: The requirements depend on whether you are distributing to registered devices, using TestFlight, or submitting to the App Store. Arrange the relevant Apple signing assets and account permissions for the chosen route.
Gitea documents host and container execution modes, including a macOS LaunchDaemon example in its Act Runner documentation. Do not assume a generic Linux container can provide Apple’s Xcode toolchain. A host runner can use Xcode installed on the Mac, while any isolation approach must still make the necessary host and toolchain available.
Configure Gitea and select a runner
- Check the Gitea version. Confirm the instance meets the Quick Start’s 1.19.0 minimum.
- Enable Actions where needed. Check the instance-level configuration and enable Actions for the repository in its settings. The fact that Actions are enabled by default from Gitea 1.21.0 does not remove the repository-level step.
- Register and run the macOS runner. Use a registration token at the scope appropriate to your repository, and configure the runner as a service on the Mac that has the required Xcode installation.
- Match the workflow label to the runner. Put the workflow YAML in
.gitea/workflows/. Setruns-onto a label the registered runner actually advertises; a label in the workflow does not create or configure a runner by itself.
Runner access is also a security boundary. Gitea cautions that runners should be used only with trusted repositories. Consider who can submit workflow changes and what secrets those workflows can access before choosing a persistent host or another isolation strategy.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesBuild, test, and archive the app
Make the workflow’s build choices explicit: check out the repository, select the intended Xcode scheme and destination, run the project’s tests and build steps, and create an archive. Apple describes archiving as a precursor to its distribution process in its Xcode distribution guidance.
#1 Best Overall
Keep the archive as a build output that can be inspected or passed to a later release job. Gitea supports workflow artifacts, which lets you keep outputs separate from the job logs. Avoid making a successful compile stand in for a completed release: signing, export, and upload are separate steps.
Choose how to distribute the build
| Route | What it is for | What to configure |
|---|---|---|
| Registered-device distribution | Testing on specified registered devices. | An app ID, an iOS-family distribution certificate, and provisioning that determines which devices are eligible. See Apple’s registered-device distribution guidance. |
| TestFlight | Beta testing through App Store Connect. | The team’s signing assets and appropriate App Store Connect account access. Apple’s distribution guidance describes this route. |
| App Store submission | Submitting a release through App Store Connect. | The team’s signing setup, App Store Connect access, and a build that meets current upload requirements. Check Apple’s build upload guidance. |
After creating the archive, choose the corresponding Xcode export or upload flow. For TestFlight and App Store delivery, uploads go through App Store Connect. Verify the currently accepted Xcode versions and upload requirements before pinning a toolchain for releases.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep release credentials limited to the release job
Separate routine build and test jobs from the job that exports or uploads a release. Make Apple signing credentials and distribution permissions available only to the job that needs them, and limit which trusted workflows can access those secrets. This reduces unnecessary exposure without assuming that any one runner layout is safest for every team.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Manual and automatic signing are both choices to make in light of the project’s release setup. Whichever approach you use, confirm that its certificates and provisioning match the intended distribution route; a successful archive does not by itself prove that the app is provisioned for the right devices or ready for App Store Connect.
Quick Recap
Rank #4
Common setup problems to check
- A workflow never starts: Confirm Actions is enabled for the repository, a runner is registered and online, and the workflow’s
runs-onlabel matches that runner’s configured labels. - The job cannot find Xcode: Confirm the job is running on the intended macOS host and that the required Xcode version is installed and available to the runner service.
- The build succeeds but distribution fails: Check the selected route’s signing assets and provisioning, then review the current App Store Connect upload requirements if uploading.
- A release job has more access than necessary: Review who can change workflow code and restrict signing secrets and distribution permissions to the release job and trusted repositories.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
