In my previous article, I wrote about why I built Git Guardian: I wanted to stop spending code review time on branch names and commit message formats.

This article is a hands-on follow-up. I’ll install the package in a fresh repository, try an invalid branch name, create a valid branch, and make a commit. You can follow along in your own project.

Start with a test repository

You’ll need Node.js 20 or later and Git 2.28 or later. Git Guardian is an npm package, so the repository also needs a package.json.

For a quick test, create a new directory:

mkdir git-guardian-demo
cd git-guardian-demo
npm init -y
git init

Install the scoped package:

npm install --save-dev @agnotic/git-guardian

Then run the setup wizard:

npx git-guardian init

The wizard creates a .git-guardian.yml file and installs the Git hooks. You can press Enter to accept the defaults.

With the default settings, branch names follow this format:

<type>/<number>-<description>

For example:

feat/123-add-login

The allowed branch and commit types default to feat, chore, bugfix, and task.

Check that the hooks are installed

Run the doctor command:

npx git-guardian doctor

Here’s the kind of output I saw:

Git Guardian doctor
✓ Repository: /path/to/git-guardian-demo
✓ Config: /path/to/git-guardian-demo/.git-guardian.yml
✓ Git 2.51.1 supports branch transaction guarding.
✓ Secret scanning is on for commits.
→ Hooks directory: /path/to/git-guardian-demo/.git/hooks
✓ reference-transaction hook installed and executable.
✓ commit-msg hook installed and executable.
✓ Everything looks good.

The two hooks have different jobs:

• reference-transaction checks branch creation.
• commit-msg checks commit messages and, when enabled, scans staged changes for common secret patterns.

See what happens to an invalid branch

Try creating a branch that doesn’t follow the configured format:

git switch -c wip/login

Git Guardian stops the branch from being created and explains why:

✗ Branch creation blocked: wip/login
Branch "wip/login" doesn't follow the format <type>/<number>-<description>
"wip" is not an allowed type.

Format:  <type>/<number>-<description>
  <type>         one of: feat, chore, bugfix, task
  <number>       a number, e.g. 123
  <description>  lowercase words joined by hyphens, e.g. add-login
Example: feat/123-add-login

Try:
  feat/<number>-wip-login
  chore/<number>-wip-login
  bugfix/<number>-wip-login
  (replace any <placeholder> left in a suggestion)
fatal: ref updates aborted by hook

The branch is rejected before Git creates it. The error also shows which part of the name failed and gives examples of the required format.

Now create a valid branch:

git switch -c feat/123-add-login

This time, Git switches to the new branch.

Make a commit

Create a small file, stage it, and commit it:

echo "Hello from the tutorial" > example.txt
git add example.txt
git commit -m "feat: add tutorial example"

The commit message matches the default format, so Git records the commit.

You can also check a name or message without trying to create a branch or commit:

npx git-guardian validate branch feat/123-add-login
npx git-guardian validate commit -m "feat: add tutorial example"

And if you have a ticket title or rough description, ask for branch suggestions:

npx git-guardian branch suggest "ABC-42 Fix login crash"

Example output:

Suggested branch names
  bugfix/42-login-crash
  feat/42-login-crash
  chore/42-login-crash

Test the secret check safely

With secret scanning enabled, Git Guardian checks staged changes for common patterns. To see it work, use a fake token in a throwaway test file, never paste a real credential into your repository:

echo "ghp_123456789012345678901234567890123456" > fake-token.txt
git add fake-token.txt
git commit -m "chore: test secret detection"

The commit is blocked, and the detected value is masked:

✗ Commit blocked by Git Guardian: possible secrets found.
  fake-token.txt:1  GitHub token  ghp_************

What to do:
  Remove the value and load it from an environment variable or secret manager instead.

This is a local guardrail for common patterns. It isn’t a replacement for your Git host’s secret scanning or push protection. If a real credential has already been pushed, revoke and rotate it.

After the test, remove the staged test file:

git restore --staged fake-token.txt
rm fake-token.txt

Where the rules live

The wizard writes the policy to .git-guardian.yml. A default configuration looks like this:

version: 1
branch:
  enabled: true
  format: "<type>/<number>-<description>"
  types: "feat,chore,bugfix,task"
  protected: "main,master,develop,development,staging,production"
  suggestions: true
commit:
  enabled: true
  format: "<type>: <description>"
  types: "feat,chore,bugfix,task"
  maxSubjectLength: 72
  autoTicket: true
secrets:
  enabled: true
  allow: ""
hooks:
  referenceTransaction: true
  commitMsg: true

You can commit this file so the policy is shared with your team. The hook files are installed locally in each clone, so teammates need to set them up after pulling the repository:

npm install
npx git-guardian install
npx git-guardian doctor

What the test showed

In a fresh repository, the main flow is short: install the package, run init, check the hooks with doctor, and try a branch and commit.

The useful part is when a rule fails. Instead of discovering a naming problem during a pull request, the developer gets feedback in the terminal while creating the branch or committing.

For team use, add matching checks to CI as well. Local hooks can be skipped with --no-verify, and every clone needs its own hook installation.

Try it with your own conventions:

npm install --save-dev @agnotic/git-guardian
npx git-guardian init
npx git-guardian doctor

• Git Guardian on npm
• Guardian Engineering Toolkit on GitHub

Explore git-guardian

A pull request should be an engineering conversation about the code: architecture, edge cases, and performance.
Yet far too often, the very first review comment is:

“Please rename the branch to match our Jira ticket format.”

The second comment is:

“Can you update the commit message to follow Conventional Commits?”

Neither comment improves the code. Both interrupt the review flow. And when senior engineers spend cognitive energy playing syntax police across five different repositories, it becomes an exhausting chore.

I kept hitting this while leading mobile, web, and backend engineering teams. We had documented conventions. We held onboarding sessions. Yet adherence still relied on human memory, peer vigilance, and manual corrections.

That frustration led me to build @agnotic/git-guardian: an opinionated, batteries-included Git validation tool designed to eliminate conventions friction once and for all.

The Problem Is Bigger Than Untidy Names

A branch named login-fix makes sense to its author on Tuesday afternoon. A commit message that says "fixed stuff" feels adequate when the diff is fresh in your head.

Three months later, an engineer is debugging a production incident or bisecting a regression. That shorthand now gives them nothing to work with.

Compare:

Branch: loginfix
Commit: fixed

With:

Branch: fix/AUTH-123-expired-token
Commit: fix(AUTH-123): handle expired access tokens gracefully

The second version provides instant situational awareness. It links the change to a Jira/Linear ticket, defines the functional domain, and describes the actual behavior modified.

Consistent naming won’t solve every engineering challenge, but it eradicates avoidable ambiguity. The real challenge is making that consistency effortless to follow.

What Git Guardian Does Differently

Most teams attempt to solve this by stitching together custom bash scripts, husky, and commitlint. While powerful, this setup usually involves maintaining fragile regular expressions, boilerplate hook files, and separate linters.

With git-guardian, the developer experience is built around five core pillars:

1. Human-Readable Formats (No Regular Expressions)

You don’t configure complex regex patterns. Conventions are declared with plain placeholders in .git-guardian.yml:

branch:
  format: "<type>/<ticket>-<description>"
  types: "feat,chore,fix,task"
commit:
  format: "<type>(<ticket>): <description>"
  autoTicket: true

2. Native Git Branch Guarding

Unlike tools that only run at commit time, Git Guardian utilizes Git’s native reference-transaction hook. If an engineer runs git switch -c bad-name or git checkout -b temp, Git Guardian intercepts the action before the branch is even created, displays what failed, and suggests valid names based on what they typed.

3. Automatic Ticket Enrichment

Developers often forget to repeat their ticket ID in commit messages. When commit.autoTicket: true is enabled, Git Guardian automatically detects the ticket (e.g., AUTH-123) from the current branch name and injects it into the commit message on the fly.

4. Guided Interactive Commit Wizard

Don’t want teammates to memorize rules? They can just run:

npx git-guardian commit

An interactive prompt asks for the type, ticket, and summary, formats the message according to your repo rules, and runs the commit cleanly.

5. Native Secret Scanning on Commit

Before any commit is recorded, staged diffs and messages are scanned for AWS keys, OpenAI tokens, private certificates, and committed .env files. If a credential is detected, the commit is blocked locally with masked diagnostics.

Why Immediate Local Feedback Matters

When a naming error is flagged in a GitHub pull request, the developer has already switched context to their next task. They have to context-switch back, rename branches, rewrite Git history, force-push, and ping reviewers again.

Local Git hooks bring that feedback to the exact second the mistake occurs. The context is fresh, the correction takes five seconds, and the PR arrives clean.

Getting Started

In any Git repository (Node, React Native, Python, Go, or Rust):

# 1. Install as a dev dependency
npm install --save-dev @agnotic/git-guardian

# 2. Interactive guided setup (creates .git-guardian.yml & sets up hooks)
npx git-guardian init

# 3. Verify health and hook integrity
npx git-guardian doctor

Commit the generated .git-guardian.yml file. When teammates pull the repo and run npm install, they simply run npx git-guardian install once to wire their local hooks.

Where It Fits Alongside Husky and commitlint

Husky and commitlint are staples of the JavaScript ecosystem. Husky is a generalized Git hook runner; commitlint is a dedicated commit message linter.

git-guardian was engineered for teams that want an all-in-one, config-driven convention guardian:

• Branch validation is built-in natively (Husky doesn’t validate branch creation out of the box).
• No regex authoring or complex JavaScript config files.
• Auto-ticket injection and secret scanning come included without chaining external plugins or lint-staged scripts.
• Zero runtime dependencies.

If your team already has a battle-tested Husky + commitlint pipeline that everyone loves, keep it! But if you find yourself repeatedly copying 50 lines of bash scripts and regexes between projects, Git Guardian offers a streamlined alternative.

What I Want This Project to Achieve

My goal is simple: zero PR comments spent on housekeeping.

Every minute spent reminding an engineer about branch syntax or commit style is a minute diverted from discussing code quality, architecture, and user experience.

@agnotic/git-guardian is the first package in the Guardian Engineering Toolkit, an initiative aimed at standardizing developer guardrails across Git workflows, CI quality pipelines, and release engineering.

Try it out on your next project, and let me know: What conventions does your team enforce, and where does your Git workflow still cause friction?

Explore git-guardian

I’ve been building SwiftUI apps long enough to accept one truth:
SwiftUI navigation works beautifully… until it doesn’t.

When your app is small, NavigationStack feels magical.
Once you start adding deep linking, authentication flows, modals, tabs, and modular features… well, the magic doesn’t last long.

If you’ve read my previous article — 
👉 I Was Tired of Fighting SwiftUI Navigation, So I Built My Own Router
https://medium.com/@vedantshirke/i-was-tired-of-fighting-swiftui-navigation-so-i-built-my-own-router-199a5fecf81c
 — you already know exactly why I felt the need to rethink SwiftUI navigation entirely.

This article takes that discussion further.
Let’s break down the actual truth:

Which navigation approach truly scales in a real production SwiftUI app?

Why NavigationStack Feels Perfect at First

SwiftUI’s NavigationStack gives you a clean and declarative way to manage navigation:

NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            Text(item.name)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
}

This is ideal for:

• simple list → detail flows
• small apps
• prototypes
• demos
• non-nested navigation scenarios

In the beginning, everything feels great.
Then your app grows.

Where NavigationStack Starts Cracking (Real Production Issues)

SwiftUI demos rarely show what happens once your app crosses 10+ screens.
But that’s exactly when NavigationStack begins to show its limitations.

1. No Central Control

You can’t easily:

• reset navigation
• clear a flow
• trigger navigation from a ViewModel
• coordinate multiple screens cleanly

Everything is tied to the UI layer.

2. Deep Linking Gets Messy Fast

When handling:

• universal links,
• notifications,
• dynamic routing,
• and fallback flows,

navigation becomes a scattered web of conditions.

3. Feature Modules Cannot Own Their Navigation

If you’re working with modular architecture, navigation becomes tightly coupled with parent views.
Clean architecture? Hard to maintain.

4. Hard to Test and Reason About

Navigation logic spreads across views.
ViewModels start leaking UI concerns.
Testing becomes painful.

This is exactly why many teams end up creating their own solution.

Enter Custom Routers (The Practical, Scalable Approach)

A Custom Router gives you:

• a single navigation source of truth
• testable and predictable routes
• full programmatic control
• clean flow resets
• modular independence
• a consistent API for navigation

Instead of the UI owning navigation state, the router owns it.

Example:

class AppRouter: ObservableObject {
    @Published var path = NavigationPath()
     
    func push(_ route: Route) { 
        path.append(route) 
    }
    
    func pop() {
        path.removeLast()
    }

    func popToRoot() {
        path.removeLast(path.count)
    }
}

Views simply observe navigation.
Your architecture remains stable as the app grows.

Where SwiftUIRouter (SwiftUIRouterKit) Fits In

After repeatedly hitting SwiftUI’s navigation limitations across different projects, I finally built SwiftUIRouter — a lightweight router package for SwiftUI apps that need predictable, scalable navigation.

What SwiftUIRouter solves:

• Navigation logic becomes centralized
• ViewModels can navigate cleanly
• No navigation leaks into UI
• Flows become modular & testable
• You don’t need to reinvent routing from scratch

In short:

SwiftUIRouter gives you all the benefits of a custom router without the overhead of building one manually.

It’s intentionally small, production-focused, and easy to integrate.

When Should You Use What?

Use NavigationStack if:

• You’re building a very small app
• Flows are simple
• No deep linking is needed
• It’s a prototype or MVP

Use a Custom Router if:

• Your app has more than one flow
• You need clean architecture
• You want to support deep links
• You want centralized navigation

Use SwiftUIRouter if:

• You want the power of a router
• Without maintaining routing infrastructure
• While keeping SwiftUI code clean and modular
• And ensuring production scalability

A Real-World Architecture That Scales

App
 ├── AppRouter (from SwiftUIRouter)
 ├── AuthFlow
 ├── DashboardFlow
 ├── ProfileFlow
 ├── SettingsFlow
 └── Shared Components

Each flow manages its own routes.
Navigation logic stays simple and predictable.
The app stays maintainable even after months of growth and feature additions.

Final Verdict

NavigationStack is amazing for small apps.
Custom routers are amazing for real-world apps.
SwiftUIRouter gives you both power and simplicity.

SwiftUI’s default navigation works great until you start shipping real, non-trivial apps.
Once you’re dealing with deep linking, multiple flows, modular architecture, and state-driven navigation, you quickly realize how much easier life is with a proper router.

And if you want to understand why I built SwiftUIRouter in the first place, here’s the original story:

👉 https://medium.com/@vedantshirke/i-was-tired-of-fighting-swiftui-navigation-so-i-built-my-own-router-199a5fecf81c

NavigationStack vs Custom Router: What Actually Scales in Real iOS Apps? was originally published in Dev Beyond on Medium, where people are continuing the conversation by highlighting and responding to this story.

Run tests on Simulator, generate JUnit/HTML reports, and streamline your iOS testing process with one CLI tool.

📦 Introduction

Automated testing is the backbone of scalable iOS development. But running tests manually via Xcode, resetting simulators, and collecting result reports can become tedious — especially in CI environments.

That’s why I built ios-test-runner, a lightweight command-line tool that lets you:

• ✅ Run iOS tests via xcodebuild
• ✅ Automatically boot/reset simulators
• ✅ Generate HTML, JUnit XML, and text reports from .xcresult
• ✅ Use it both locally and in CI/CD pipelines
• ✅ Install easily via Homebrew

🍺 Install via Homebrew

You can now install ios-test-runner as a Homebrew package in just two steps:

brew tap ENVY-Packages/homebrew-envy-ios-test-runner
brew install ios-test-runner

And that’s it — you’re ready to go.

🚀 Quick Usage

Run the tool like this:

ios-test-runner -s MyAppScheme -d "iPhone 15" -o test-output

⚙️ What Does It Do?

Here’s a breakdown of what ios-test-runner automates:

✅ 1. Dependency Check

Before running, it ensures essential tools are available:

xcodebuild
xcrun
xcresultparser

Don’t have xcresultparser? Install it via: brew install xcresultparser

🌀 2. Resets & Boots Simulator

No more simulator clutter or stale states. The tool:

• Kills running simulators
• Resets them cleanly
• Boots the selected one automatically

🧪 3. Executes Tests via xcodebuild

It runs your test suite using:

xcodebuild test \
  -scheme "$SCHEME" \
  -destination "platform=iOS Simulator,name=$DEVICE,OS=latest" \
  -enableCodeCoverage YES \
  -resultBundlePath TestResults.xcresult

📄 4. Generates Rich Reports

After tests run, it uses xcresultparser to convert .xcresult into:

• 📄 report.html – clean test summary in browser
• 📄 junit.xml – for CI/CD integrations
• 📄 output.txt – plain-text summary

These are saved in the directory you provide via -o.

📁 Example Output

After execution, you’ll have a structured output like:

reporter/reports/
├── report.html
├── junit.xml
└── output.txt

You can open the HTML file in your browser or use junit.xml with Jenkins, GitHub Actions, or GitLab.

🧰 Perfect for CI Pipelines

Add it to your CI pipeline like this:

- name: Install Test Runner
  run: |
    brew tap ENVY-Packages/homebrew-envy-ios-test-runner
    brew install ios-test-runner

- name: Run iOS Tests
  run: ios-test-runner -s MyAppScheme

This makes your tests more reproducible, report-friendly, and CI-ready.

🔄 Update Instructions

You can always update the tool with:

brew update
brew upgrade ios-test-runner

💬 Final Thoughts

Whether you’re a solo iOS dev or working with a larger team, ios-test-runner simplifies repetitive test workflows and ensures consistent reporting.

Install it once via Homebrew, and you’ll never go back to running raw xcodebuild commands again.

Happy testing! 🚀

https://img.shields.io/badge/brew%20install-ios--test--runner-brightgreen?style=for-the-badge&logo=homebrew

In Part 1, we automated iOS builds and distributed them to Firebase App Distribution on every push to main, develop, or release/*. It was all about continuous delivery for testers.

In Part 2, we’re moving into production territory — we’ll level up by automating deployments to TestFlight using GitHub Actions triggered by a GitHub Release event.

This workflow adds several enhancements:
1. Automatically generates a unique build number
2. Commits the updated build number and Info.plist to the correct branch
3. Force pushes the tag associated with the GitHub Release
4. Uploads the build to TestFlight and Firebase

Since this is a continuation of Part 1, we’ll keep common steps like CocoaPods installation, Fastlane setup, and Firebase CLI brief — and focus on what’s new and more advanced in this part.

🧱 Pipeline Overview (Part 2)

Trigger: GitHub Release (release.published)

Steps:
1. Automatically generate a unique build number
2. Commit updated build number back to the repo
3. Force push a tag corresponding to the release
4. Upload to TestFlight with retry logic

⚙️ Job 1: Set Up Environment and Build Number

Trigger

on:
  release:
    types: [published]

🔢 Key Addition: Generate Build Number (Unique Per Day)

This step is new in Part 2. We generate a unique build number based on the current date (YYYYMMDD) followed by a counter (01 to 99) to avoid duplicates on the same day:

DATE=$(date '+%Y%m%d')
BUILD_FILE="build_number.txt"
if [ -f "$BUILD_FILE" ]; then
  LAST_BUILD=$(cat "$BUILD_FILE")
  LAST_DATE=${LAST_BUILD:0:8}
  LAST_COUNTER=${LAST_BUILD:8:2}
else
  LAST_DATE=""
  LAST_COUNTER=0
fi

if [ "$LAST_DATE" = "$DATE" ]; then
  COUNTER=$(printf "%02d" $((10#$LAST_COUNTER + 1)))
else
  COUNTER="01"
fi

if [ "$COUNTER" -gt 99 ]; then
  echo "Build number counter exceeded 99 for today ($DATE)"
  exit 1
fi
NEW_BUILD_NUMBER="${DATE}${COUNTER}"
echo "$NEW_BUILD_NUMBER" > build_number.txt

Why?
1. Ensures every build in a day has a unique, ascending number
2. Avoids manual version bumping

This build number is passed as an output to downstream jobs and injected into the app’s Info.plist.

🧱 Job 2: Build the iOS App

⚠️ This section shares many steps with Part 1. Refer back if you want details on CocoaPods installation, code signing, or Fastlane setup.

✅ Key Difference: Updating Build Number and Tag

1. Update Build Number in Info.plist

/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $BUILD_NUMBER" Info.plist
echo "$BUILD_NUMBER" > build_number.txt

2. Extract Target Branch from Release

- name: Extract Target Branch
  id: extract_branch
  run: echo "branch=${{ github.event.release.target_commitish }}" >> $GITHUB_OUTPUT

3. Commit Build Number and Push Updated Tag This is one of the most critical parts of this workflow.

git checkout $TARGET_BRANCH
git pull origin $TARGET_BRANCH

git add build_number.txt Info.plist
git commit -m "🔢 Update build number to $BUILD_NUMBER" || echo "No changes"
git push origin $TARGET_BRANCH

# Re-tag the release to include updated build
git tag -f $RELEASE_TAG
git push origin $RELEASE_TAG --force

This ensures that the tag pointing to the release always references the correct commit with the proper build number and versioning.

📦 Archive and Export IPA

Refer to Part 1 for the full clean + archive + export steps. Nothing changes here.

🧠 Upload Symbols to Crashlytics

- name: Upload dSYM to Firebase Crashlytics
 run: |
 Pods/FirebaseCrashlytics/upload-symbols -gsp <APP_NAME>/Firebase/${{ env.PLIST_FILE_NAME }} -p ios <APP_NAME>.xcarchive/dSYMs/${{ env.PRODUCT_NAME }}.app.dSYM

🚀 Job 3: Deploy to TestFlight and Firebase

The upload logic here is nearly identical to Part 1, but with some improvements:

1. Install Fastlane and Firebase CLI

sudo gem install fastlane -NV
curl -sL https://firebase.tools | bash

2. Download IPA Artifact

- uses: actions/download-artifact@v4
  with:
    name: <APP_NAME>
    path: .

3. Create App Store Connect API Key JSON: Before uploading to TestFlight, Fastlane requires authentication using an App Store Connect API key. We dynamically create the required AuthKey.json file:

cat <<EOF > fastlane/AuthKey.json
{
  "key_id": "${{ secrets.PROD_KEY_ID }}",
  "issuer_id": "${{ secrets.PROD_ISSUER_ID }}",
  "key": "${{ secrets.PROD_KEY }}"
}
EOF

4. Upload to TestFlight with Retry Logic: This step uploads the .ipa file to TestFlight using Fastlane. Since network issues or App Store Connect hiccups are not uncommon, a retry mechanism is used to improve reliability.

for i in {1..3}; do
  echo "🔁 Attempt $i to upload to TestFlight"
  if bundle exec fastlane ios upload_only; then
    echo "✅ Upload succeeded"
    break
  elif [ "$i" -eq 3 ]; then
    echo "❌ Upload failed after 3 attempts"
    exit 1
  else
    echo "⏳ Waiting before retry..."
    sleep 30
  fi
done

1. It tries uploading up to 3 times.
2. If the upload fails, it waits 30 seconds before retrying.
3. If it still fails after 3 attempts, the workflow fails gracefully.

This logic improves deployment reliability by avoiding transient failures.

5. Fastfile: upload_only Lane

Here’s the Fastlane lane used in the upload job:

platform :ios do
  lane :upload_only do
    upload_to_testflight(
      ipa: "<APP_NAME>.ipa",
      api_key_path: "fastlane/AuthKey.json"
    )
  end
end

This lane does the following:

1. Uploads the exported IPA (<APP_NAME>.ipa) to TestFlight
2. Authenticates with App Store Connect using the API key JSON file
3. Keeps the lane minimal — ideal for CI/CD workflows

6. Publish to Firebase App Distribution

firebase appdistribution:distribute <APP_NAME>.ipa \
  --app $FIREBASE_APP_ID \
  --groups "PROD" \
  --release-notes "$RELEASE_BODY" \
  --token $FIREBASE_TOKEN

✅ What You Achieve

On every published GitHub Release:

1. 🔢 Build number is auto-generated and committed
2. 🏷️ Git tag is force-updated to latest commit
3. 📦 App is signed, archived & uploaded
4. 🚀 Delivered to TestFlight and Firebase
5. 🧠 dSYMs uploaded for Crashlytics

Fully automated. Fully controlled.

📚 Summary

This workflow helps eliminate all manual steps after tagging a release. You can now:

1. Trigger builds via GitHub UI by creating a release
2. Keep version control accurate and reproducible
3. Simplify QA workflows with both Firebase and TestFlight deploys

With this, you’ve built a robust, end-to-end iOS CI/CD pipeline — and while this might be the last part for now, it’s just the beginning of what you can automate.

🔗 Missed Part 1? Read it here

name: Build And Upload To Testflight

on:
  release:
    types: [published]

jobs:

  # ──────────────────────────────
  # Job 1: Environment Setup
  # ──────────────────────────────
  setup:
    name: Set Up Environment
    runs-on: macos-latest
    outputs:
      build_number: ${{ steps.generate_build.outputs.BUILD_NUMBER }}
      build_env: PROD
      firebase_app_id_secret_name: FIREBASE_APP_ID
      firebase_token: FIREBASE_TOKEN
      provisioning_profile_name: DIST_PROVISIONING_PROFILE
      provisioning_profile_specifier_name: <PROFILE_NAME>
      scheme_name: <SCHEME_NAME>
      product_name: <APP_NAME>
      plist_file_name: GoogleService-Info.plist

    steps:
      # Checkout the repo
      - name: Checkout Source Code
        uses: actions/checkout@v4

      # Set up Ruby environment for CocoaPods
      - name: Setup Ruby Environment
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1.0'

      # Install CocoaPods dependencies
      - name: Install CocoaPods
        run: |
          gem install cocoapods
          pod install

      # Generate unique build number: YYYYMMDD + counter (01-99)
      - name: Generate Build Number
        id: generate_build
        run: |
          DATE=$(date '+%Y%m%d')
          BUILD_FILE="build_number.txt"
          if [ -f "$BUILD_FILE" ]; then
            LAST_BUILD=$(cat "$BUILD_FILE")
            LAST_DATE=${LAST_BUILD:0:8}
            LAST_COUNTER=${LAST_BUILD:8:2}
          else
            LAST_DATE=""
            LAST_COUNTER=0
          fi

          if [ "$LAST_DATE" = "$DATE" ]; then
            COUNTER=$(printf "%02d" $((10#$LAST_COUNTER + 1)))
          else
            COUNTER="01"
          fi

          if [ "$COUNTER" -gt 99 ]; then
            echo "Build number counter exceeded 99 for today ($DATE)"
            exit 1
          fi

          NEW_BUILD_NUMBER="${DATE}${COUNTER}"
          echo "$NEW_BUILD_NUMBER" > "$BUILD_FILE"
          echo "BUILD_NUMBER=$NEW_BUILD_NUMBER" >> $GITHUB_ENV
          echo "BUILD_NUMBER=$NEW_BUILD_NUMBER" >> "$GITHUB_OUTPUT"
          echo "✅ Build Number: $NEW_BUILD_NUMBER"

  # ──────────────────────────────
  # Job 2: Build the iOS App
  # ──────────────────────────────
  build:
    name: Build App
    runs-on: macos-latest
    needs: setup
    env:
      BUILD_ENV: ${{ needs.setup.outputs.build_env }}
      FIREBASE_APP_ID_SECRET_NAME: ${{ needs.setup.outputs.firebase_app_id_secret_name }}
      FIREBASE_TOKEN: ${{ needs.setup.outputs.firebase_token }}
      PROVISIONING_PROFILE_NAME: ${{ needs.setup.outputs.provisioning_profile_name }}
      PROVISIONING_PROFILE_SPECIFIER_NAME: ${{ needs.setup.outputs.provisioning_profile_specifier_name }}
      SCHEME_NAME: ${{ needs.setup.outputs.scheme_name }}
      PRODUCT_NAME: ${{ needs.setup.outputs.product_name }}
      PLIST_FILE_NAME: ${{ needs.setup.outputs.plist_file_name }}
      BUILD_NUMBER: ${{ needs.setup.outputs.build_number }}

    steps:
      # Checkout the code
      - name: Checkout Source Code
        uses: actions/checkout@v4

      # Select Xcode version 16.1
      - name: Select Xcode Version
        run: |
          sudo xcode-select -s "/Applications/Xcode_16.1.app"
          xcodebuild -version

      # Setup provisioning profile and certificates for code signing
      - name: Configure Code Signing
        env:
          CERT_DATA: ${{ secrets.P12_CERTIFICATE }}
          CERT_PW: ${{ secrets.P12_PASSWORD }}
        run: |
          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
          echo "${{ secrets.PROVISIONING_PROFILE }}" | base64 --decode > ~/Library/MobileDevice/Provisioning\ Profiles/profile.mobileprovision

          # Create and unlock a temporary keychain
          security create-keychain -p "" build.keychain
          security list-keychains -s build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "" build.keychain
          security set-keychain-settings

          # Decode and import the certificate
          echo $CERT_DATA | base64 --decode > signingCertificate.p12
          security import signingCertificate.p12 -f pkcs12 -k build.keychain -P $CERT_PW -T /usr/bin/codesign
          security set-key-partition-list -S apple-tool:,apple: -s -k "" build.keychain

          rm signingCertificate.p12

      # Update Info.plist with the new build number
      - name: Update Build Number in Info.plist
        run: |
          /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $BUILD_NUMBER" "<APP_NAME>/Info.plist"
          echo "$BUILD_NUMBER" > "build_number.txt"

      # Extract target branch name from release event
      - name: Extract Target Branch
        id: extract_branch
        run: echo "branch=${{ github.event.release.target_commitish }}" >> $GITHUB_OUTPUT

      # Fetch all branches to ensure git operations succeed
      - name: Fetch All Branches
        run: git fetch --all

      # Commit updated build number and tag the release
      - name: Commit Build Number and Tag Release
        run: |
          BRANCH_NAME="${{ steps.extract_branch.outputs.branch }}"
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git checkout "$BRANCH_NAME"
          git pull origin "$BRANCH_NAME"
          git pull origin "$GITHUB_REF_NAME"

          git add build_number.txt <APP_NAME>/Info.plist
          git commit -m "🔢 Update build number to $BUILD_NUMBER" || echo "No changes to commit"
          git push origin "$BRANCH_NAME"

          VERSION_NUMBER=$(/usr/libexec/PlistBuddy -c "Print CFBundleShortVersionString" "<APP_NAME>/Info.plist")
          TAG_NAME="${{ github.event.release.tag_name }}"
          git tag -f "$TAG_NAME"
          git push origin "$TAG_NAME" --force
          echo "✅ Committed build number and tagged release v$VERSION_NUMBER.$BUILD_NUMBER"

      # Clean and archive the app using xcodebuild
       name: Clean and Build the iOS App
        run: |
          xcodebuild clean \
            -workspace <WORKSPACE_NAME>.xcworkspace \
            -scheme "${{ env.SCHEME_NAME }}" \
            -configuration "AdHoc" \
            -sdk iphoneos \
            -quiet
            
          echo "Clean success"

          # Archive the app
          xcodebuild -scheme "${{ env.SCHEME_NAME }}" -workspace <WORKSPACE_NAME>.xcworkspace -sdk iphoneos -archivePath <WORKSPACE_NAME>.xcarchive clean archive PROVISIONING_PROFILE_SPECIFIER="${{ env.PROVISIONING_PROFILE_SPECIFIER_NAME}}" CODE_SIGN_STYLE="Manual"

          echo "Archive success"

      # Upload the IPA as an artifact for the deploy job
      - name: Upload IPA Artifact
        uses: actions/upload-artifact@v4
        with:
          name: PETRO-PASS
          path: build/${{ env.PRODUCT_NAME }}.ipa

      # Upload dSYM symbols for Crashlytics
      - name: Upload dSYM to Firebase Crashlytics
        run: |
          Pods/FirebaseCrashlytics/upload-symbols -gsp <WORKSPACE_NAME>/Firebase/${{ env.PLIST_FILE_NAME }} -p ios <WORKSPACE_NAME>.xcarchive/dSYMs/${{ env.PRODUCT_NAME }}.app.dSYM

  # ──────────────────────────────
  # Job 3: Deploy to TestFlight and Firebase
  # ──────────────────────────────
  deploy:
    name: Deploy to TestFlight and Firebase
    runs-on: macos-latest
    needs: build

    steps:
      # Checkout code
      - name: Checkout Source Code
        uses: actions/checkout@v4

      # Install Fastlane for iOS deployment
      - name: Install Fastlane
        run: sudo gem install fastlane -NV

      # Install Firebase CLI tools
      - name: Install Firebase CLI
        run: curl -sL https://firebase.tools | bash

      # Download IPA artifact from build job
      - name: Download IPA Artifact
        uses: actions/download-artifact@v4
        with:
          name: <APP_NAME>
          path: .

      # Setup Ruby Bundler and install dependencies (if any)
      - name: Setup Bundler and Install Dependencies
        run: |
          gem install bundler
          bundle install

      # Create App Store Connect API Key JSON file
      - name: Create App Store Connect API Key JSON
        run: |
          cat <<EOF > fastlane/AuthKey.json
          {
            "key_id": "${{ secrets.PROD_KEY_ID }}",
            "issuer_id": "${{ secrets.PROD_ISSUER_ID }}",
            "key": "${{ secrets.PROD_KEY }}"
          }
          EOF
          
      # Upload IPA to TestFlight with retry logic
      - name: Upload IPA to TestFlight
        env:
          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.PROD_KEY_ID }}
          APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.PROD_ISSUER_ID }}
          APP_STORE_CONNECT_API_KEY_PATH: fastlane/AuthKey.p8
        run: |
          for i in {1..3}; do
            echo "🔁 Attempt $i to upload to TestFlight"
            if bundle exec fastlane ios upload_only; then
              echo "✅ Upload succeeded"
              break
            elif [ "$i" -eq 3 ]; then
              echo "❌ Upload failed after 3 attempts"
              exit 1
            else
              echo "⏳ Waiting before retry..."
              sleep 30
            fi
          done

      # Publish app to Firebase App Distribution
      - name: Publish to Firebase App Distribution
        run: |
          firebase appdistribution:distribute <APP_NAME>.ipa \
            --app ${{ secrets.FIREBASE_APP_ID }} \
            --groups "PROD" \
            --release-notes "${{ github.event.release.body }}" \
            --token ${{ secrets.FIREBASE_TOKEN }}

As an iOS developer, automating the build and distribution process saves time and reduces manual errors. In this blog series, I’ll walk you through a CI/CD pipeline using GitHub Actions for iOS apps.

In Part 1, we’ll focus on automatically building your app and distributing it to Firebase App Distribution when you push to a specific branch (like main, develop, or release/*).

In Part 2, we’ll expand this pipeline to trigger on GitHub Release publish events, dynamically generate build numbers, tag versions, and deploy to TestFlight.

🧱 Pipeline Overview

Trigger: Push to branch (e.g., main)

Steps:
1. Checkout source code
2. Install dependencies
3. Configure code signing
4. Build and archive the iOS app
5. Upload to Firebase App Distribution

⚙️ Job 1: Setup and Build on Push

Trigger

on:
  push:
    branches:
      - main

Steps

1. Checkout the code

- uses: actions/checkout@v4

2. Set up Ruby & CocoaPods

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.1.0'
- run: |
    gem install cocoapods
    pod install

3. Configure Code Signing

mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles

# Decode and import provisioning profile
echo "${{ secrets.PROVISIONING_PROFILE }}" | base64 --decode > ~/Library/MobileDevice/Provisioning\ Profiles/profile.mobileprovision

# Set up keychain and import .p12
security create-keychain -p "" build.keychain
security list-keychains -s build.keychain
security default-keychain -s build.keychain
security unlock-keychain -p "" build.keychain

# Decode and import certificate
echo $CERT_DATA | base64 --decode > signingCertificate.p12
security import signingCertificate.p12 -f pkcs12 -k build.keychain -P $CERT_PW -T /usr/bin/codesign

4. Build and Archive the App

xcodebuild clean -workspace <WORKSPACE_NAME>.xcworkspace 
  -scheme "<SCHEME_NAME>" 
  -configuration "Dist" 
  -sdk iphoneos 
  -quiet

xcodebuild -scheme "<SCHEME_NAME>" \
  -workspace <WORKSPACE_NAME>.xcworkspace \
  -sdk iphoneos \
  -archivePath <SCHEME_NAME>.xcarchive \
  clean archive \
  PROVISIONING_PROFILE_SPECIFIER="<PROFILE_NAME>" \
  CODE_SIGN_STYLE="Manual" \
  CODE_SIGN_IDENTITY="Apple Distribution"

Replace <WORKSPACE_NAME> and <SCHEME_NAME> with your app’s actual values.

5. Export IPA

xcodebuild -exportArchive \
  -archivePath <SCHEME_NAME>.xcarchive \
  -exportOptionsPlist plist/ExportOptions.plist \
  -exportPath build

☁️ Job 2: Upload to Firebase App Distribution

1. Install Firebase CLI

curl -sL https://firebase.tools | bash

2. Distribute the IPA

firebase appdistribution:distribute build/<APP_NAME>.ipa \
  --app ${{ secrets.FIREBASE_APP_ID }} \
  --groups "<GROUP_NAME>" \
  --release-notes "${{ github.event.head_commit.message }} " \
  --token ${{ secrets.FIREBASE_TOKEN }}

⚠️ Rename the generated .ipa to match your app name or update the path accordingly.

This makes the latest .ipa available to your internal testers automatically after each push.

🔐 Secrets Used

P12_CERTIFICATE — Base64 of the signing certificate (.p12)
P12_PASSWORD — Password for .p12
PROVISIONING_PROFILE— Base64 of provisioning profile
FIREBASE_APP_ID— Firebase App ID
FIREBASE_TOKEN— Firebase CLI token

These are decoded and imported during the workflow.

✅ What You Achieve

1. 🔄 Automatic iOS app build on push
2. ✅ Code signing handled securely
3. ☁️ IPA uploaded to Firebase App Distribution
4. 🚫 No more manual builds and uploads!

▶️ Coming Up in Part 2

In the next post, we’ll cover:
1. Triggering builds on GitHub Release publish
2. Automatically generating unique build numbers
3. Tagging releases and committing back to the repo
4. Uploading to TestFlight with retries
5. Uploading dSYM to Crashlytics

Stay tuned — we’re just getting started with smarter iOS CI/CD.

By Vedant Shirke

name: Build with Firebase CLI
on:
  push:
    branches:
      - 'develop'
      - 'main'
      - 'release/*'

jobs:
  build:
    name: Build iOS app IPA
    runs-on: macos-latest
    steps:
      # Step 1: Checkout the code
      - name: Checkout
        uses: actions/checkout@v4
      
      # Step 2: Set up the Build environment
      - name: Setup Build Environment
        run: |
          # Set BUILD_ENV based on branch name
          echo "BUILD_ENV=DEV" >> $GITHUB_ENV
          echo "FIREBASE_APP_ID_SECRET_NAME=FIREBASE_APP_ID_DEV" >> $GITHUB_ENV
          echo "PROVISIONING_PROFILE_NAME=PROVISIONING_PROFILE" >> $GITHUB_ENV
          echo "PROVISIONING_PROFILE_SPECIFIER_NAME=<PROFILE_NAME>" >> $GITHUB_ENV
          echo "SCHEME_NAME=<SCHEME_NAME>" >> $GITHUB_ENV
          echo "PRODUCT_NAME=PETRO-PASS\ DEV" >> $GITHUB_ENV
          echo "PLIST_FILE_NAME=GoogleService-Info-dev.plist" >> $GITHUB_ENV
          
      - name: Verify BUILD_ENV
        run: |
          echo "Current BUILD_ENV: ${{ env.BUILD_ENV }}"
          echo "Firebase App Id: ${{ secrets[env.FIREBASE_APP_ID_SECRET_NAME] }}"
          echo "Provisioning Profile: ${{ secrets[env.PROVISIONING_PROFILE_NAME] }}"
          echo "Provisioning Profile Specifier: ${{ env.PROVISIONING_PROFILE_SPECIFIER_NAME}}"
          echo "Scheme Name: ${{ env.SCHEME_NAME }}"
          echo "Product Name: ${{ env.PRODUCT_NAME }}"
          echo "Plist File Name: ${{ env.PLIST_FILE_NAME }}"
          
      #Step 3: Set up the environment (CocoaPods, etc)
      - name: Set up Ruby for CocoaPods
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1.0'
          
      - name: Get xcodebuild version
        run: |
          sudo xcode-select -s "/Applications/Xcode_16.1.app"
          xcodebuild -version
          
      - name: Install CocoaPods Dependencies
        run: |
          gem install cocoapods
          pod install
          
      #Step 4: Set up Provisioning Profile and Certificates
      - name: Set up Provisioning Profile and Certificates
        env:
          CERT_DATA: ${{ secrets.P12_CERTIFICATE }}
          CERT_PW: ${{ secrets.P12_PASSWORD }}
        run: |

          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
          echo "${{ secrets[env.PROVISIONING_PROFILE_NAME] }}" | base64 --decode > ~/Library/MobileDevice/Provisioning\ Profiles/profile.mobileprovision
          
          # Create and unlock keychain
          security create-keychain -p "" build.keychain
          security list-keychains -s build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "" build.keychain
          security set-keychain-settings
          
          echo $CERT_DATA | base64 --decode > signingCertificate.p12
          echo "certificate decoded"
          security import signingCertificate.p12 -f pkcs12 -k build.keychain -P $CERT_PW -T /usr/bin/codesign
          security set-key-partition-list -S apple-tool:,apple: -s -k "" build.keychain
          
          file signingCertificate.p12
          
          rm signingCertificate.p12
          
      #Step 5: Clean and Build the iOS App
      - name: Clean and Build the iOS App
        run: |
          xcodebuild clean \
            -workspace <WORKSPACE_NAME>.xcworkspace \
            -scheme "${{ env.SCHEME_NAME }}" \
            -configuration "AdHoc" \
            -sdk iphoneos \
            -quiet
            
          echo "Clean success"

          # Archive the app
          xcodebuild -scheme "${{ env.SCHEME_NAME }}" -workspace <WORKSPACE_NAME>.xcworkspace -sdk iphoneos -archivePath <WORKSPACE_NAME>.xcarchive clean archive PROVISIONING_PROFILE_SPECIFIER="${{ env.PROVISIONING_PROFILE_SPECIFIER_NAME}}" CODE_SIGN_STYLE="Manual"

          echo "Archive success"
          
      - name: Upload dSYM
        run: |
          ls Pods/FirebaseCrashlytics/
          ls Pods/FirebaseCrashlytics 
          Pods/FirebaseCrashlytics/upload-symbols -gsp <WORKSPACE_NAME>/Firebase/${{ env.PLIST_FILE_NAME }} -p ios <WORKSPACE_NAME>.xcarchive/dSYMs/${{ env.PRODUCT_NAME }}.app.dSYM
            
      - name: Export the IPA
        run: |
          xcodebuild -exportArchive \
            -archivePath <WORKSPACE_NAME>.xcarchive \
            -exportOptionsPlist plist/ExportOptions.plist \
            -exportPath build
            
          ls build
          
      - name: Install Firebase Tools
        run: |
          curl -sL https://firebase.tools | bash

      - name: Get Firebase Tools Version
        run: |
          firebase --version

        ## For dev should be update to APK
      - name: Publish App to Firebase App Distribution
        run: |
          firebase appdistribution:distribute build/${{ env.PRODUCT_NAME }}.ipa \
            --app ${{ secrets[env.FIREBASE_APP_ID_SECRET_NAME] }} \
            --groups "${{ env.BUILD_ENV }}" \
            --release-notes "${{ github.event.head_commit.message }}" \
            --token ${{ secrets.FIREBASE_TOKEN }}