Bangun dan Pasang Aplikasi iOS dengan Aksi Gitea

Gitea Actions dapat membangun aplikasi iOS, tetapi hanya pada Mac yang Anda daftarkan sendiri, karena Gitea tidak memiliki runner yang dihost dan Xcode hanya dapat menjalankan pada macOS. Dua setup yang praktis adalah Mac yang menjalankan act_runner dalam mode host, atau runner Linux normal yang mengirimkan konstruksi iOS ke layanan konstruksi awan. Panduan ini menjelajahi kedua setup tersebut untuk aplikasi Capacitor dengan file workflow yang dapat Anda masukkan .gitea/workflows/.

Tim memilih Gitea karena mereka ingin code mereka di infrastruktur yang mereka kendalikan. Hal itu tidak harus berubah hanya karena aplikasi memerlukan Xcode. Kedua setup di bawah ini menjaga sumber Anda di server Anda.

How Gitea Actions menjalankan pekerjaan

Gitea Actions menggunakan sintaks GitHub yang kompatibel dengan Actions, dan pekerjaan dijalankan pada act_runner instans yang Anda daftarkan terhadap server Gitea Anda. Setiap runner mengiklankan label seperti ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latestBagian setelah titik dua menentukan bagaimana pekerjaan dijalankan:

• docker://image menjalankan pekerjaan dalam kontainer. Ini adalah default untuk runner Linux.
• host menjalankan pekerjaan secara langsung pada mesin, dengan apa saja yang terinstal di sana.

macOS tidak dapat menjalankan dalam kontainer Docker, sehingga runner Mac harus menggunakan host label. Hal ini memiliki konsekuensi yang akan kita bahas nanti.

Catatan kompatibilitas dua hal sebelum Anda menyalin alur kerja dari GitHub:

• Gitea membaca .gitea/workflows/ dan kembali ke .github/workflows/ ketika folder pertama tidak ada.
• uses: actions/checkout@v4 berfungsi karena Gitea menyelesaikan aksi dari GitHub secara default (pengaturan). DEFAULT_ACTIONS_URL Instansi yang terisolasi udara perlu menggandakan aksi yang digunakan dan merujuk ke mereka dengan URL penuh.

Option 1: Runner Mac dengan act_runner

Pendaftaran Mac

Unduh file act_runner biner untuk macOS (arm64 untuk Apple Silicon) dari halaman rilis Gitea, kemudian dapatkan token pendaftaran dari Pengelolaan Situs > Aksi > Runner (secara instansi), atau dari pengaturan organisasi atau repositori.

./act_runner register --no-interactive \
  --instance https://gitea.example.com \
  --token <registration_token> \
  --name mac-mini-01 \
  --labels macos-arm64:host

./act_runner daemon

Jalankan daemon sebagai agen peluncuran di bawah pengguna dedikasi sehingga dapat diulang setelah restart dan memiliki kunci login sendiri.

Pasang toolkit pada host

Pasang mode host berarti pekerjaan menggunakan alat Mac sendiri. Pasang:

• Xcode 26 (diperlukan untuk unggah ke App Store Connect sejak 28 April 2026) dan jalankan sudo xcodebuild -license accept
• Node.js 22 atau lebih baru dan Bun (Capacitor 8 memerlukan Node 22)
• Ruby dan fastlane, atau gunakan Gemfile dengan bundle exec
• CocoaPods, hanya jika proyek iOS Anda masih menggunakan itu. Proyek Capacitor 8 baru menggunakan Swift Package Manager.

Alur kerja

# .gitea/workflows/ios-mac.yaml
name: iOS release (Mac runner)

on:
  push:
    tags:
      - 'v*'

jobs:
  ios:
    runs-on: macos-arm64
    env:
      APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
      APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
      APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
      P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
      APP_STORE_CONNECT_TEAM_ID: ${{ vars.APP_STORE_CONNECT_TEAM_ID }}
      PROFILE_NAME: ${{ vars.IOS_PROFILE_NAME }}
    steps:
      - uses: actions/checkout@v4
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ios
      - name: Decode signing files
        run: |
          echo "${{ secrets.IOS_CERTIFICATE_BASE64 }}" | base64 --decode > dist.p12
          echo "${{ secrets.IOS_PROFILE_BASE64 }}" | base64 --decode > profile.mobileprovision
      - run: bundle exec fastlane ios beta
      - name: Clean up
        if: always()
        run: rm -f dist.p12 profile.mobileprovision

The beta jalur mengimpor sertifikat ke sebuah keychain sementara, mengubah proyek ke tanda tangan manual, meningkatkan nomor pembangunan dari TestFlight, mengarsipkan, dan mengunggah. File Fastfile lengkap untuk proyek Capacitor ada di Membangun dan mengunggah aplikasi iOS dengan Bitbucket PipelinesUntuk Gitea, itu berfungsi tanpa perubahan. Untuk latar belakang fastlane, lihat GitHub Actions iOS guide.

Biaya Modus Host

The act_runner documentasi langsung tentang hal ini: host pekerjaan tidak terisolasi. Dalam prakteknya:

• Pekerjaan apa pun menggunakan pengguna, disk, dan keychain yang sama. Jika pekerjaan mati setengah jalan, maka dapat meninggalkan keychain sementara atau profil pengaturan yang ketinggalan waktu yang dapat mengganggu pekerjaan berikutnya.
• Setiap alur kerja yang menargetkan label menjalankan code pada Mac tersebut dengan akses pengguna. Hanya daftarkan runner host untuk repositori yang Anda percayai, dan hindari menjalankannya pada permintaan pull dari fork.
• Data Derived, arsip, dan runtime simulator tumbuh hingga disk penuh.
• Pembaruan Xcode ada di tangan Anda, dan Apple meningkatkan minimum SDK setiap musim semi.
• Satu Mac membangun satu pekerjaan pada satu waktu. Antrian hari raya.

Jika tim Anda sudah menjalankan Mac dan ada orang yang mengelolanya, maka ini berfungsi. Jika tidak, maka pilihan berikut menghilangkan Mac dari infrastruktur Anda.

Pilihan 2: Bangun iOS dari runner Linux dengan Capgo Build

Capgo Build Memproses dan menandatangani Capacitor aplikasi pada Capgo-dikelola Mac. Pekerjaan Gitea Anda tetap pada runner Linux yang sudah Anda miliki. Pekerjaan tersebut mengecek keluaran code, membangun layer web, menjalankan cap sync ios, dan memanggil build request. Capgo CLI mengunggah proyek native yang disiapkan, mengalirkan log Xcode ke dalam log pekerjaan Gitea, dan keluar dengan kode tidak nol jika gagal.

Model ini cocok untuk Gitea yang di-host sendiri:

• Tidak ada akses masuk. Capgo tidak mengklon repositori Anda. Runner Anda mengirimkan proyek yang disiapkan melalui HTTPS, sehingga server Gitea di balik firewall atau VPN dapat berjalan tanpa perubahan.
• Tidak ada token repositori. Tidak ada koneksi Git untuk dikonfigurasi di sisi Capgo.
• Sumber web Anda tetap di rumah. Hanya untuk aplikasi asli ios/ folder, konfigurasi Capacitor, dan bagian native dari plugin diunggah. src/, .git/, and .env Pengaturan sekali saja

Di mesin pengembang:

Pengaturan sekali saja

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add
bunx @capgo/cli@latest build init --platform ios

build init Sertifikat distribusi (membuat atau menggunakan kembali sertifikat distribusi Anda dan profil pengaturan App Store, dan menyimpan kunci API App Store Connect. Jalankan satu build lokal untuk memastikan semuanya tanda tangan:

bun run build && bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

Lalu ekspor kunci tersebut:

bunx @capgo/cli@latest build credentials manage --appId com.example.app --platform ios
# select "Export to .env"

Tambahkan rahasia ke Gitea

Buka Pengaturan Repositori > Aksi > Rahasia Dan tambahkan setiap kunci dari file yang diekspor, plus kunci Capgo API Anda:

Gitea menolak nama rahasia dan variabel yang dimulai dengan GITEA_ atau GITHUB_Tetapkan nama-nama tersebut seperti itu. Masukkan nilai-nilai non-rahasia seperti ID aplikasi di bawah. Variables dan baca mereka dengan ${{ vars.NAME }}. Secrets set at the organization level are shared by every repository in it, which is handy when you ship several apps from one Apple team. Delete the exported file when you are done.

Rilis pada tag push

# .gitea/workflows/ios-release.yaml
name: iOS release

on:
  push:
    tags:
      - 'v*'

jobs:
  release-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ios
      - name: Build, sign, and upload to TestFlight
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
        run: |
          bunx @capgo/cli@latest build request ${{ vars.APP_ID }} \
            --platform ios \
            --build-mode release \
            --ios-distribution app_store \
            --store-release-name "${{ gitea.ref_name }}"

Catatan:

• ${{ gitea.ref_name }} Nama tagnya. Tag tersebut github.* Konteks juga berfungsi sebagai alias, yang membantu ketika Anda memindahkan alur kerja.
• Gitea CI=true dalam setiap pekerjaan, sehingga Capgo CLI tidak pernah menunggu input interaktif.
• Capgo meningkatkan nomor pembangunan dari pembangunan TestFlight terakhir, sehingga dua tag dalam satu baris tidak pernah bertabrakan.
• Without --submit-to-store-reviewBuildnya berhenti di TestFlight dan berhenti. Tambahkan flag jika Anda ingin CI mengajukan aplikasi untuk tinjauan juga.

Mengeluarkan git tag v2.3.0 && git push origin v2.3.0Siapa pun yang bisa mengirimkan push v* Tambahkan aturan tag terlindungi untuk tag yang dapat dikirimkan v* bawah Pengaturan > Tag dan batasi hanya untuk manajer rilis.

Pembangunan ad-hoc untuk tester

Untuk pembangunan QA yang langsung diinstal pada perangkat yang terdaftar, bangunlah dalam mode ad-hoc dan dapatkan tautan download:

# .gitea/workflows/ios-adhoc.yaml
name: iOS ad hoc build

on:
  workflow_dispatch:

jobs:
  adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile && bun run build
      - run: bunx cap sync ios
      - name: Ad hoc build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
        run: |
          echo "${{ secrets.ADHOC_PROFILE_BASE64 }}" | base64 --decode > adhoc.mobileprovision
          bunx @capgo/cli@latest build request ${{ vars.APP_ID }} \
            --platform ios \
            --ios-distribution ad_hoc \
            --ios-provisioning-profile ./adhoc.mobileprovision \
            --output-upload --output-retention 3d \
            --output-record /tmp/build.json
          bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl

Ad hoc build memerlukan profil pengembangan ad hoc yang mencantumkan perangkat pengujian. Simpan profil tersebut dalam bentuk base64 sebagai rahasia (ADHOC_PROFILE_BASE64 atas), dekodifikasikan di dalam pekerjaan, dan berikan bersama dengan --ios-provisioning-profile. CLI flag memiliki prioritas lebih tinggi daripada variabel lingkungan, sehingga ini mengalahkan profil App Store untuk pembangunan ini saja. Kumpulkan UDIDs dengan Pencari UDID iOS. Untuk sebagian besar tester, pengujian internal TestFlight lebih sederhana, karena tidak memerlukan UDIDs.

Pengesahan rilis manual

GitHub memungkinkan Anda memerlukan reviewer pada lingkungan. Gitea Actions tidak mengimplementasikan aturan perlindungan lingkungan, sehingga pekerjaan yang menyebutkan lingkungan tidak akan berhenti untuk menunggu persetujuan. Dua pola yang berhasil adalah:

1. Tag yang dilindungi. Hanya pengelola rilis yang dapat mengirimkan v* tag, dan alur kerja tag berlayar.
2. Buat, kemudian promosikan. Buat pada setiap push ke main dengan --ios-distribution ad_hoc atau unggah ke TestFlight pengujian internal hanya, kemudian gunakan workflow_dispatch Alur kerja (tersedia dalam rilis Gitea saat ini) untuk membangun kembali komit yang disetujui dengan --submit-to-store-review.

Tayangkan perubahan web tanpa binary baru

Komit kebanyakan ke aplikasi Capacitor hanya mengubah JavaScript, CSS, dan HTML. Membangun kembali iOS untuk itu akan menghabiskan menit dan waktu App Review. Dengan Capgo pembaruan hidupSatu pekerja dapat memilih jalur yang tepat:

      - name: Live update or native build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # plus the iOS signing secrets from above
        run: |
          if bunx @capgo/cli@latest build needed ${{ vars.APP_ID }} --channel production; then
            bunx @capgo/cli@latest bundle upload ${{ vars.APP_ID }} --channel production
          else
            bunx cap sync ios
            bunx @capgo/cli@latest build request ${{ vars.APP_ID }} --platform ios --build-mode release
          fi

build needed satu pekerja dapat memilih jalur yang tepat: exit 0 ketika dependensi native sesuai dengan apa yang hidup di saluran, dan 1 ketika binary baru diperlukan. Juga paksa jalur native ketika file di ios/ atau capacitor.config.* perubahan, karena itu tidak termasuk perbandingan dependensi. Lihat Pilih otomatis live update atau build native.

Memilih otomatis __CAPGO_KEEP_0__ atau pembangunan asli

Miliki sendiri

Untuk mode gagal lainnya, lihat CI/CD untuk Capacitor: kelemahan umum dan Capgo Build troubleshooting guide.

Summary

Gitea Actions handles iOS fine once you decide where Xcode runs. A host-mode Mac runner gives you full control and full responsibility. A Linux job that calls Capgo Build keeps your Gitea setup unchanged, needs no inbound access, and turns a TestFlight release into a tag push. Whichever you choose, keep signing material in Gitea secrets, protect your release tags, and ship web-only changes as live updates so the native pipeline only runs when it has to.