Skip to content

Latest commit

 

History

History
685 lines (486 loc) · 23.8 KB

README.md

File metadata and controls

685 lines (486 loc) · 23.8 KB

Apple Dev Scripts

Reusable Mise Tasks for common iOS and macOS development workflows.

📖 Documentation

This repository contains common scripts I use for the development of native iOS and macOS applications. It's an example of development tools configuration, not a fully featured solution. The scripts have minimal dependencies on some basic bash utilities. They do not depend on Ruby, Fastlane, Match, and other heavy tools. I use the scripts to build apps, run tests, archive, and deploy to App Store Connect and TestFlight. It works locally on a development machine, as well as on CI runners (both self-hosted and ephemeral).

Prerequisites

  • Xcode is installed, and developer tools are active.
  • Mise is installed and available in $PATH.
  • Tuist is used to generate Xcode workspace and projects.
  • App targets are configured to use automatic code signing.

Dependencies

Script dependencies are managed with Mise and defined in mise.toml file.

Usage

Copy Mise Tasks to your project repository and configure environment variables with Mise.

⚙️ Environment

Repository-wide default environment variables are defined in mise.toml:

Variable Description
TUIST_CACHE_CONFIGURATION Tuist binary cache build configuration (eg. Debug, Release, etc.).
TUIST_CACHE_PROFILE Tuist binary cache profile (eg. "only-external", or a custom profile defined by Tuist manifest).
XCODE_APP_SCHEME Default app scheme used by deployment-oriented tasks such as archive_app when --scheme is not provided.
IOS_SIMULATOR_NAME Default iOS simulator device name used by the test task.
TESTFLIGHT_GROUPS Comma-separated default TestFlight groups used by submit_to_testflight and deploy.

Build artifacts produced by repository tasks are stored under the repo-local build/ directory, which is ignored by git.

Scripts that require access to App Store Connect use the following environment variables:

Variable Description
APP_STORE_CONNECT_API_KEY_ID App Store Connect private key identifier.
APP_STORE_CONNECT_API_ISSUER_ID App Store Connect private key issuer.
APP_STORE_CONNECT_API_PRIVATE_KEY_PATH Path to App Store Connect private key file.

Archives skip developer code signing and apply ad-hoc signatures that preserve target entitlements. The automatic distribution export replaces them using App Store Connect credentials and cloud-managed signing. The build machine does not require an Apple Account in Xcode or a local signing identity.

🏗️ Mise Tasks

This repository defines development tasks as executable scripts in mise-tasks/*. Do not run the scripts directly. You can invoke a task from the command line using mise run:

$ mise run <task>

To list all available tasks, run:

$ mise tasks

▶️ Generate Workspace

Uses Tuist to:

  1. Install any remote content (e.g. dependencies) necessary to interact with the project.
  2. Inspect implicit and redundant dependencies in projects, failing when issues are found.
  3. Generate the Xcode workspace and projects.
Flag Description
--no-inspect Skip inspecting implicit and redundant dependencies in Tuist projects.
--no-install Skip installing any remote content (e.g. dependencies).
--cache-profile <cache-profile> Tuist cache profile. Defaults to the value of TUIST_CACHE_PROFILE environment variable.
--open Open generated workspace.

Source: mise-tasks/generate_workspace.sh

▶️ Warm Cache

Warms Tuist binary cache.

$ mise run warm_cache
Argument Description
--configuration <configuration> Build configuration to warm (eg. Debug, Release). Defaults to the value of TUIST_CACHE_CONFIGURATION environment variable.
--cache-profile <cache-profile> Tuist cache profile. Defaults to the value of TUIST_CACHE_PROFILE environment variable.
--no-install Skip installing any remote content (e.g. dependencies).

Source: mise-tasks/warm_cache.sh

▶️ Generate Workspace Graph

Uses Tuist to generate the workspace target dependency graph.

$ mise run generate_workspace_graph

Source: mise-tasks/generate_workspace_graph.sh

▶️ List Build Schemes

Lists all shared Xcode build schemes available in the workspace and project files.

$ mise run list_build_schemes

Source: mise-tasks/list_build_schemes.sh

▶️ Build

Builds the project using tuist xcodebuild and provided scheme and platform.

$ mise run build [--scheme <scheme>] --platform <platform>
Argument Description
--scheme <scheme> Xcode scheme name. Defaults to "{WorkspaceName}-Workspace" derived from the generated workspace file name.
--platform <platform> Platform. "macOS" or "iOS".

The task expects the workspace is already generated. Derived data is written under the repo-local build/DerivedData directory.

Source: mise-tasks/build.sh

▶️ Test

Runs tests using tuist xcodebuild and provided scheme and platform.

$ mise run test [--scheme <scheme>] --platform <platform>
Argument Description
--scheme <scheme> Xcode scheme name. Defaults to "{WorkspaceName}-Workspace" derived from the generated workspace file name.
--platform <platform> Platform. "macOS" or "iOS". iOS tests use the IOS_SIMULATOR_NAME environment variable to choose the simulator device.

The task expects the workspace is already generated. Derived data is written under the repo-local build/DerivedData directory.

Source: mise-tasks/test.sh

▶️ Set build number

Sets the app build number in the generated Xcode project without changing the Tuist manifest.

$ mise run set_build_number [<build_number>]
Argument Description
<build_number> Build number. Defaults to the current build number plus one.

Source: mise-tasks/set_build_number.sh

▶️ Get latest App Store Connect build number

Gets the latest uploaded or pending build number for one platform across all marketing versions.

$ mise run get_latest_app_store_build_number --platform <platform>
Argument Description
--platform <platform> macOS or iOS.

Requires a generated workspace and App Store Connect credentials.

Source: mise-tasks/get_latest_app_store_build_number.sh

▶️ Set next build number

Gets the latest iOS and macOS build numbers from App Store Connect, increments the greater value, and applies the result to the generated Xcode project.

$ mise run set_next_build_number

Requires a generated workspace and App Store Connect credentials.

Source: mise-tasks/set_next_build_number.sh

▶️ Archive app

Archives the app for one platform.

$ mise run archive_app [--scheme <scheme>] --platform <platform>
Argument Description
--scheme <scheme> Xcode scheme. Defaults to XCODE_APP_SCHEME.
--platform <platform> macOS or iOS.

Requires a generated workspace. The archive step does not use App Store Connect credentials. It ad-hoc-signs the app and embedded products using entitlements resolved from targets in the app's generated Xcode project. Archives are written to build/archives.

Source: mise-tasks/archive_app.sh

▶️ Upload archive

Exports and uploads an archived app to App Store Connect.

$ mise run upload_archive [--scheme <scheme>] --platform <platform>
Argument Description
--scheme <scheme> Xcode scheme. Defaults to XCODE_APP_SCHEME; use the value passed to archive_app.
--platform <platform> macOS or iOS.

Requires the matching archive and App Store Connect credentials. Export and upload failures are retried every 30 seconds without a script-level attempt limit; cancel a local run manually. The deployment workflow constrains each upload step to 20 minutes. Exported packages are written to build/exports.

Source: mise-tasks/upload_archive.sh

▶️ Get release metadata

Gets the marketing version, build number, and bundle identifier from the generated app build settings as compact JSON.

$ mise run get_release_metadata

Requires a generated workspace.

Source: mise-tasks/get_release_metadata.sh

▶️ Add release tag

Creates a local Git tag from the current marketing version and build number, such as v1.2.3-456.

$ mise run add_release_tag

The task fails when the tag already exists.

Source: mise-tasks/add_release_tag.sh

▶️ Generate WhatToTest file

Generates TestFlight "What to Test" notes from commits since the previous release tag.

$ mise run generate_whattotest [--version <version>] [--build <build>]
Argument Description
--version <version> Marketing version used in the release-tag URL. Defaults to the value in the generated workspace.
--build <build> Build number used in the release-tag URL. Defaults to the value in the generated workspace.

Requires full Git history and tags. A generated workspace is required only when version or build number is not provided explicitly.

Source: mise-tasks/generate_whattotest.sh

▶️ Submit to TestFlight

Submits an uploaded build to the groups selected by --groups or TESTFLIGHT_GROUPS. When any selected group is external, the task also submits the build for TestFlight App Review. If TestFlight/WhatToTest.en-US.txt exists, its contents become the en-US "What to Test" text. The task applies these notes as soon as the uploaded build is available. It retries build availability and states that may become ready without user interaction every 30 seconds without imposing its own timeout. Unknown states remain retryable for forward compatibility. Terminal states and states that require user interaction fail immediately. The caller controls the deadline; cancel a manual run with Ctrl+C.

$ mise run submit_to_testflight --platform <platform>
Argument Description
--platform <platform> macOS or iOS.
--version <version> Marketing version. Defaults to the value in the generated workspace.
--build <build> Build number. Defaults to the value in the generated workspace.
--bundle-id <bundle_id> App bundle identifier. Defaults to the value in the generated workspace.
--groups <groups> Comma-separated TestFlight groups. Defaults to TESTFLIGHT_GROUPS.

Requires an uploaded build, at least one configured TestFlight group, and App Store Connect credentials. A generated workspace is required only when version, build number, or bundle identifier is not provided explicitly.

Source: mise-tasks/submit_to_testflight.sh

▶️ Deploy

Runs the complete local release pipeline: generate the workspace, select and set the next build number, archive and upload iOS and macOS, create a local release tag, generate "What to Test" notes, and submit both builds to TESTFLIGHT_GROUPS.

The GitHub Actions deployment gives the archive-and-upload job 60 minutes and constrains each retrying upload step to 20 minutes. It then passes the non-sensitive version, build number, and bundle identifier to independent iOS and macOS TestFlight submission jobs with a 30-minute limit per platform. The submission matrix runs at most one platform job at a time on the self-hosted runner. Each submission job generates its own "What to Test" notes from the complete Git history; the jobs do not transfer archives or generate the workspace. A submission failure or workflow timeout fails only that platform's job without cancelling the other submission. Rerun the failed or specific platform job to regenerate the notes and retry submission without archiving or uploading again.

$ mise run deploy

Requires the release environment and App Store Connect credentials described above.

Source: mise-tasks/deploy.sh

▶️ Validate Documentation

Validates the repository's canonical Markdown and instruction surfaces:

  1. Lints Markdown and verifies local links and heading fragments with the pinned rumdl version.
  2. Verifies that every tracked or non-ignored untracked topic document is linked from the configured documentation index.
  3. Checks mise run <task> references across documentation, agent instructions, GitHub templates, and project skills.
  4. Verifies that every repository task is documented in this file.
  5. Verifies the AGENTS.md/CLAUDE.md and skill-directory symlink contracts.
$ mise run validate_docs

Source: mise-tasks/validate_docs.sh

▶️ Check Spelling

Checks spelling across the worktree with the pinned typos version and repository configuration. Hidden files are included; ignored and generated paths remain excluded. The task reports issues without rewriting files.

$ mise run lint_spelling

Source: mise-tasks/lint_spelling.sh

▶️ Lint Shell Scripts

Runs shellcheck against all shell scripts in the repository.

$ mise run lint_shell_scripts

Source: mise-tasks/lint_shell_scripts.sh

🔁 Continuous Integration

Mise tasks can be used on a CI server. You can find example GitHub Action workflow definitions below.

⚙️ CI action: Setup Mise

.github/actions/setup-mise/action.yml
name: Setup Mise
description: Trust the repository and install its locked Mise tools.

runs:
  using: composite
  steps:
    - name: Install dependencies
      shell: bash
      run: |
        set -euo pipefail
        mise --version
        mise trust
        mise install --locked

⚙️ CI action: Setup App Store Connect API key

.github/actions/setup-asc-key/action.yml
name: Setup App Store Connect API key
description: Materialize App Store Connect credentials for the current job.

inputs:
  app-store-connect-api-key-id:
    description: App Store Connect API key identifier.
    required: true
  app-store-connect-api-issuer-id:
    description: App Store Connect API key issuer identifier.
    required: true
  app-store-connect-api-private-key:
    description: App Store Connect API private key contents.
    required: true

runs:
  using: composite
  steps:
    - name: Configure App Store Connect API key
      shell: bash
      env:
        APP_STORE_CONNECT_API_KEY_ID: ${{ inputs.app-store-connect-api-key-id }}
        APP_STORE_CONNECT_API_ISSUER_ID: ${{ inputs.app-store-connect-api-issuer-id }}
        APP_STORE_CONNECT_API_PRIVATE_KEY: ${{ inputs.app-store-connect-api-private-key }}
      run: |
        set -euo pipefail

        private_key_path="$(mktemp "${RUNNER_TEMP}/app-store-connect-api-key.XXXXXX.p8")"
        printf '%s' "${APP_STORE_CONNECT_API_PRIVATE_KEY}" > "${private_key_path}"
        chmod 600 "${private_key_path}"

        {
          echo "APP_STORE_CONNECT_API_KEY_ID=${APP_STORE_CONNECT_API_KEY_ID}"
          echo "APP_STORE_CONNECT_API_ISSUER_ID=${APP_STORE_CONNECT_API_ISSUER_ID}"
          echo "APP_STORE_CONNECT_API_PRIVATE_KEY_PATH=${private_key_path}"
        } >> "${GITHUB_ENV}"

🧪 CI workflow: Test

Run all tests defined in Xcode workspace on macOS and iOS.

.github/workflows/test.yml
name: Test

on:
  workflow_dispatch:
  pull_request:
    branches:
      - main
    types:
      - opened
      - ready_for_review
      - reopened
      - synchronize
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: test-${{ github.event.pull_request.number || github.ref_name }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: [self-hosted, macOS, ARM64]
    timeout-minutes: 30

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          clean: true

      - name: Setup Mise
        uses: ./.github/actions/setup-mise

      - name: Validate documentation
        run: mise run validate_docs

      - name: Lint shell scripts
        run: mise run lint_shell_scripts

      - name: Check spelling
        run: mise run lint_spelling

      - name: Generate workspace
        run: mise run generate_workspace

      - name: Run tests (macOS)
        run: mise run test --platform macOS

      - name: Run tests (iOS)
        run: mise run test --platform iOS

      - name: Upload logs
        if: ${{ always() }}
        uses: actions/upload-artifact@v7
        with:
          name: logs
          path: build/Logs/*
          if-no-files-found: warn
          retention-days: 7

🚀 CI workflow: Deploy

Bump app build number, archive iOS and macOS app, upload archives to App Store Connect, generate "What To Test" notes, and submit to TestFlight.

.github/workflows/deploy.yml
name: Deploy

on:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: deploy-${{ github.ref_name }}
  cancel-in-progress: false

jobs:
  archive_and_upload:
    name: Archive and upload
    runs-on: [self-hosted, macOS, ARM64]
    timeout-minutes: 60
    permissions:
      contents: write
    outputs:
      marketing_version: ${{ steps.release_metadata.outputs.marketing_version }}
      build_number: ${{ steps.release_metadata.outputs.build_number }}
      bundle_id: ${{ steps.release_metadata.outputs.bundle_id }}

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          clean: true
          fetch-depth: 0

      - name: Setup Mise
        uses: ./.github/actions/setup-mise

      - name: Setup App Store Connect API key
        uses: ./.github/actions/setup-asc-key
        with:
          app-store-connect-api-key-id: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
          app-store-connect-api-issuer-id: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
          app-store-connect-api-private-key: ${{ secrets.APP_STORE_CONNECT_API_PRIVATE_KEY }}

      - name: Generate workspace
        run: mise run generate_workspace

      - name: Configure git identity
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Resolve and set build number
        run: mise run set_next_build_number

      - name: Archive app (macOS)
        run: mise run archive_app --platform macOS

      - name: Archive app (iOS)
        run: mise run archive_app --platform iOS

      - name: Upload archive (macOS)
        timeout-minutes: 20
        run: mise run upload_archive --platform macOS

      - name: Upload archive (iOS)
        timeout-minutes: 20
        run: mise run upload_archive --platform iOS

      - name: Create and push release tag
        run: |
          set -euo pipefail
          release_tag="$(mise run --output quiet add_release_tag)"
          git push origin "refs/tags/${release_tag}"

      - name: Export release metadata
        id: release_metadata
        run: |
          set -euo pipefail
          metadata="$(mise run --output quiet get_release_metadata)"

          {
            printf 'marketing_version=%s\n' "$(printf '%s' "${metadata}" | mise x -- jq -r '.marketing_version')"
            printf 'build_number=%s\n' "$(printf '%s' "${metadata}" | mise x -- jq -r '.build_number')"
            printf 'bundle_id=%s\n' "$(printf '%s' "${metadata}" | mise x -- jq -r '.bundle_id')"
          } >> "${GITHUB_OUTPUT}"

      - name: Upload logs
        if: ${{ always() }}
        uses: actions/upload-artifact@v7
        with:
          name: logs
          path: build/Logs/*
          if-no-files-found: warn
          retention-days: 7

      - name: Cleanup App Store Connect API key
        if: ${{ always() }}
        run: |
          if [[ -n "${APP_STORE_CONNECT_API_PRIVATE_KEY_PATH:-}" ]]; then
            rm -f "${APP_STORE_CONNECT_API_PRIVATE_KEY_PATH}"
          fi

  submit_to_testflight:
    name: Submit to TestFlight (${{ matrix.platform }})
    needs: archive_and_upload
    runs-on: [self-hosted, macOS, ARM64]
    timeout-minutes: 30
    env:
      RELEASE_MARKETING_VERSION: ${{ needs.archive_and_upload.outputs.marketing_version }}
      RELEASE_BUILD_NUMBER: ${{ needs.archive_and_upload.outputs.build_number }}
      RELEASE_BUNDLE_ID: ${{ needs.archive_and_upload.outputs.bundle_id }}
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        platform: [iOS, macOS]

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          clean: true
          fetch-depth: 0

      - name: Setup Mise
        uses: ./.github/actions/setup-mise

      - name: Setup App Store Connect API key
        uses: ./.github/actions/setup-asc-key
        with:
          app-store-connect-api-key-id: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
          app-store-connect-api-issuer-id: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
          app-store-connect-api-private-key: ${{ secrets.APP_STORE_CONNECT_API_PRIVATE_KEY }}

      - name: Generate WhatToTest
        run: |
          set -euo pipefail
          : "${RELEASE_MARKETING_VERSION:?Missing marketing version}"
          : "${RELEASE_BUILD_NUMBER:?Missing build number}"

          mise run generate_whattotest \
            --version "${RELEASE_MARKETING_VERSION}" \
            --build "${RELEASE_BUILD_NUMBER}"

      - name: Submit to TestFlight
        run: |
          set -euo pipefail

          : "${RELEASE_MARKETING_VERSION:?Missing marketing version}"
          : "${RELEASE_BUILD_NUMBER:?Missing build number}"
          : "${RELEASE_BUNDLE_ID:?Missing bundle identifier}"

          if [[ "${GITHUB_REF_NAME}" == "main" ]]; then
            testflight_groups="$(mise env --json | mise x -- jq -r '.TESTFLIGHT_GROUPS')"
          else
            testflight_groups="Internal"
          fi
          : "${testflight_groups:?Missing TestFlight groups}"

          mise run submit_to_testflight \
            --platform "${{ matrix.platform }}" \
            --version "${RELEASE_MARKETING_VERSION}" \
            --build "${RELEASE_BUILD_NUMBER}" \
            --bundle-id "${RELEASE_BUNDLE_ID}" \
            --groups "${testflight_groups}"

      - name: Cleanup App Store Connect API key
        if: ${{ always() }}
        run: |
          if [[ -n "${APP_STORE_CONNECT_API_PRIVATE_KEY_PATH:-}" ]]; then
            rm -f "${APP_STORE_CONNECT_API_PRIVATE_KEY_PATH}"
          fi

☕️ Do you like the project?

I would love to hear if you like my work. I can help you apply any of the solutions used in this repository in your app too! Feel free to reach out to me, or if you just want to say "thanks", you can buy me a coffee.

Buy Me A Coffee

📄 License

Copyright © 2026 Dariusz Rybicki Darrarski

MIT LICENSE