No-Wham Dev

Rules files and context - teaching the agent your codebase

NoamIfergan@gmail.com — Mon, 16 Mar 2026 00:00:00 GMT

So, you did your first agentic session. Congrats! The agent wrote code that compiles, runs, and technically does what you asked. But you looked at it and thought... "this is not how we do things here."

The architecture is wrong. The naming is off. It puts files in places that make no sense for your project. It used some library you've never heard of when you've got a perfectly good utility that does the same thing. The code works, but it looks like a stranger wrote it. Which, to be fair, it is.

This is the single most common complaint I hear from people who try agentic coding for the first time: "It writes code that works but doesn't match my project." And the fix is simpler than you think.

Rules files: your project's instruction manual

Most agent tools support some form of a "rules file" — a file that lives in your repo and tells the agent how your project works. Think of it as onboarding documentation, but for your AI pair programmer.

Different tools call them different things:

CLAUDE.md — for Claude Code and tools that use Anthropic's models
.cursorrules — for Cursor
Copilot instructions — for GitHub Copilot
.windsurfrules — for Windsurf

The name and format vary, but the concept is identical: a file in your repo that the agent reads before it starts working. It's the "hey, before you write any code, here's how we do things" brief.

And no, you don't need to pick just one. If your team uses different tools, throw a few of these in your repo. They don't conflict, and they're just text files. Low cost, high impact.

What to put in them

Here's where people either overthink or underthink this. You don't need to write a 50-page architecture document. But you also can't just write "make good code" and call it a day.

Here's what actually matters:

Architecture pattern

This is the big one. If your project uses MVVM, say so. If you're using TCA, say so. If you've got your own homebrewed architecture that you swear is better than everything else (we all have that friend), describe it.

## Architecture
We use MVVM across the app.
- Views are SwiftUI views that observe a ViewModel
- ViewModels are ObservableObject classes that handle business logic
- Models are plain structs in the Models/ folder
- Views never call services directly, always go through the ViewModel

Naming conventions

You'd be amazed how much this one matters. Agents love making up their own names, and they're rarely the ones you'd choose.

## Naming
- ViewModels: `{Feature}ViewModel` (e.g., `SettingsViewModel`)
- Views: `{Feature}Screen` for full screens, `{Feature}View` for components
- Files match their primary type name
- Use camelCase for properties, PascalCase for types

File structure

Where do things go? The agent doesn't inherently know that your ViewModels go in Sources/Features/{Feature}/ViewModels/ and not just floating around in the root.

## File structure
Each feature has its own folder under Sources/Features/:
- Sources/Features/{Feature}/Views/
- Sources/Features/{Feature}/ViewModels/
- Sources/Features/{Feature}/Models/
Tests mirror the source structure under Tests/Features/

Preferred libraries and patterns

If you've got a design system, mention it. If you use specific libraries for networking, storage, or whatever, list them. This prevents the agent from importing random third-party dependencies.

## Libraries & patterns
- Networking: Use our APIClient (Sources/Networking/APIClient.swift), NOT URLSession directly
- UI components: Use components from our DesignSystem module
- Navigation: Use the Router pattern (see Sources/Navigation/Router.swift)
- Async: Prefer async/await over Combine for new code

Beyond rules files: context in your prompts

The rules file is your baseline. It covers the general stuff that applies to every task. But for specific tasks, you'll want to give the agent more context directly in your prompt.

Here's the difference:

Rules file (general): "We use MVVM, files go in Features/ folders, use our DesignSystem module."

Prompt context (specific): "Add a settings screen. Look at how ProfileScreen is built — follow the same pattern. The toggles should use DesignSystem.Toggle, and navigation should go through the Router."

See the difference? The rules file sets the stage. The prompt points at specific examples. Together, they give the agent everything it needs to write code that actually fits your project.

Some tips for giving good context:

Reference existing files by name. "Follow the pattern in ProfileScreen" is 10x better than "follow our patterns."
Be specific about what to reuse. "Use the same cell style as in ProfileScreen's list" is better than "make it look similar."
Mention what not to do. "Don't add new dependencies" or "Don't use UIKit, stay in SwiftUI" saves you a round trip.

The payoff

Let me paint a picture.

Without rules or context: You ask the agent to add a settings screen. It creates a single massive ViewController with inline layout code, imports a random settings library from GitHub, puts everything in a folder called "Misc", and names the class "SettingsVC." It works, but you want to cry.

With rules and context: You ask the agent to add a settings screen. It creates a SettingsScreen view that observes a SettingsViewModel, uses your DesignSystem.Toggle for switches, follows your Router for navigation, puts files in Sources/Features/Settings/, and the code looks like it was written by someone who's been on your team for months.

Same agent. Same model. Same intelligence. The only difference is you told it how your project works. That's it. That's the whole trick.

A starter template

Here's a rules file you can steal, adapt, and throw in your repo today. It's opinionated — change it to match your project, not mine.

# Project Rules

## Architecture
- We use [MVVM/MVI/TCA/whatever you use]
- [Brief description of the data flow]
- [Any other architectural constraints]

## Naming Conventions
- Views: `{Feature}Screen` for full screens, `{Feature}View` for reusable components
- ViewModels: `{Feature}ViewModel`
- Models: plain descriptive name (e.g., `UserProfile`, `Settings`)
- Files match their primary type name

## File Structure
- Features live in `Sources/Features/{FeatureName}/`
- Each feature has Views/, ViewModels/, and Models/ subfolders
- Tests mirror source structure under Tests/

## Dependencies & Libraries
- Networking: [your networking setup]
- UI: [your design system or UI library]
- Navigation: [your navigation approach]
- Storage: [your persistence approach]

## Code Style
- [Async approach: async/await, Combine, RxSwift, etc.]
- [Error handling approach]
- [Any specific linting rules or formatters]

## Things to Avoid
- Don't add new third-party dependencies without asking
- Don't use [deprecated pattern/library] - use [preferred alternative] instead
- Don't put business logic in Views

Copy it, fill in the brackets, drop it in your repo root, and you're 80% of the way there. You can refine it over time as you notice patterns the agent keeps getting wrong.

Takeaways

Rules files are the single biggest quality improvement you can make to your agentic coding workflow. Low effort, massive impact.
They don't need to be long. 20-30 lines covering architecture, naming, file structure, and key libraries is enough to start.
Combine rules files with specific context in your prompts. Rules set the baseline, prompts handle the specifics.
Reference real files in your project. "Follow the pattern in ProfileScreen" beats "follow our patterns" every time.
Iterate on your rules file. When the agent gets something wrong repeatedly, add a rule for it. It's a living document.

Next time, we'll look at managing your context windows, through actual examples and usages!. Stay tuned.

Your first agentic session - let's actually do something

NoamIfergan@gmail.com — Mon, 09 Mar 2026 00:00:00 GMT

Alright, so you've read the intro post, you have a vague idea of what agentic coding is, you might have even installed a tool or two. Now what?

Now we actually do something. Open up your project, pick your weapon of choice (IDE, terminal, standalone app, whatever), and let's walk through your first real session together. No theory, no fluff, just a real task from start to finish.

What are we building?

For this walkthrough, I'm going to add a feature that pretty much every app has and every developer has built a hundred times: a settings screen. It's got a list of options, maybe some toggles, maybe some navigation to sub-screens. It's not rocket science, and that's the point.

You don't want your first agentic session to be "rewrite my entire networking layer." You want something that's:

Familiar — you know what the end result should look like
Scoped — it's not going to spiral into a week-long refactor
Verifiable — you can look at the result and immediately tell if it's right

A settings screen ticks all those boxes. Pick whatever feature makes sense for your project, but if you're following along, settings screen it is.

Setting up

Open your project in whatever tool you picked. If you haven't picked one yet, here's a quick refresher from the last post: your IDE probably already has agent support built in, there are terminal CLIs from the big providers, and there are standalone apps that wrap those CLIs.

For this walkthrough, it genuinely does not matter which one you use. The flow is the same across all of them:

Point the agent at your project
Give it a task
Watch it work
Tell it what to fix
Repeat until you're happy

That's it. That's the whole workflow. Let's do it.

The first prompt

Here's where most people overthink things. Your first prompt doesn't need to be a masterpiece. It doesn't need to be a perfectly engineered 500-word essay about exactly what you want. It's a conversation, not a contract.

Here's roughly what I'd type:

"Add a settings screen to the app. It should have a list of options including: dark mode toggle, notification preferences, account info, and an about section. Follow the existing navigation patterns in the project."

That's it. Nothing fancy. A few things to note:

I told it what to build (settings screen)
I gave it specifics (the list of options)
I told it to follow existing patterns (this is key — more on this later)

Could I have given it more detail? Sure. Could I have given it less? Also sure. The beauty of agentic coding is that it's a conversation. If the agent doesn't get it right, you tell it. You're not writing a requirements doc, you're pair programming with a very fast, very eager junior developer.

Watching the agent work

This is where it gets fun. And, if I'm being honest, a little bit unsettling the first time.

The agent is going to start reading your project. It's going to look at your file structure, your existing screens, your navigation setup, your models. It might read 10, 20, 30 files before it writes a single line of code. And you're going to sit there watching it, going "oh shit, it's reading everything."

This is normal. This is good. It's trying to understand your project before it starts making changes. You know, like what a good developer should do.

Then it's going to start writing. It'll create files, modify existing ones, maybe add new dependencies. Depending on the tool you're using, you'll see this happening in real time, or you'll get a summary at the end.

Here's the thing that trips people up: the first output is not the final output. Read that again. The agent's first attempt is a draft. It's a starting point. And this is where the actual skill of agentic coding comes in.

Reviewing and course-correcting

The agent wrote you a settings screen. Great. Now look at it.

Does it compile? Probably. Does it work? Most likely. Does it look like something you'd actually ship? Ehh. Let's see.

Here's some stuff you might notice:

It used a different architecture pattern than the rest of your app
The naming conventions are off
It added a dependency you don't want
The UI is functional but doesn't match your design system
It put files in the wrong folders

All of this is fine. This is expected. Here's what you do: you tell it.

"The settings screen looks good, but we use MVVM in this project. Can you restructure it to match the pattern used in ProfileScreen?"

"The toggles are working but they should use our custom DesignSystem.Toggle component, not the default one."

"Move the SettingsViewModel to the ViewModels folder, not the Screens folder."

See what's happening? You're not starting from scratch. You're refining. The agent did 80% of the work, and you're steering the last 20%. That back-and-forth, that conversation, that is the skill. Not the first prompt.

Some sessions, you'll go back and forth 2-3 times and you're done. Other sessions, you'll be going back and forth 10 times and want to throw your laptop out the window. Both are normal. The more you do it, the better your first prompts get, and the fewer rounds you need.

Know when to start fresh

Here's a thing that a lot of noobies trip on: conversations with agents have a shelf life. The longer a session goes on, the more back-and-forth you have, the worse the agent gets. It starts forgetting things you told it earlier, contradicting itself, or confidently making up stuff that doesn't exist in your project.

This isn't a bug, it's just how these things work. The agent has a limited memory for the conversation (they call it "context"), and when it fills up, older stuff gets compressed or dropped. Think of it like a whiteboard — eventually you run out of space and start erasing the stuff at the top.

My rule of thumb: one task, one conversation. If you asked the agent to build a settings screen and it's done (or close enough), and now you want to add a networking layer — start a new conversation. Don't keep piling tasks into the same session hoping the agent remembers everything from an hour ago. It won't.

Signs that it's time to start fresh:

The agent starts "forgetting" things you already told it (re-adding that dependency you asked it to remove, ignoring your architecture, etc.)
It confidently references files or classes that don't exist
The responses start feeling generic, like it lost track of your project
You've been going back and forth for ages and you're going in circles

When in doubt, just start a new one. It's free, it's fast, and you'll get better results than trying to salvage a session that's gone off the rails.

The result

So, what did we end up with?

A working settings screen with a list of options, some toggles, navigation to sub-screens, and it mostly follows the existing patterns in the project. I had to manually tweak a few things — some spacing was off, a couple of naming conventions were wrong, and it didn't quite nail the navigation transition I wanted.

Was it faster than writing it from scratch? Yes. Meaningfully so. The boilerplate alone — the view, the view model, the navigation registration, the list cells — that would have taken me a solid chunk of time just typing it all out. The agent did that in seconds.

Was the code good? It was... fine. It compiled, it worked, it was readable. It wasn't going to win any architecture awards, and it needed some massaging to fit the project properly. But as a starting point? Pretty damn solid.

Here's my honest assessment: the agent is really good at the boring parts. The boilerplate, the scaffolding, the repetitive setup code. It's less good at understanding the soul of your project — the little conventions, the design patterns, the "we do it this way because of that one bug in 2024" stuff. That's still your job. For now.

Takeaways

Your first prompt doesn't need to be perfect. It's a conversation. You'll refine as you go.
The agent's first output is a draft, not a final product. The skill is in the back-and-forth, not in the initial prompt.
Start with something familiar. Don't try to learn agentic coding and a new framework at the same time. Use it on something you already know how to build, so you can focus on learning the workflow.
The agent is great at boilerplate, less great at your project's conventions. You'll spend most of your time steering it toward your patterns, not fixing compilation errors.
One task, one conversation. Long sessions degrade. If the agent starts forgetting things or making stuff up, start fresh — don't try to rescue a stale session.

In the next post, we're going to tackle that last point head-on. We'll look at how to teach the agent your codebase — rules files, context, and all the tricks to make it stop writing code that works but looks nothing like the rest of your project.

Agentic coding for mobile developers simplified - you're not as far behind as you think

NoamIfergan@gmail.com — Mon, 02 Mar 2026 00:00:00 GMT

I know, I know, another blog post about AI and agentic coding to clutter your feed and swarm you with information you don't feel like you need. You've been hearing about AI, you must have, but you either tried it back when GPT-3 was a thing and it would make silly mistakes all the time, or you're constantly being bombarded with people on Twitter telling you that AI is cooking their brains, or telling you that they've created a 10k MRR SaaS B2B app and you're a sucker who doesn't use it yet.

I know, you're tired of it, but it feels inevitable. So, you want to at least get a little bit of knowledge about it, but don't know where to start. Well, that's what I'm here for. Let's take a bit of a step back from all the noise and the faff, and distill the situation with AI agentic coding to the basics, stuff that you can use right now, and what you should care about.

Disclaimer: This is a very, very fast-moving industry, with very dynamic changes. The content of this blog post is accurate at the time of writing, and I will attempt to edit it as things change, but bear that in mind.

What is agentic coding? Is it ChatGPT in my editor?

Let's cover the basics first, to make sure we're all up to speed on terminology and the general vibe (pun intended). Agentic coding is, spoiler alert, coding with an agent. The main difference between what you might be used to with just ChatGPT is that an agent can have reasoning levels, and can complete a full task end to end, prompting itself, and basically "take control" - write to multiple files, delete files, create new ones, run tests, run terminal commands, etc. It can, but it doesn't have to. You control how much power it has. There's of course more to it than that, it's an iceberg, but for our use case, this is the gist that you should care about.

Where am I using it?

This can be in a few places, but to make things simple, let's simmer it down to 3 locations:

The IDE

The current IDE you're working with has an agent mode connected to it. It's not a "probably it does", it absolutely already does. Android Studio has Junie / AI Agent / Claude integration (we'll discuss it later), and Xcode recently received the ability to have agentic coding in it as well. Hell, there are even tools like Cursor and Antigravity that are entire IDEs dedicated to AI coding. Wherever you already are, there's agentic coding involved in it.

The terminal

This is where a lot of these tools started, and where a lot of them still live. Each one of the "big players" has their own CLI too, and there are tools like OpenCode that can be a central point for all of them. However, to keep things simple, we will be talking today about the first-party CLI tools, the ones the companies created for themselves.

The standalone apps

Again, the big players here have their own standalone apps. These apps are, in reality, a wrapper around their CLIs, but they make installation a lot easier, provide a nice GUI, and make project management easier.

Who is them?

Right, yeah, time to talk about it. What actual agents are we talking about here?

Well, there are honestly a bucket load, and it's partially why this sphere is so daunting for so many people. In reality, there are only two players you should care about: OpenAI and Anthropic.

Are there other providers? Yes, there are.

Are they close in performance? Some.

Do you need to follow all of them? Absolutely not.

In reality, these two are the biggest players out there, and for good reason. Their models (Codex 5.3 for OpenAI, and Sonnet and Opus 4.6 for Anthropic) are highly optimized, really accurate, and honestly do the job. There are other good providers, like Google for example, but I'm going to focus on these two because they're the gold standard.

Where should you be using them?

It does not matter. Surprising, right?

Well, each of these platforms has its pluses and minuses, pros and cons, and you might find that you prefer to, for example, stay within your IDE for all of your development. That's fine. You might find that you like the simplicity of the terminal. That's also fine. Give them each a whirl, take a day to play around, find the flow that works for you, and that one is the best. Can you optimize things? Probably. Endlessly. You can spend all day optimizing the flow for best performance and execution and whatever. Or you can, and in my opinion should, fuck around and find out.

Which one do I choose?

Ready for this? It does not matter.

I know this might be a hot take for some, I know the die-hards for either platform are fuming right now and are writing me angry emails (or using their provider of choice to write me an email), but in reality, for your day-to-day usage, it really does boil down to which one you like more. Once more, this is a case of fucking around and finding out.

"But so-and-so on Twitter said that if I don't use Opus I'm a pleb." It doesn't matter.

"But they told me on LinkedIn (what?) that Opus is slopus!" It doesn't matter.

"But this dude said that..." IT DOES NOT MATTER.

For 99% of your time, you will not feel any difference between them. Try them both, they each come with a trial period, see which one jives with you more, and go with that one.

Takeaways

I think it's quite clear: fuck around and find out.

Install some agents, in your favorite workspace of choice, or in a new one like the terminal, and see how you go.

In the next few weeks, we're going to go down the path of agentic coding. I'm going to hold your hand and tell you that you're doing great, and by the end of it, you'll have enough knowledge to feel confident being a programmer in today's day and age. Or enough knowledge to know you prefer to move to a farm in the woods and leave this whole thing behind. That's up to you.

Delete Dead Swift Code Safely Using Periphery

NoamIfergan@gmail.com — Mon, 11 Aug 2025 00:00:00 GMT

Introduction

If you've worked on an iOS app for more than five minutes, you know how quickly codebases collect “just in case” types, old imports, and properties that no one calls anymore. I love shipping features, not dusting shelves. So I wrote a script that uses Periphery to find unused Swift code and then cleans the obvious stuff safely, with a verification scan at the end and a tidy report for you to review.

This isn’t a magic wand that deletes half your project. It’s a pragmatic helper that:

Ensures Periphery is installed and configured
Runs a scan and removes only the low‑risk things (unused imports and single‑line stored properties explicitly marked as unused)
Suggests full‑file removals conservatively
Re‑runs Periphery to verify things actually improved
Writes everything to a neat .periphery_cleanup/ folder that you can review (and it auto‑ignores it in git)

Why automate this?

Consistency: the same checks, every time, across projects
Confidence: a verification pass catches accidental regressions
Speed: Periphery + a tiny bit of scripting can handle the boring bits for you

What the script does (high level)

Detects your project root using git if available, or by walking up to find an .xcworkspace/.xcodeproj.
Installs Periphery via brew if it’s missing.
Ensures you have a .periphery.yml. It can:
- Launch Periphery’s interactive setup, or
- Generate a non‑interactive config in “auto mode” (see flags below) and pick a scheme/target for you (prefers BrewBuddy if found, otherwise the first available).
Runs a Periphery scan and saves JSON output.
Parses the JSON with a small Python helper and:
- Removes unused imports
- Removes single‑line stored properties that Periphery flags as unused
- Collects conservative candidates for whole‑file deletion (files that contain exactly one unused top‑level type)
Runs a second Periphery scan to verify improvement and summarizes before/after counts.
Stores a report and artifacts under .periphery_cleanup/ and keeps that directory out of git.

Usage

Drop the script into your repo (for example, Scripts/periphery_cleanup.sh) and make it executable:

chmod +x Scripts/periphery_cleanup.sh

Run it interactively (guided Periphery setup if you don’t have a config):

./Scripts/periphery_cleanup.sh

Or run it in auto mode (no prompts), optionally providing scheme/target/workspace/project overrides:

./Scripts/periphery_cleanup.sh --auto \
  --scheme YourScheme \
  --target YourTarget \
  --workspace YourApp.xcworkspace \
  --project YourApp.xcodeproj

Short flags are supported too: -a, -s, -t, -w, -p.

Requirements:

macOS with brew (for auto‑install) and Xcode command line tools
periphery (the script will install it via brew if missing)
python3 available on your PATH

What gets edited (and what doesn’t)

This is intentionally conservative:

Removes only:
- Unused imports
- Single‑line stored properties explicitly flagged as unused by Periphery
Suggests (does not delete):
- Whole files that contain exactly one unused top‑level type

Everything is logged to:

.periphery_cleanup/deleted_symbols.txt
.periphery_cleanup/removable_files.txt
.periphery_cleanup/scan_2.json (verification pass)

Pro tip: skim the removable_files.txt list and delete those files in Xcode first so it updates your project/workspace correctly.

How it works (under the hood)

The script locates your project root via git (if present) or by walking up the tree to find an Xcode workspace/project.
If .periphery.yml is missing:
- Interactive mode: launches periphery scan --setup and exits if a config isn’t produced
- Auto mode: resolves workspace/project, lists schemes/targets, prefers BrewBuddy if present, and writes a minimal .periphery.yml
First scan: periphery scan --format json → saves the output
Python helper:
- Parses findings by file and applies safe deletions (unused imports and single‑line stored properties)
- Detects “single unused top‑level type” files and lists them as removable candidates
- Emits a small JSON summary consumed by the shell script
Second scan (verification) confirms improvements and prevents loops
The script writes a human‑readable summary and clearly points you to the artifacts

CI? Maybe

I keep this as a local tool because it edits files. If you want CI visibility, run Periphery there and surface findings, but I recommend committing code deletions manually after reviewing diffs locally.

The script

Copy‑paste as is. No edits needed.

#!/usr/bin/env bash

# Periphery Cleanup Script
# Robust, safe, portable helper to detect and neutralize unused Swift code.
# - Installs Periphery if missing (via Homebrew if available)
# - Ensures a .periphery.yml exists (auto-generates one for Xcode projects)
# - Runs scan, annotates unused symbols (@available(*, deprecated, ...))
# - Suggests whole-file removals when safe to do so
# - Re-runs scan once to confirm improvements, avoids loops

set -euo pipefail
IFS=$'\n\t'

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

# CLI arguments
AUTO_MODE=0
OVERRIDE_SCHEME=""
OVERRIDE_TARGET=""
OVERRIDE_WORKSPACE=""
OVERRIDE_PROJECT=""

usage() {
  cat <<EOF
Usage: $(basename "$0") [options]

Options:
  -a, --auto              Generate .periphery.yml non-interactively (no prompts)
  -s, --scheme NAME       Scheme to use when generating config (auto mode)
  -t, --target NAME       Target to use when generating config (auto mode)
  -w, --workspace PATH    Use this .xcworkspace (auto mode)
  -p, --project PATH      Use this .xcodeproj (auto mode)
  -h, --help              Show this help

Defaults:
  - Without --auto, the script launches Periphery's guided setup (interactive)
  - With --auto, the script detects workspace/project & picks a scheme/target
EOF
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    -a|--auto) AUTO_MODE=1; shift ;;
    -s|--scheme) OVERRIDE_SCHEME="$2"; shift 2 ;;
    -t|--target) OVERRIDE_TARGET="$2"; shift 2 ;;
    -w|--workspace) OVERRIDE_WORKSPACE="$2"; shift 2 ;;
    -p|--project) OVERRIDE_PROJECT="$2"; shift 2 ;;
    -h|--help) usage; exit 0 ;;
    *) err "Unknown option: $1"; usage; exit 1 ;;
  esac
done

# Determine project root robustly
determine_root() {
  local dir
  # Prefer git root if available
  if command -v git >/dev/null 2>&1; then
    local git_root
    git_root=$(cd "$SCRIPT_DIR" && git rev-parse --show-toplevel 2>/dev/null || true)
    if [[ -n "$git_root" && -d "$git_root" ]]; then
      echo "$git_root"
      return
    fi
  fi
  # Walk up until we find an Xcode project/workspace
  dir="$SCRIPT_DIR"
  while [[ "$dir" != "/" && -n "$dir" ]]; do
    if compgen -G "$dir/*.xcworkspace" > /dev/null || compgen -G "$dir/*.xcodeproj" > /dev/null; then
      echo "$dir"
      return
    fi
    dir="$(dirname "$dir")"
  done
  # Fallback: parent of tools
  echo "$(cd "$SCRIPT_DIR/.." && pwd)"
}

ROOT_DIR="$(determine_root)"
cd "$ROOT_DIR"

ASCII_LOGO="
============================================================
   _____                 _                 _
  |  __ \               (_)               | |
  | |__) |___ _ __ _ __  _ _ __ _   _  ___| |_ ___ _ __
  |  _  // _ \ '__| '_ \| | '__| | | |/ __| __/ _ \ '__|
  | | \ \  __/ |  | |_) | | |  | |_| | (__| ||  __/ |
  |_|  \_\___|_|  | .__/|_|_|   \__,_|\___|\__\___|_|
                   | |
                   |_|   Cleanup • Periphery Automation
============================================================
"

info()  { printf "\033[1;34m[INFO]\033[0m %s\n"  "$*"; }
warn()  { printf "\033[1;33m[WARN]\033[0m %s\n"  "$*"; }
err()   { printf "\033[1;31m[ERR ]\033[0m %s\n"  "$*"; }
good()  { printf "\033[1;32m[DONE]\033[0m %s\n"  "$*"; }
bold()  { printf "\033[1m%s\033[0m\n" "$*"; }

echo "$ASCII_LOGO"

# 1) Ensure periphery is installed
if ! command -v periphery >/dev/null 2>&1; then
  warn "Periphery not found. Attempting install via Homebrew."
  if command -v brew >/dev/null 2>&1; then
    info "brew install periphery"
    brew install periphery || {
      err "Failed to install Periphery via Homebrew. Please install Periphery manually and re-run."
      exit 1
    }
    good "Periphery installed."
  else
    err "Homebrew not found. Please install Homebrew (https://brew.sh) or Periphery manually, then rerun."
    exit 1
  fi
else
  good "Periphery found: $(command -v periphery)"
fi

detect_targets_from_list() {
  # Reads xcodebuild -list output from stdin, prints Targets as lines
  awk '/Targets:/{flag=1;next} flag && NF {print $0} /^\s*$/{if(flag) exit}' \
    | sed 's/^ *//;s/ *$//' | sed '/^$/d'
}

append_targets_to_config() {
  local cfg="$1"; shift
  local targets=("$@")
  [[ ${#targets[@]} -eq 0 ]] && return 0
  if ! grep -q '^targets:' "$cfg" 2>/dev/null; then
    info "Adding targets to $cfg: ${targets[*]}"
    {
      echo "targets:"
      for t in "${targets[@]}"; do echo "  - $t"; done
    } >> "$cfg"
  fi
}

# 2) Ensure .periphery.yml exists
CONFIG_FILE="$ROOT_DIR/.periphery.yml"
if [[ ! -f "$CONFIG_FILE" ]]; then
  if [[ "$AUTO_MODE" -eq 1 ]]; then
    warn ".periphery.yml not found. Generating a non-interactive configuration (auto mode)..."

    # Resolve workspace/project
    if [[ -n "$OVERRIDE_WORKSPACE" ]]; then
      WORKSPACE_CANDIDATE="$OVERRIDE_WORKSPACE"
    else
      WORKSPACE_CANDIDATE=$(find "$ROOT_DIR" -maxdepth 1 -name "*.xcworkspace" -print -quit || true)
    fi
    if [[ -n "$OVERRIDE_PROJECT" ]]; then
      PROJECT_CANDIDATE="$OVERRIDE_PROJECT"
    else
      PROJECT_CANDIDATE=$(find "$ROOT_DIR" -maxdepth 1 -name "*.xcodeproj" -print -quit || true)
    fi

    if [[ -n "$WORKSPACE_CANDIDATE" ]]; then
      info "Using workspace: $(basename "$WORKSPACE_CANDIDATE")"
      LIST_OUTPUT=$(xcodebuild -list -workspace "$WORKSPACE_CANDIDATE" 2>/dev/null || true)
    elif [[ -n "$PROJECT_CANDIDATE" ]]; then
      info "Using project: $(basename "$PROJECT_CANDIDATE")"
      LIST_OUTPUT=$(xcodebuild -list -project "$PROJECT_CANDIDATE" 2>/dev/null || true)
    else
      err "No .xcworkspace or .xcodeproj found at $ROOT_DIR. Cannot configure Periphery."
      exit 1
    fi

    # Extract schemes and targets (compatible with bash 3.2 on macOS)
    SCHEMES=()
    TARGETS=()
    while IFS= read -r line; do
      [[ -n "$line" ]] && SCHEMES+=("$line")
    done <<EOF
$(printf "%s\n" "$LIST_OUTPUT" | awk '/Schemes:/{flag=1;next} flag && NF {print $0} /^\s*$/{if(flag) exit}' | sed 's/^ *//;s/ *$//')
EOF
    while IFS= read -r line; do
      [[ -n "$line" ]] && TARGETS+=("$line")
    done <<EOF
$(printf "%s\n" "$LIST_OUTPUT" | awk '/Targets:/{flag=1;next} flag && NF {print $0} /^\s*$/{if(flag) exit}' | sed 's/^ *//;s/ *$//')
EOF

    DEFAULT_SCHEME="${OVERRIDE_SCHEME:-${SCHEMES[0]:-}}"
    DEFAULT_TARGET="${OVERRIDE_TARGET:-${TARGETS[0]:-}}"

    # Prefer a scheme/target named BrewBuddy if present and not overridden
    if [[ -z "$OVERRIDE_SCHEME" ]]; then
      for s in "${SCHEMES[@]}"; do
        if [[ "$s" == "BrewBuddy" ]]; then DEFAULT_SCHEME="$s"; break; fi
      done
    fi
    if [[ -z "$OVERRIDE_TARGET" ]]; then
      for t in "${TARGETS[@]}"; do
        if [[ "$t" == "BrewBuddy" ]]; then DEFAULT_TARGET="$t"; break; fi
      done
    fi

    if [[ -z "$DEFAULT_SCHEME" || -z "$DEFAULT_TARGET" ]]; then
      err "Failed to detect a scheme/target from xcodebuild. Use --scheme/--target or ensure the project builds."
      exit 1
    fi

    {
      if [[ -n "$WORKSPACE_CANDIDATE" ]]; then
        echo "workspace: $(basename "$WORKSPACE_CANDIDATE")"
      else
        echo "project: $(basename "$PROJECT_CANDIDATE")"
      fi
      echo "schemes:"
      echo "  - $DEFAULT_SCHEME"
      echo "targets:"
      echo "  - $DEFAULT_TARGET"
      echo "retain_public: false"
      echo "retain_objc_accessible: false"
      echo "clean_build: false"
    } > "$CONFIG_FILE"

    good "Created $CONFIG_FILE (scheme=$DEFAULT_SCHEME, target=$DEFAULT_TARGET)"
  else
    warn ".periphery.yml not found. Launching interactive Periphery setup..."
    bold "(You will be prompted by Periphery. Choose workspace/project, scheme, and targets as usual.)"
    periphery scan --setup || { err "Periphery setup failed."; exit 1; }
    if [[ ! -f "$CONFIG_FILE" ]]; then
      err "Setup finished but .periphery.yml was not created. Aborting."
      exit 1
    fi
    good "Created $CONFIG_FILE via interactive setup"
  fi
else
  good "Found existing .periphery.yml"
fi

WORK_DIR="$ROOT_DIR/.periphery_cleanup"
mkdir -p "$WORK_DIR"
SCAN_JSON_1="$WORK_DIR/scan_1.json"
SCAN_JSON_2="$WORK_DIR/scan_2.json"
REPORT_TXT="$WORK_DIR/report.txt"
REMOVABLE_FILES_TXT="$WORK_DIR/removable_files.txt"
DELETED_SYMBOLS_TXT="$WORK_DIR/deleted_symbols.txt"
: > "$REPORT_TXT"; : > "$REMOVABLE_FILES_TXT"; : > "$DELETED_SYMBOLS_TXT"

# Keep artifacts out of source control by ensuring .gitignore contains the work directory
GITIGNORE_FILE="$ROOT_DIR/.gitignore"
if [[ -f "$GITIGNORE_FILE" ]]; then
  if ! grep -qE '^\.periphery_cleanup/?$' "$GITIGNORE_FILE" 2>/dev/null; then
    echo "# Periphery cleanup artifacts" >> "$GITIGNORE_FILE"
    echo ".periphery_cleanup/" >> "$GITIGNORE_FILE"
    good "Updated .gitignore to ignore .periphery_cleanup/"
  fi
else
  {
    echo "# Periphery cleanup artifacts"
    echo ".periphery_cleanup/"
  } > "$GITIGNORE_FILE"
  good "Created .gitignore to ignore .periphery_cleanup/"
fi

bold "\nRunning Periphery scan (pass 1)..."
periphery scan --config "$CONFIG_FILE" --format json --disable-update-check > "$SCAN_JSON_1" || {
  err "Periphery scan failed."
  exit 1
}
good "Scan completed. Output: $SCAN_JSON_1"

# 3) Parse JSON and annotate unused declarations safely with @available(*, deprecated, ...)
#    Use Python for robust JSON parsing and in-place edits.
PYTHON3_BIN="python3"
if ! command -v "$PYTHON3_BIN" >/dev/null 2>&1; then
  err "python3 not found. Please install Python 3."
  exit 1
fi

cat > "$WORK_DIR/annotate.py" <<'PY'
import json, os, sys, re

scan_path = sys.argv[1]
deleted_log_path = sys.argv[2]

with open(scan_path, 'r', encoding='utf-8') as f:
    data = json.load(f)

# Group entries by file
entries_by_file = {}
for e in data:
    loc = e.get('location', '')
    # Periphery sometimes splits lines with wrapping; normalize
    # Expect: /abs/path/File.swift:LINE:COL
    m = re.search(r"(.+\.swift):(\d+):(\d+)$", loc)
    if not m:
        continue
    path, line, col = m.group(1), int(m.group(2)), int(m.group(3))
    entries_by_file.setdefault(path, []).append({
        'line': line,
        'col': col,
        'name': e.get('name',''),
        'kind': e.get('kind',''),
        'hints': e.get('hints', []),
        'accessibility': e.get('accessibility','')
    })

deleted = []

def is_stored_property_line(line: str) -> bool:
    # Single-line stored property like: `public var foo: Type = ...` or `let name = ...`
    # Avoid computed properties `{` and protocol requirements `get set` patterns
    s = line.strip()
    if not re.search(r"\b(var|let)\b", s):
        return False
    if '{' in s:
        return False
    if re.search(r"\b(get|set)\b", s):
        return False
    return '=' in s

applied = []

for path, entries in entries_by_file.items():
    if not os.path.isfile(path):
        continue
    try:
        with open(path, 'r', encoding='utf-8') as f:
            lines = f.readlines()
    except Exception:
        continue

    # For @Observable files, we DO allow deletions of unused stored properties.

    # Sort entries descending by line to keep indices stable when inserting
    entries.sort(key=lambda x: x['line'], reverse=True)

    changed = False
    for e in entries:
        line_idx = e['line'] - 1
        if line_idx < 0 or line_idx >= len(lines):
            continue

        decl_line = lines[line_idx]
        hints = set(h.lower() for h in e.get('hints', []))

        # 1) Remove unused imports (only when explicitly marked unused)
        if decl_line.lstrip().startswith('import ') and 'unused' in hints:
            del lines[line_idx]
            changed = True
            deleted.append(f"{path}:{e['line']} import {e.get('name','')}")
            continue

        # 2) Remove single-line stored properties only if explicitly unused
        if is_stored_property_line(decl_line) and 'unused' in hints:
            del lines[line_idx]
            changed = True
            deleted.append(f"{path}:{e['line']} var/let {e.get('name','')}")
            continue

    if changed:
        with open(path, 'w', encoding='utf-8') as f:
            f.writelines(lines)

with open(deleted_log_path, 'w', encoding='utf-8') as f:
    for a in deleted:
        f.write(a + "\n")

# Compute removable file candidates conservatively:
# If a file contains exactly one top-level type declaration (struct/class/enum/protocol),
# and that same declaration appears in the unused report, suggest it.
def top_level_decl_count(path):
    try:
        with open(path, 'r', encoding='utf-8') as f:
            src = f.read()
    except Exception:
        return 0
    # Remove comments to avoid false positives
    src = re.sub(r"//.*", "", src)
    src = re.sub(r"/\*[\s\S]*?\*/", "", src)
    m = re.findall(r"^\s*(struct|class|enum|protocol)\s+\w+", src, flags=re.MULTILINE)
    return len(m)

removable_candidates = []
for path, entries in entries_by_file.items():
    # Only consider if file still exists and exactly one top-level decl
    if not os.path.isfile(path):
        continue
    if top_level_decl_count(path) != 1:
        continue
    # If every entry in this file is an unused type (struct/class/enum/protocol)
    all_types_unused = all(any(k in e['kind'] for k in ['struct', 'class', 'enum', 'protocol']) for e in entries)
    if all_types_unused:
        removable_candidates.append(path)

print("\n\n===REPORT-BEGIN===")
print(json.dumps({
    'deleted_count': sum(1 for _ in open(deleted_log_path, 'r', encoding='utf-8')) if os.path.isfile(deleted_log_path) else 0,
    'removable_candidates': removable_candidates
}, indent=2))
print("===REPORT-END===\n\n")
PY

if [[ -s "$SCAN_JSON_1" ]] && grep -q '"kind"' "$SCAN_JSON_1"; then
  python3 "$WORK_DIR/annotate.py" "$SCAN_JSON_1" "$DELETED_SYMBOLS_TXT" | tee -a "$REPORT_TXT" >/dev/null
else
  warn "No unused items found by Periphery (empty JSON). Skipping annotation."
  echo "\n===REPORT-BEGIN===" >> "$REPORT_TXT"
  echo '{"deleted_count":0,"removable_candidates":[]}' >> "$REPORT_TXT"
  echo "===REPORT-END===\n" >> "$REPORT_TXT"
fi

REMOVABLE_JSON=$(sed -n '/===REPORT-BEGIN===/,/===REPORT-END===/p' "$REPORT_TXT" | sed '1d;$d')
echo "$REMOVABLE_JSON" > "$WORK_DIR/removable.json"
"$PYTHON3_BIN" - "$WORK_DIR/removable.json" <<'PY' > "$WORK_DIR/removable_extracted.txt"
import json,sys
with open(sys.argv[1], 'r', encoding='utf-8') as f:
    d = json.load(f)
print("Deleted symbols:", d.get('deleted_count',0))
print("\nPotentially removable files (manual delete, safe heuristic):")
for p in d.get('removable_candidates',[]):
    print(p)
PY

cat "$WORK_DIR/removable_extracted.txt" | tee "$REMOVABLE_FILES_TXT"

# Remove transient helper files
rm -f "$WORK_DIR/removable_extracted.txt" "$WORK_DIR/removable.json" "$WORK_DIR/annotate.py"

bold "\nRunning Periphery scan (pass 2, verification)..."
periphery scan --config "$CONFIG_FILE" --format json --disable-update-check > "$SCAN_JSON_2" || {
  err "Periphery verification scan failed."
  exit 1
}
good "Verification scan completed. Output: $SCAN_JSON_2"

# Basic loop avoidance: only two scans are performed.
# Summarize counts before/after

COUNT1=$(grep -c '"kind"' "$SCAN_JSON_1" || true)
COUNT2=$(grep -c '"kind"' "$SCAN_JSON_2" || true)

echo "" | tee -a "$REPORT_TXT"
bold "Summary"
echo "- Unused reported (pass 1): $COUNT1" | tee -a "$REPORT_TXT"
echo "- Unused reported (pass 2): $COUNT2" | tee -a "$REPORT_TXT"
DELETED_COUNT=$(wc -l < "$DELETED_SYMBOLS_TXT" | tr -d ' ')
echo "- Deleted symbols: $DELETED_COUNT" | tee -a "$REPORT_TXT"
echo "- Removable file candidates listed in: $REMOVABLE_FILES_TXT" | tee -a "$REPORT_TXT"

cat <<'EOT'

============================================================
 Result
============================================================
  • Deleted clearly unused imports and single-line stored properties.
  • Listed conservative whole-file removals where the file contains a
    single unused top-level type (manual review recommended).
  • To review:
      - .periphery_cleanup/deleted_symbols.txt
      - .periphery_cleanup/removable_files.txt
      - .periphery_cleanup/scan_2.json

 Tips
  - Re-run this script after code changes.
  - For whole-file deletion, confirm in Xcode first, then delete.

============================================================
EOT

good "Periphery cleanup complete."

Wrap up

Dead code adds weight and confusion. This script gives you a safe, repeatable way to trim the obvious stuff, confirm improvements, and make a short list of files that are probably ready to go. Run it, read the report, commit the wins.

GitHub Actions Caching for iOS CI: Strategies That Work

NoamIfergan@gmail.com — Thu, 31 Jul 2025 00:00:00 GMT

Introduction

Alright, let's be honest here. You've set up your fancy GitHub Actions workflow from our previous posts, you're feeling like a CI/CD wizard, and then... you sit there for 15 minutes watching your build crawl along while Xcode downloads the same dependencies for the 47th time this week.

Sound familiar? Yeah, I thought so.

Well, my friend, today we're going to fix that. We're going to take your glacially slow builds and turn them into something that'll make you look like you've got superpowers. How? Caching. The magical art of not doing the same work twice.

After implementing the caching strategies in this post, your 15-minute builds will drop to 3-4 minutes, your teammates will think you've sold your soul to the DevOps gods, and you'll finally have time to grab that coffee instead of watching progress bars.

Why caching matters (and why you should care)

The cold, hard numbers

Without caching, here's what happens every single time your workflow runs:

Ruby gems: Downloaded and installed from scratch (1-2 minutes)
Swift Package Manager: Downloads and builds all dependencies (3-5 minutes)
Xcode derived data: Builds everything from zero (5-10 minutes)
CocoaPods (if you're still using them): Downloads and installs everything (2-3 minutes)

That's potentially 15+ minutes of pure waiting. For work that's been done hundreds of times before.

With proper caching:

Ruby gems: Restored in 10-15 seconds
Swift Package Manager: Restored in 30 seconds
Xcode derived data: Restored in 1-2 minutes
CocoaPods: Restored in 30 seconds

Total time saved: 10-12 minutes per build. That's enough time to contemplate life, check Twitter, or actually be productive. Your choice! 😄

GitHub Actions pricing impact

Here's the kicker - GitHub Actions charges by the minute for private repos. Those extra 10 minutes per build? That's 10x more expensive than it needs to be. Caching literally pays for itself by reducing your compute costs.

Understanding GitHub Actions cache fundamentals

Before we dive into iOS-specific strategies, let's understand how GitHub Actions caching works:

Cache keys and restore keys

- uses: actions/cache@v4
  with:
    path: path/to/cache
    key: my-cache-${{ hashFiles('**/lockfile') }}
    restore-keys: |
      my-cache-

key: The exact cache identifier. If this matches, you get a perfect cache hit
restore-keys: Fallback patterns. If the exact key doesn't match, it finds the closest match
path: What directories/files to cache

Cache invalidation strategy

The beauty is in the hashFiles() function. It creates a hash of your dependency files (like Package.resolved or Gemfile.lock). When dependencies change, the hash changes, and you automatically get a fresh cache. When they don't change, you get blazing fast restores.

The iOS caching trinity

Let's set up caching for the three main bottlenecks in iOS builds:

1. Xcode derived data caching

This is the big one. Xcode's derived data contains all the intermediate build artifacts, and it's usually the slowest part of your build.

- name: Cache Xcode derived data
  uses: actions/cache@v4
  with:
    path: ~/Library/Developer/Xcode/DerivedData
    key: ${{ runner.os }}-xcode-deriveddata-${{ hashFiles('**/*.xcodeproj/project.pbxproj', '**/*.xcworkspace/contents.xcworkspacedata') }}
    restore-keys: |
      ${{ runner.os }}-xcode-deriveddata-

What this does:

Caches the entire derived data directory
Invalidates when your project structure changes
Falls back to any previous derived data if project changes

Pro tip: The derived data cache can get huge (several GB). GitHub Actions has a 10GB limit per repository, so you might want to clean it periodically.

2. Swift Package Manager caching

SPM dependencies can take forever to download and build. Let's cache them:

- name: Cache Swift Package Manager
  uses: actions/cache@v4
  with:
    path: |
      .build
      ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex
      ~/Library/Caches/org.swift.swiftpm
      ~/Library/org.swift.swiftpm
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
    restore-keys: |
      ${{ runner.os }}-spm-

What this caches:

.build: Your local SPM build artifacts
ModuleCache.noindex: Compiled Swift modules
~/Library/Caches/org.swift.swiftpm: SPM's download cache
~/Library/org.swift.swiftpm: SPM's configuration and metadata

3. Ruby gems caching (for Fastlane)

Since you're using Fastlane (you are, right?), let's cache those Ruby gems:

- name: Set up Ruby
  uses: ruby/setup-ruby@v1
  with:
    ruby-version: 3.1
    bundler-cache: true  # This automatically handles gem caching!

Wait, that's it? Yep! The ruby/setup-ruby action has built-in caching when you set bundler-cache: true. It's so good that you don't need to do it manually.

4. CocoaPods caching (if you're still using them)

For those who haven't made the SPM transition yet:

- name: Cache CocoaPods
  uses: actions/cache@v4
  with:
    path: |
      Pods
      ~/Library/Caches/CocoaPods
    key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
    restore-keys: |
      ${{ runner.os }}-pods-

The complete caching workflow

Here's how to put it all together in a workflow that'll make your builds fly:

name: Build and Test with Caching

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: macos-latest

    steps:
    - uses: actions/checkout@v4

    # Set up Xcode (this doesn't need caching)
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: "15.4.0"

    # Cache Ruby gems (built into setup-ruby)
    - name: Set up Ruby with caching
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.1
        bundler-cache: true

    # Cache Xcode derived data
    - name: Cache Xcode derived data
      uses: actions/cache@v4
      with:
        path: ~/Library/Developer/Xcode/DerivedData
        key: ${{ runner.os }}-xcode-deriveddata-${{ hashFiles('**/*.xcodeproj/project.pbxproj', '**/*.xcworkspace/contents.xcworkspacedata') }}
        restore-keys: |
          ${{ runner.os }}-xcode-deriveddata-

    # Cache Swift Package Manager
    - name: Cache Swift Package Manager
      uses: actions/cache@v4
      with:
        path: |
          .build
          ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex
          ~/Library/Caches/org.swift.swiftpm
          ~/Library/org.swift.swiftpm
        key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
        restore-keys: |
          ${{ runner.os }}-spm-

    # Optional: Cache CocoaPods (if you're using them)
    - name: Cache CocoaPods
      if: hashFiles('**/Podfile.lock') != ''
      uses: actions/cache@v4
      with:
        path: |
          Pods
          ~/Library/Caches/CocoaPods
        key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
        restore-keys: |
          ${{ runner.os }}-pods-

    # Set up code signing (from our previous posts)
    - name: Set up SSH key for Match
      run: |
        mkdir -p ~/.ssh
        echo "${{ secrets.MATCH_GIT_PRIVATE_KEY }}" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        ssh-keyscan github.com >> ~/.ssh/known_hosts

    - name: Set up code signing
      run: bundle exec fastlane match appstore --readonly --app_identifier com.yourcompany.yourapp
      env:
        MATCH_REPOSITORY: ${{ secrets.MATCH_REPOSITORY }}
        MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}

    # Run tests (now much faster!)
    - name: Run tests
      run: bundle exec fastlane test

    # Build app (also much faster!)
    - name: Build app
      run: bundle exec fastlane build

Advanced caching strategies

Once you've got the basics down, here are some pro-level techniques:

Cache warming

Pre-populate caches in a dedicated job that runs on a schedule:

name: Cache Warming

on:
  schedule:
    - cron: '0 2 * * *'  # Run daily at 2 AM

jobs:
  warm-cache:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v4

    # ... set up steps ...

    - name: Warm SPM cache
      run: swift package resolve

    - name: Warm derived data cache
      run: xcodebuild build -scheme YourScheme -destination 'platform=iOS Simulator,name=iPhone 15 Pro' -quiet

This ensures your main workflows always have warm caches to work with.

Matrix caching

If you're building for multiple configurations, share caches between them:

strategy:
  matrix:
    scheme: [MyApp, MyAppTests]

steps:
- name: Cache Xcode derived data
  uses: actions/cache@v4
  with:
    path: ~/Library/Developer/Xcode/DerivedData
    key: ${{ runner.os }}-xcode-${{ matrix.scheme }}-${{ hashFiles('**/*.xcodeproj/project.pbxproj') }}
    restore-keys: |
      ${{ runner.os }}-xcode-${{ matrix.scheme }}-
      ${{ runner.os }}-xcode-  # Fallback to any scheme

Conditional caching

Only cache CocoaPods if you actually use them:

- name: Cache CocoaPods
  if: hashFiles('**/Podfile.lock') != ''  # Only run if Podfile.lock exists
  uses: actions/cache@v4
  with:
    path: Pods
    key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}

Cache size optimization

Clean up your derived data before caching to keep it manageable:

- name: Clean derived data before caching
  run: |
    # Keep only the most recent build products
    find ~/Library/Developer/Xcode/DerivedData -name "Build" -type d -exec rm -rf {}/Intermediates.noindex \;

Monitoring cache performance

Add some logging to see how much time you're saving:

- name: Cache Swift Package Manager
  id: spm-cache
  uses: actions/cache@v4
  with:
    path: .build
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}

- name: Report cache status
  run: |
    if [ "${{ steps.spm-cache.outputs.cache-hit }}" == "true" ]; then
      echo "✅ SPM cache hit! Saved time on dependency resolution."
    else
      echo "❌ SPM cache miss. Dependencies will be downloaded."
    fi

You can also track cache performance over time by checking the Actions logs and seeing how often you get cache hits vs misses.

Troubleshooting common caching issues

"Cache size exceeded 10GB limit"

GitHub Actions has a 10GB cache limit per repository. If you hit this:

Clean your derived data: Remove build intermediates before caching
Use more specific cache keys: Separate caches for different branches/schemes
Set up cache cleanup: Use actions/cache/restore and actions/cache/save to have more control

- name: Clean cache before saving
  run: |
    # Remove large intermediate files
    rm -rf ~/Library/Developer/Xcode/DerivedData/*/Build/Intermediates.noindex

"Cache is slower than rebuilding"

This usually happens when your cache keys are too broad. If you're invalidating cache too often:

Make keys more specific: Use more granular file hashes
Use restore keys effectively: Have good fallback strategies
Profile your cache sizes: Large caches can be slower to restore than rebuilding

"Dependencies not found after cache restore"

This often happens with SPM when the cache doesn't include everything needed:

- name: Cache Swift Package Manager
  uses: actions/cache@v4
  with:
    path: |
      .build
      ~/Library/Developer/Xcode/DerivedData/ModuleCache.noindex
      ~/Library/Caches/org.swift.swiftpm
      ~/Library/org.swift.swiftpm  # Don't forget this!
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}

"CocoaPods cache not working"

Make sure you're not skipping the cache in your pod install:

- name: Install pods
  run: bundle exec pod install
  # Note: Don't use COCOAPODS_SKIP_CACHE=TRUE if you want caching!

Cache key collisions

If you're seeing unexpected cache behavior, you might have key collisions. Make your keys more unique:

key: ${{ runner.os }}-${{ github.workflow }}-xcode-${{ hashFiles('**/*.xcodeproj/project.pbxproj') }}

Best practices and gotchas

Do's

✅ Start with Ruby gem caching - It's built into setup-ruby, easy to set up, and gives immediate benefits

✅ Use specific file patterns for cache keys - Package.resolved, Podfile.lock, etc. are better than generic patterns

✅ Set up restore keys - Always have a fallback strategy

✅ Monitor cache hit rates - Add logging to see how well your caching is working

✅ Clean before caching - Remove temporary files to keep cache sizes manageable

Don'ts

❌ Don't cache node_modules equivalent directories without good reason - They can be huge and change frequently

❌ Don't use overly broad cache keys - ${{ runner.os }}-cache will almost never hit

❌ Don't cache secrets or sensitive data - Caches are not encrypted

❌ Don't forget about cache limits - 10GB per repo, plan accordingly

❌ Don't cache absolute paths - Use relative paths when possible

Real-world impact

Let me share some real numbers from implementing this in production:

Before caching:

Average build time: 14 minutes
Cache hit rate: 0% (obviously)
GitHub Actions cost: ~$50/month for a team of 5

After implementing smart caching:

Average build time: 4 minutes
Cache hit rate: 85% (meaning 85% of builds use cached dependencies)
GitHub Actions cost: ~$15/month
Developer happiness: Significantly improved 😄

That's a 70% reduction in build time and 70% reduction in costs. Not bad for a few hours of YAML writing!

What's next?

Once you've got caching humming along nicely, you can explore:

Self-hosted runners with persistent caches (for even faster builds)
Docker layer caching (if you're containerizing your builds)
Artifact caching between different workflows
Build result caching (only rebuild what changed)

But honestly? The strategies in this post will get you 90% of the benefit with 10% of the complexity. Perfect is the enemy of good, and good caching is already pretty amazing.

Conclusion

Look, I get it. YAML configuration isn't the sexiest part of iOS development. But trust me on this one - spending an hour setting up proper caching will save you hours every week waiting for builds.

Your future self will thank you when you push a small change and your CI finishes before you can even switch to Twitter. Your teammates will think you're a wizard. Your manager will love the reduced CI costs. And you'll finally have time to do what we all really want to do: write more Swift code instead of watching progress bars.

The strategies in this post have saved my team literally hundreds of hours over the past year. That's time we could spend on features, bug fixes, or just not being frustrated by slow builds.

So go forth, cache all the things, and may your builds be swift and your coffee always hot! ☕️

Got questions about caching? Hit me up! I love talking about developer productivity, especially when it involves making computers do less work. That's basically the entire point of programming, right? 😄

P.S. - If you found this helpful, you might also enjoy our previous posts on GitHub Actions setup and TestFlight automation. Together, they form the holy trinity of iOS CI/CD automation.

Learning to Learn with AI (for Developers)

NoamIfergan@gmail.com — Wed, 16 Jul 2025 00:00:00 GMT

Introduction

I know I know, another blog post about AI. But this one is different, I swear!
In a sea of AI agents, tools, IDEs and everything in between, it's really easy to get lost in the "let this thing do it for me" mindset. And I have to admit, I've been there.

I love using AI to take the boring away from me. That be boilerplate, revision of PRs, things that I can't be bothered to do.
But I've also been guilty of using AI to do things that I should be doing myself, not because I know how to do them, but because I don't. let's talk about it.

The problem

AI is great right? you can build shit that you wouldn't normally be able to build, and without much effort. Are you a web-dev that wants an app? no problem, just ask Claude to build it for you. Are you an iOS dev that wants a backend? Sick, Cursor has go you sorted. We've all been there, and it's great.

But what happens when you don't know what you don't know? when AI inevitable hits the infinite feedback loop of "a ha! now i see the problem" and you're left with a bug or unexpected behavior?

Or, and perhaps more importantly, what happens when you don't know what you're supposed to know? That can be the codebase that you're working on in your job, that can be a feature or a product you're delivering to a client, or that can even be something that you're trying to learn?

What happens when someone asks you, live, face to face or in a meeting, "how is this thing done?", "how long will it take to do this?", "is this thing feasible?"? if you don't know what you're doing, you've only been a pass-thorough to some agent, you be stuck in a very embarrassing situation.

And lastly, you're going to change jobs eventually. might not be today, might not be next week, but it's going to happen. and you're going to be left stuck in the same place, with whatever knowledge you've had the last time you were actually coding, stagnant. the world moves fast, and if you're not continuously learning, you're left behind.

My approach

You'll notice that i'm not calling this section "the solution", because I don't claim to have the answer. or at least not the answer that will work for everyone. i have the answer that has worked for me and I'm going to share it with you.

I've recently started a new job at a tremendous company, and the code base is a bit of a beast. firstly, we use KMP, a framework i have never touched before, bar the tiniest of projects. And secondly, it has a lot more emphasis on Kotlin and Android than i had in the recent years, being an iOS developer. I haven't lied during my interview process, the company knew i'm an iOS developer who's happy to learn new things, but i still felt like i have that self-inflected stress over my head of "you should be able to do this".

Not only that, i've also had some client work that has involved some MacOS development, which i've never done before. goes without saying, that has stressed me out as well.

So, while i could use AI to do tickets for me ( or at least attempt to), i've been using it for a different purpose. I've been using it to teach me about the project, about KMP, and about everything else that i'm not familiar with.

The obvious way i do this is by asking AI how things are done in Kotlin, or on MacOS, or whatever that might be. while yes, i can just ask it to do it for me, by asking it how things are done, and then doing them myself, i get the repetition and learning process.

Another way i've been using it, is by asking it to onboard me on certain parts of the codebase. So if i'm working on a new feature in an existing module / part of the code, i will ask it to explain to me:

What are the main components of the module?
What is the architecture used?
What are patterns or conventions i should adhere to ?
What are the main concepts that i should be aware of?

These questions help me greatly understand what am i looking at. this is a very important step in learning any new code base, and i think it's crucial to understand those pointers so you can become comfortable and confident in the codebase, and then you can start to build your own knowledge of the codebase.

Tools

So while doing this, i've found certain tools seem to be more helpful than other, but like everything else in programming (and life), pick the right tool for the job.

Cursor

I've been using cursor for context-specific code questions that require knowledge of the codebase.
The main ways i've used this before is "Where is this thing", or "Why is this error happening", or my personal favorite, "am i doing this like the rest of the codebase?"

The reason for the last question is that we've all been doing things our way, and that's great. but new codebases have their own ways of doing things, their own conventions and patterns. so while you might be used to having view models and presenters, the new codebase might have a different approach. so it's good to ask either before you start, or just after you've started, "is this following the codebase's conventions?"

Claude

Claude has been my new google for a while now. i mainly use it for "how do you do this in Kotlin?" or "how do you do this in Android?" or "how do you do this in KMP?". Think of it like that, you know that the thing you're building needs a switch statement, you write switch, but whoops the compiler doesn't understand what you're talking about? that's because switch is called when in Kotlin. These are small, minuscule things, but they might waste your time, and there's no need for that struggle - you know what you want to do, syntax is just a tool to get there.

Copilot

Admittedly, i've been using copilot less and less now, as cursor has been replacing it more and more, but when i write code either in Xcode or Android Studio, i still use it for auto completion of basic things. So i try not to use it for too big of a job, as i still want the repetition to build the muscle memory, but i use it for things like autocompletion of init methods, or auto completion of basic functions.

Pitfalls

Like everything else in life, this isn't a 100% solution. AI can be, and is, wrong. sometimes i'll ask it where something is, and it will hallucinate a location or a module, and i'll be sent down a rabbit hole of trying to find it. Sometimes it guesses the autocompletion of an init method and i'll be left with a bug that i didn't see coming.

But that's the beauty of it, it's not a replacement for you, it's a tool to help you. It's a tool to help you learn, to help you understand, to help you get things done.

Main takeaways

AI is great, but it's not a replacement for you. It wants to be, but it's up to you to not let it.
It's very easy to fall into the trap of using AI to do things for you. the speed of the feedback loop is too tempting. but you're not learning anything. if you want to be a better engineer, you need to learn.
It might be a cliche, but it's not about the destination, it's about the journey. Programming is such a vast field, and there is so much to learn, it can be daunting. but that's the beauty of it, there is always something to learn. if you don't learn, you're going to be stagnant. and if you're stagnant, you're going to be the one left behind.
This is by no means a "AI BAD" post. i love AI, i use it every single day, and i think that if you don't use it you're going to struggle to keep up, but you shouldn't lose sight of the fact that it's a tool, and you're the wielder. you should be able to jump in and do whatever it is doing, at any point.

Auto-Deploy to TestFlight via GitHub Actions Tag

NoamIfergan@gmail.com — Wed, 09 Jul 2025 00:00:00 GMT

Introduction

This is it! This is the post we've been building up to in our "GitHub Actions to TestFlight - from zero to hero" series. We've set up GitHub Actions for iOS, we've automated our unit tests, and now we're going to put it all together to create the ultimate iOS developer dream: tagging your branch with "testflight" and having your app automatically built, tested, and deployed to TestFlight.

No more manual builds, no more forgetting to increment version numbers, no more "works on my machine" deployments. Just tag, push, and relax while the robots do all the work. Let's make it happen! 🚀

The workflow we're building

Here's what's going to happen when you tag your branch with "testflight":

Tests run - Making sure everything still works
Version numbers bump - Using our version bumping knowledge
App builds - Using our Fastlane building skills
App uploads to TestFlight - The magic moment
Notifications sent - So you know it worked

All triggered by a simple git tag testflight && git push --tags. Beautiful, right?

Pre-requisites

Before we dive in, make sure you have:

A working GitHub Actions setup from our previous posts
An App Store Connect API key (more on this below)
Your app already created in App Store Connect
Code signing certificates and provisioning profiles set up

If you're missing any of these, don't worry - I'll walk you through the tricky parts.

Setting up App Store Connect API Key

First things first - we need a way for our GitHub Action to authenticate with App Store Connect. The old username/password method is deprecated, so we're using API keys.

Creating the API key

Go to App Store Connect
Navigate to Users and Access → Integrations → App Store Connect API
Click the + button to create a new key
Give it a name like "GitHub Actions"
Select the "Developer" role (or "Admin" if you need more permissions)
Download the .p8 file and note the Key ID and Issuer ID

⚠️ Important: You can only download the .p8 file once! Keep it safe.

Adding secrets to GitHub

Now we need to add these credentials to GitHub as secrets:

Go to your repository on GitHub
Settings → Secrets and variables → Actions
Add these repository secrets:
- APP_STORE_CONNECT_API_KEY: The content of your .p8 file
- APP_STORE_CONNECT_API_KEY_ID: Your Key ID
- APP_STORE_CONNECT_ISSUER_ID: Your Issuer ID
- APP_STORE_CONNECT_APP_ID: Your app's App Store ID (found in App Store Connect)

For the API key content, you can get it with:

cat AuthKey_XXXXXXXXXX.p8 | base64

Copy the entire base64 string into the secret.

Code signing in CI

Code signing is probably the most painful part of iOS CI/CD. If you followed our GitHub Actions setup post, you should already have Fastlane Match configured. If not, here's a quick refresher:

Fastlane Match Setup (Required)

Our build lane uses Fastlane Match to handle code signing automatically. If you haven't set this up yet, you'll need to:

Create a private Git repository for certificates
Initialize Match in your project:
```
bundle exec fastlane match init
```
Generate certificates:
```
bundle exec fastlane match appstore
```

For a complete setup guide, check out the Match setup section in our previous post.

Required GitHub Secrets

Make sure you have these secrets configured in your repository:

MATCH_REPOSITORY: URL to your certificates repository
MATCH_PASSWORD: Your Match encryption passphrase
MATCH_GIT_PRIVATE_KEY: SSH private key for accessing your private certificates repository

For detailed setup instructions, see the SSH access setup section in our first post.

Alternative: Manual certificates

If you prefer not to use Match, you can create a separate Fastlane lane for manual certificate setup:

desc "Set up manual certificates"
lane :setup_certificates do
  import_certificate(
    certificate_path: "ios_distribution.p12",
    certificate_password: ENV["IOS_CERTIFICATE_PASSWORD"],
    keychain_name: "login.keychain"
  )

  install_provisioning_profile(
    path: "MyApp_AppStore.mobileprovision"
  )
end

Then call it as a separate step in your GitHub Actions workflow:

- name: Set up code signing
  run: bundle exec fastlane setup_certificates
  env:
    IOS_CERTIFICATE_PASSWORD: ${{ secrets.IOS_CERTIFICATE_PASSWORD }}

But honestly? Match is so much easier. 😉

The TestFlight deployment workflow

Now for the main event! Here's our complete workflow:

name: Deploy to TestFlight

on:
  push:
    tags:
      - 'testflight*'

jobs:
  deploy:
    runs-on: macos-latest

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # We need full history for version bumping

    # Set up Xcode 16.2
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: "16.2.0"

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.1
        bundler-cache: true

    - name: Cache Xcode derived data
      uses: actions/cache@v4
      with:
        path: ~/Library/Developer/Xcode/DerivedData
        key: ${{ runner.os }}-xcode-deriveddata-${{ hashFiles('**/*.xcodeproj/project.pbxproj') }}
        restore-keys: |
          ${{ runner.os }}-xcode-deriveddata-

    - name: Install dependencies
      run: bundle install

    - name: Setup App Store Connect API Key
      run: |
        mkdir -p ~/.appstoreconnect/private_keys/
        echo "${{ secrets.APP_STORE_CONNECT_API_KEY }}" | base64 --decode > ~/.appstoreconnect/private_keys/AuthKey_${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}.p8

    # Set up SSH key for Match repository access
    - name: Set up SSH key for Match
      run: |
        mkdir -p ~/.ssh
        echo "${{ secrets.MATCH_GIT_PRIVATE_KEY }}" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        ssh-keyscan github.com >> ~/.ssh/known_hosts
        # Create SSH config for GitHub
        cat > ~/.ssh/config << EOF
        Host github.com
          HostName github.com
          User git
          IdentityFile ~/.ssh/id_rsa
          IdentitiesOnly yes
        EOF
        # Test SSH connection
        ssh -T git@github.com || true

    - name: Set up code signing
      run: bundle exec fastlane match appstore --readonly --app_identifier com.yourcompany.yourapp
      env:
        MATCH_REPOSITORY: ${{ secrets.MATCH_REPOSITORY }}
        MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}

    - name: Run tests
      run: bundle exec fastlane test

    - name: Build and Deploy to TestFlight
      run: bundle exec fastlane deploy_testflight
      env:
        APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
        APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
        APP_STORE_CONNECT_APP_ID: ${{ secrets.APP_STORE_CONNECT_APP_ID }}

    - name: Clean up API Key
      if: always()
      run: rm -f ~/.appstoreconnect/private_keys/AuthKey_${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}.p8

The Fastlane lanes

Now we need to create the Fastlane lanes that this workflow calls. Add these to your Fastfile:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    # Build the app (code signing should be done separately)
    gym(
      scheme: "YourAppScheme",
      configuration: "Release",
      export_method: "app-store",
      output_directory: "./build",
      export_options: {
        uploadBitcode: false,
        uploadSymbols: true,
        compileBitcode: false
      }
    )
  end

  desc "Run tests"
  lane :test do
    scan(
      scheme: "YourAppScheme",
      clean: true,
      devices: "iPhone 15 Pro",
      output_directory: "./fastlane/test_output",
      output_types: "html,junit"
    )
  end

  desc "Deploy to TestFlight"
  lane :deploy_testflight do
    # First, let's bump the build number
    # Get the latest build numbers from both TestFlight and App Store
    latest_tf_build = latest_testflight_build_number(
      app_identifier: "com.yourcompany.yourapp",
      api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
      issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"]
    )

    latest_appstore_build = app_store_build_number(
      app_identifier: "com.yourcompany.yourapp",
      api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
      issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"]
    )

    # Use the highest build number and increment by 1
    highest_build = [latest_tf_build, latest_appstore_build].max
    increment_build_number_in_xcodeproj(
      build_number: highest_build + 1
    )

    # Build the app (code signing was done in a previous step)
    build

    # Upload to TestFlight
    pilot(
      app_identifier: "com.yourcompany.yourapp",
      api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
      issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"],
      skip_waiting_for_build_processing: true,
      changelog: "Automated build from GitHub Actions",
      distribute_external: false,
      notify_external_testers: false
    )

    # Send a notification (optional)
    slack(
      message: "🚀 New TestFlight build is processing!",
      slack_url: ENV["SLACK_WEBHOOK_URL"]
    ) if ENV["SLACK_WEBHOOK_URL"]
  end

end

Let me break down what's happening in the deploy_testflight lane:

Version bumping

# Get the latest build numbers from both TestFlight and App Store
latest_tf_build = latest_testflight_build_number(
  app_identifier: "com.yourcompany.yourapp",
  api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
  issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"]
)

latest_appstore_build = app_store_build_number(
  app_identifier: "com.yourcompany.yourapp",
  api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
  issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"]
)

# Use the highest build number and increment by 1
highest_build = [latest_tf_build, latest_appstore_build].max
increment_build_number_in_xcodeproj(
  build_number: highest_build + 1
)

This gets the latest build numbers from both TestFlight and the App Store, finds the highest one, and increments it by 1. This prevents version conflicts that could occur if the App Store has a higher build number than TestFlight. No more version conflicts! This builds on what we learned in our version bumping post.

Building the app

# Build the app (code signing was done in a previous step)
build

This calls our build lane from our GitHub Actions setup post. Since we've already set up code signing in a previous workflow step, the build lane can focus purely on building the app. Clean and efficient!

Uploading to TestFlight

pilot(
  app_identifier: "com.yourcompany.yourapp",
  api_key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
  issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"],
  skip_waiting_for_build_processing: true,
  changelog: "Automated build from GitHub Actions",
  distribute_external: false,
  notify_external_testers: false
)

This uploads your app to TestFlight. The skip_waiting_for_build_processing option means the workflow won't wait for Apple to process the build (which can take 10-30 minutes). The distribute_external and notify_external_testers options are set to false to prevent automatically distributing to external testers - you'll want to review builds manually first.

Advanced features

Smart tagging

Instead of just using "testflight", you can make your tags more informative:

on:
  push:
    tags:
      - 'testflight*'
      - 'tf-*'
      - 'beta-*'

This allows tags like testflight-v1.2.3, tf-hotfix, or beta-release.

Version from tag

You can extract version information from your tag:

desc "Deploy to TestFlight with version from tag"
lane :deploy_testflight do
  # Extract version from git tag
  tag_name = ENV["GITHUB_REF_NAME"] || sh("git describe --tags --abbrev=0").strip

  if tag_name.include?("-v")
    version = tag_name.split("-v").last
    increment_version_number(version_number: version)
  end

  # ... rest of the lane
end

Now you can tag with testflight-v1.2.3 and it will set your app version to 1.2.3.

Conditional notifications

Only send notifications for production builds:

# Send notification only for main branch
if ENV["GITHUB_REF"] == "refs/heads/main"
  slack(
    message: "🚀 Production TestFlight build is ready!",
    slack_url: ENV["SLACK_WEBHOOK_URL"]
  )
end

Build artifacts

Save your .ipa file as a GitHub artifact:

- name: Upload build artifacts
  uses: actions/upload-artifact@v4
  with:
    name: ios-app-${{ github.sha }}
    path: build/*.ipa

Using the workflow

Now for the moment of truth! Here's how to use your new automated TestFlight deployment:

Make your changes and commit them
Tag your commit: git tag testflight
Push the tag: git push --tags
Watch the magic happen in the GitHub Actions tab

You can also do it all in one go:

git add .
git commit -m "Ready for TestFlight"
git tag testflight-$(date +%Y%m%d-%H%M%S)
git push --tags

This creates a unique tag with a timestamp, so you can deploy multiple times per day without conflicts.

Troubleshooting

"Invalid API Key"

Make sure your API key is properly base64 encoded and that you've set all three required secrets (API key, key ID, and issuer ID).

"No matching provisioning profiles found"

This usually means your provisioning profile doesn't match your app's bundle identifier or capabilities. Double-check your Match setup or manual provisioning profiles.

"Build already exists"

This happens when you try to upload a build with the same version and build number as an existing build. Our version bumping should prevent this, but if it happens, you might need to manually increment the build number.

"Processing takes too long"

Apple's build processing can sometimes take a very long time. If you're hitting timeout issues, consider using skip_waiting_for_build_processing: true and checking the status manually later.

Monitoring and notifications

Slack notifications

Add Slack notifications to know when your builds succeed or fail:

slack(
  message: "✅ TestFlight deployment successful!",
  success: true,
  payload: {
    "Build Number" => get_build_number,
    "Version" => get_version_number,
    "Git Commit" => ENV["GITHUB_SHA"]
  },
  slack_url: ENV["SLACK_WEBHOOK_URL"]
)

Email notifications

GitHub Actions can also send email notifications on failure:

- name: Send failure notification
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: "TestFlight deployment failed"
    body: "The TestFlight deployment for ${{ github.repository }} failed. Check the logs at ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
    to: your-email@example.com

Best practices

Branch protection

Consider protecting your main branch and requiring pull request reviews before changes can be merged. This prevents accidental TestFlight deployments from broken code.

Environment separation

You might want different workflows for different environments:

testflight tag → Internal TestFlight
beta tag → External TestFlight
release tag → App Store

Testing before deployment

Always run your full test suite before deploying:

desc "Deploy to TestFlight"
lane :deploy_testflight do
  # Run tests first
  scan(scheme: "YourAppScheme")

  # Only proceed if tests pass
  # ... rest of deployment
end

Security considerations

Least privilege

Your API key should have the minimum permissions needed. Usually "Developer" role is sufficient for TestFlight uploads.

Secret rotation

Rotate your API keys and certificates regularly. Consider using different keys for different environments.

Branch restrictions

Consider restricting TestFlight deployments to specific branches:

on:
  push:
    tags:
      - 'testflight*'
    branches:
      - main
      - release/*

What's next?

Congratulations! You've just set up one of the most powerful iOS development workflows possible. You can now:

Push code to GitHub
Tag it with "testflight"
Have it automatically tested, built, and deployed to TestFlight
Get notified when it's done

This is the kind of automation that makes iOS development feel magical. No more manual builds, no more forgetting steps, no more "works on my machine" problems.

But we're not done yet! You could extend this further with:

Automatic App Store submissions (for approved builds)
Integration with project management tools
Automated release notes generation
Performance monitoring integration
Crash reporting setup

The possibilities are endless!

Conclusion

We've come a long way in this series! We started with basic GitHub Actions setup, moved on to automated testing, and now we've created a complete TestFlight deployment pipeline.

This workflow leverages everything we've learned in our Fastlane series - building apps, running tests, and managing versions - and combines it with the power of GitHub Actions automation.

The result? A professional-grade iOS deployment pipeline that would make any DevOps engineer proud. And the best part? It's all free (within GitHub's generous limits) and runs in the cloud, so your laptop can stay in sleep mode while your app gets built and deployed.

Try it out, customize it for your needs, and let me know how it goes! And if you run into any issues, remember that both GitHub Actions and Fastlane have excellent logging - the answer is usually in the logs.

Happy deploying! 🚀

P.S. - If you found this series helpful, consider sharing it with other iOS developers. Automation like this can save hours every week, and everyone deserves to experience the joy of git tag testflight && git push --tags followed by a coffee break while the robots do all the work!

Run iOS Unit Tests in GitHub Actions CI

NoamIfergan@gmail.com — Thu, 19 Jun 2025 00:00:00 GMT

Introduction

Welcome back to our "GitHub Actions to TestFlight - from zero to hero" series! In our last post, we set up a basic GitHub Actions workflow that builds our iOS app every time we push to the main branch. That's great, but you know what's even better? Making sure our app actually works before we ship it.

Today, we're going to extend our workflow to run unit tests automatically. This builds on what we learned in our running unit tests with Fastlane post, but now we're going to do it in the cloud, automatically, every time we push code.

Because let's be honest - we all write unit tests (right?), but do we always remember to run them before pushing? I certainly don't. Let the robots handle it!

Why run tests in CI?

Catch issues early

Running tests on every push and pull request means you catch issues before they make it to the main branch. This is especially important when you're working in a team - you don't want to be the person who breaks the build for everyone else.

Consistency

Your local machine might have different versions of Xcode, different simulators, or different environment variables. Running tests in CI ensures that everyone's tests run in the same environment.

Test against multiple configurations

Want to make sure your app works on iOS 15, 16, and 17? Or test against both iPhone and iPad simulators? CI makes this easy with matrix builds.

Building on our existing workflow

Remember the workflow we created in the previous post? We're going to extend it to run tests as well. Let's start by adding a new job to our workflow:

name: Build and Test iOS App

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: macos-latest

    strategy:
      matrix:
        device: ['iPhone 16 Pro']

    steps:
    - uses: actions/checkout@v4

    # Set up Xcode 16
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: "16.2.0"

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.1
        bundler-cache: true

    - name: Install dependencies
      run: bundle install

    - name: Run tests
      run: bundle exec fastlane test

    - name: Upload test results
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: test-results-${{ matrix.device }}
        path: |
          fastlane/test_output/
          *.junit

Let me break this down for you.

Understanding matrix builds

strategy:
  matrix:
    device: ['iPhone 16 Pro']

The matrix strategy allows us to run the same job with different configurations. In this case, we're running tests with different devices. You can easily extend this to test multiple devices:

strategy:
  matrix:
    device: ['iPhone 16 Pro', 'iPad Pro 13-inch (M4)', 'iPhone SE (3rd generation)']

This would create 3 different jobs, each testing on a different device.

If you need to test with different Xcode versions, you could do something like:

strategy:
  matrix:
    xcode-version: ['15.4', '16.0']
    device: ['iPhone 16 Pro']

steps:
- uses: actions/checkout@v4

- name: Set up Xcode
  uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: ${{ matrix.xcode-version }}

This would test your app with both Xcode 15.4 and 16.0, which is useful when you want to ensure compatibility across different Xcode versions.

Setting up Fastlane for tests

Just like in our unit testing with Fastlane post, we need a test lane in our Fastfile. Building on the enhanced build lane from our previous post, your Fastfile should look like this:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    # Build the app (code signing should be done separately)
    gym(
      scheme: "YourAppScheme",
      configuration: "Release",
      export_method: "app-store",
      output_directory: "./build",
      export_options: {
        uploadBitcode: false,
        uploadSymbols: true,
        compileBitcode: false
      }
    )
  end

  desc "Run tests"
  lane :test do
    scan(
      scheme: "YourAppScheme",
      clean: true,
      destination: "platform=iOS Simulator,name=iPhone 16 Pro",
      output_directory: "./fastlane/test_output",
      output_types: "html,junit"
    )
  end

end

This approach uses a fixed destination, which is more reliable than dynamic device selection in CI environments.

Making it more robust

Let's enhance our workflow to handle some common scenarios:

name: Build and Test iOS App

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: macos-latest

    strategy:
      matrix:
        device: ['iPhone 16 Pro', 'iPhone SE (3rd generation)']
      fail-fast: false

    steps:
    - uses: actions/checkout@v4

    # Set up Xcode 16
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: "16.2.0"

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.1
        bundler-cache: true

    - name: Cache Xcode derived data
      uses: actions/cache@v4
      with:
        path: ~/Library/Developer/Xcode/DerivedData
        key: ${{ runner.os }}-xcode-deriveddata-${{ hashFiles('**/*.xcodeproj/project.pbxproj') }}
        restore-keys: |
          ${{ runner.os }}-xcode-deriveddata-

    - name: Install dependencies
      run: bundle install

    # Optional: List available simulators for debugging
    - name: List available simulators
      run: xcrun simctl list devices available

    # Note: For unit tests, you typically don't need code signing
    # Remove these steps if your tests don't require it

    - name: Run tests
      run: bundle exec fastlane test

    - name: Upload test results
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: test-results-${{ matrix.device }}
        path: |
          fastlane/test_output/
          *.junit

    - name: Upload coverage reports
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: coverage-${{ matrix.device }}
        path: |
          *.xcresult

Key features explained

Caching

The cache step stores Xcode's derived data between runs, significantly speeding up builds. The cache key is based on your project file, so it invalidates when you change your project structure.

Destination parameter

Using destination: "platform=iOS Simulator,name=iPhone 16 Pro" in the Fastfile is more reliable than device name resolution, especially in CI environments where simulator IDs can be inconsistent.

fail-fast: false

By default, if one job in a matrix fails, GitHub Actions cancels all other jobs. Setting fail-fast: false means all jobs run to completion, so you see all test results, not just the first failure.

Handling different types of tests

You can create separate jobs for different types of tests:

jobs:
  unit-tests:
    runs-on: macos-latest
    steps:
      # ... setup steps
      - name: Run unit tests
        run: bundle exec fastlane unit_tests

  integration-tests:
    runs-on: macos-latest
    needs: unit-tests
    steps:
      # ... setup steps
      - name: Run integration tests
        run: bundle exec fastlane integration_tests

  ui-tests:
    runs-on: macos-latest
    needs: [unit-tests, integration-tests]
    steps:
      # ... setup steps
      - name: Run UI tests
        run: bundle exec fastlane ui_tests

The needs keyword creates dependencies between jobs. Integration tests wait for unit tests to pass, and UI tests wait for both unit and integration tests to complete.

Advanced: Parallel testing

Remember our parallel testing post? We can leverage that in GitHub Actions too:

desc "Run tests in parallel"
lane :test do
  scan(
    scheme: "YourAppScheme",
    clean: true,
    destination: "platform=iOS Simulator,name=iPhone 16 Pro",
    parallel_testing: true,
    concurrent_workers: 4,
    output_directory: "./fastlane/test_output",
    output_types: "html,junit"
  )
end

This runs your tests faster by using multiple worker processes.

Test reporting

GitHub Actions can parse JUnit XML files and show test results directly in pull requests:

- name: Publish test results
  uses: dorny/test-reporter@v1
  if: always()
  with:
    name: Test Results
    path: 'fastlane/test_output/*.junit'
    reporter: java-junit

This creates a test results summary in the GitHub UI.

Troubleshooting common issues

"No simulators available" or "Unable to find a destination"

This is the most common issue! The simulator you specified might not be available on the runner. Different Xcode versions come with different simulator versions. For example, Xcode 16.2 comes with iPhone 16 simulators, not iPhone 15.

First, list available simulators to see what's actually available:

- name: List available simulators
  run: xcrun simctl list devices available

Then update your device names to match what's actually available. Common device names in Xcode 16.2:

iPhone 16 Pro
iPhone 16 Pro Max
iPhone SE (3rd generation)
iPad Pro 13-inch (M4)

Pro tip: Instead of using device or devices, use destination for more reliable results:

scan(
  scheme: "YourAppScheme",
  destination: "platform=iOS Simulator,name=iPhone 16 Pro"
)

This approach is more explicit and avoids simulator ID caching issues.

"Test failed due to timeout"

CI environments can be slower than your local machine. You might need to increase timeouts in your test configuration.

"Code signing error"

For running tests, you usually don't need code signing. Make sure your test target's code signing is set to "Don't Code Sign" or use the iOS Simulator SDK.

Clearing simulator cache

If you're still getting old simulator ID errors after updating device names, try clearing cached data:

rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf YourProject.xcodeproj/project.xcworkspace/xcuserdata

What's next?

Great! Now we've got a workflow that builds and tests our app automatically. But we're not done yet. In the next post, we're going to put it all together and create a workflow that automatically deploys to TestFlight when we tag our branch with "TestFlight".

That's where things get really exciting - we'll be dealing with certificates, provisioning profiles, App Store Connect API keys, and actually shipping our app to testers.

Conclusion

Running tests in CI seems like overhead at first, but once you have it set up, you'll wonder how you ever lived without it. No more "oops, I forgot to run the tests" commits, no more broken builds, and no more manual testing every time you want to make sure everything still works.

The workflow we've created today catches issues early, tests against multiple configurations, and gives you confidence that your app works before you ship it. Best of all, it runs automatically - you don't have to remember to do anything!

If you run into any issues, the GitHub Actions logs will usually tell you exactly what went wrong.

Next up: the main event - deploying to TestFlight with tags! 🚀

Set Up GitHub Actions for iOS Projects (From Scratch)

NoamIfergan@gmail.com — Thu, 12 Jun 2025 00:00:00 GMT

Introduction

So, you've been building your app with Fastlane, maybe even running your unit tests like the responsible developer you are (right?), and now you're thinking: "This is great, but I'm still doing this manually on my machine. What if I could automate this even further?"

Well, my friend, you've come to the right place! In this series, we're going to take your iOS development automation to the next level by setting up GitHub Actions to automatically trigger TestFlight builds when we tag our branch with "testflight". But before we get to the fun stuff, we need to lay the groundwork.

This is going to be the first post in our "GitHub Actions to TestFlight - from zero to hero" series, and just like our Fastlane series, we're going to start from the beginning and work our way up.

Why GitHub Actions?

It's free (mostly)

GitHub Actions gives you 2,000 minutes per month for free on public repositories, and 2,000 minutes per month for free on private repositories too. For most indie developers and small teams, this is more than enough to get started. And even if you go over, the pricing is pretty reasonable.

It's integrated

Unlike other CI/CD solutions that you need to set up separately, GitHub Actions is built right into GitHub. This means no additional accounts to manage, no webhooks to configure, and no external services to worry about. It just works.

It's powerful

GitHub Actions can do pretty much anything you can think of. Build your app, run your tests, deploy to TestFlight, send notifications to Slack, update your documentation, and even make coffee (okay, maybe not that last one, but you get the idea).

Pre-requisites

Before we dive in, let's make sure we've got everything we need:

A GitHub repository with your iOS project (obviously!)
Xcode project with a working build configuration
Basic familiarity with Fastlane (we've covered this in our previous series)
An Apple Developer account (for later posts when we actually deploy to TestFlight)

If you're missing any of these, no worries! Go get them set up and come back. I'll wait. ☕️

Understanding GitHub Actions

Before we start writing YAML files (yes, we're going to write YAML, but I promise it won't hurt), let's understand what GitHub Actions actually is.

GitHub Actions is essentially a way to run code on GitHub's servers whenever something happens in your repository. That "something" could be a push to main, a pull request, a new tag, or even something as simple as someone starring your repo.

The basic concepts

Workflows: These are the main files that define what should happen. They live in .github/workflows/ in your repository.

Jobs: Each workflow can have multiple jobs that run in parallel (or sequentially if you want).

Steps: Each job has multiple steps that run one after another.

Actions: These are pre-built pieces of functionality that you can use in your steps. Think of them as the npm packages of the CI/CD world.

Runners: These are the actual machines that run your code. GitHub provides Ubuntu, Windows, and macOS runners.

Setting up your first workflow

Let's start with something simple. We're going to create a workflow that builds your iOS app every time you push to the main branch. This is a great way to catch build errors early and make sure your app can always be built.

First, create the directory structure in your repository:

mkdir -p .github/workflows

Now, let's create our first workflow file:

name: Build iOS App

# When should this workflow run?
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    # We need a macOS runner for iOS builds
    runs-on: macos-latest
    
    steps:
    # First, we check out our code
    - uses: actions/checkout@v4
    
    # Set up Xcode 16.2
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: "16.2.0"
    
    # Set up Ruby (for Fastlane)
    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.1
        bundler-cache: true
    
    # Install dependencies
    - name: Install dependencies
      run: bundle install
    
    # Set up SSH key for Match repository access
    - name: Set up SSH key for Match
      run: |
        mkdir -p ~/.ssh
        echo "${{ secrets.MATCH_GIT_PRIVATE_KEY }}" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        ssh-keyscan github.com >> ~/.ssh/known_hosts
        # Create SSH config for GitHub
        cat > ~/.ssh/config << EOF
        Host github.com
          HostName github.com
          User git
          IdentityFile ~/.ssh/id_rsa
          IdentitiesOnly yes
        EOF
        # Test SSH connection
        ssh -T git@github.com || true
    
    # Set up code signing with Match
    - name: Set up code signing
      run: bundle exec fastlane match appstore --readonly --app_identifier com.yourcompany.yourapp
      env:
        MATCH_REPOSITORY: ${{ secrets.MATCH_REPOSITORY }}
        MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
    
    # Build the app using Fastlane
    - name: Build app
      run: bundle exec fastlane build

Let's break this down step by step:

The trigger

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

This tells GitHub Actions to run this workflow whenever someone pushes to the main branch, or when someone creates a pull request targeting the main branch. This is a great way to catch issues early!

The runner

runs-on: macos-latest

For iOS development, we need a macOS runner because Xcode only runs on macOS. GitHub provides macOS runners, but they're a bit more expensive than Linux runners (but still within the free tier for most use cases).

The steps

Each step does one specific thing:

Checkout the code: This downloads your repository's code to the runner
Set up Ruby: This installs Ruby and Bundler, which we need for Fastlane
Install dependencies: This runs bundle install to install all the gems in your Gemfile
Build the app: This runs your Fastlane build lane

Making it work with your project

Now, this workflow assumes you've got a Fastlane setup with a build lane, like we covered in our building with Fastlane post. If you don't have that set up yet, you'll need to do that first.

Your Fastfile should look something like this:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    # Build the app (code signing should be done separately)
    gym(
      scheme: "YourAppScheme",
      configuration: "Release",
      export_method: "app-store",
      output_directory: "./build",
      export_options: {
        uploadBitcode: false,
        uploadSymbols: true,
        compileBitcode: false
      }
    )
  end

end

Make sure to replace "YourAppScheme" with the actual scheme name from your Xcode project.

Code Signing Explained

Notice how we handle code signing as a separate step in our GitHub Actions workflow, before the build step:

- name: Set up code signing
  run: bundle exec fastlane match appstore --readonly

This approach separates concerns:

Code signing setup happens first, downloading certificates and provisioning profiles
Building happens second, using the certificates that are now installed
--readonly ensures we only download existing certificates, not create new ones

This makes debugging easier - if signing fails, you know exactly where to look!

Setting up Fastlane Match

Before our workflow can sign apps in CI, we need to set up Fastlane Match. Match is a tool that stores your certificates and provisioning profiles in a secure Git repository, encrypted with a passphrase.

Why Fastlane Match?

Traditional code signing is a nightmare in CI environments:

Manually exporting certificates and profiles
Managing expiration dates
Keeping multiple machines in sync
Security risks of storing certificates in CI systems

Match solves all of this by:

✅ Storing everything in an encrypted Git repository
✅ Automatically syncing certificates across team members and CI
✅ Handling certificate renewal
✅ Using a single source of truth for all code signing

Initial Match Setup

First, add Match to your Fastfile if it's not already there:

desc "Sync certificates and profiles"
lane :certificates do
  match(
    type: "appstore",
    readonly: false  # Allow creating new certificates during setup
  )
end

Creating the certificates repository

Create a new private Git repository for your certificates. This can be on GitHub, GitLab, or any other Git provider. Name it something like MyApp-certificates or ios-certificates.
Initialize Match in your project directory:

bundle exec fastlane match init

When prompted:

Enter the URL of your certificates repository
Choose a strong passphrase (you'll need this later)

Generating certificates

Now let's generate the certificates and profiles:

# Generate App Store certificates and profiles
bundle exec fastlane match appstore

Match will:

Create or download certificates from Apple Developer Portal
Create provisioning profiles for your app
Encrypt everything with your passphrase
Store it in your certificates repository

Important: Make sure your Apple Developer account has admin access, or this step will fail.

Verify it worked

You should see something like this in your certificates repository:

certs/
  distribution/
    [TEAM_ID].cer
    [TEAM_ID].p12
profiles/
  appstore/
    AppStore_[BUNDLE_ID].mobileprovision

All files are encrypted and can only be decrypted with your passphrase.

Team setup

If you're working with a team, each team member should run:

bundle exec fastlane match appstore --readonly

This downloads and installs the certificates locally without creating new ones.

Testing your workflow

Once you've committed and pushed these files to your repository, GitHub Actions will automatically pick them up and start running. You can see the status of your workflows by going to the "Actions" tab in your GitHub repository.

If everything goes well, you should see a green checkmark ✅. If something goes wrong, you'll see a red X ❌, and you can click on it to see what went wrong.

Common issues and troubleshooting

"No Gemfile found"

This means you don't have a Gemfile in your repository. Create one with:

source 'https://rubygems.org'

gem 'fastlane'

"Could not find scheme 'YourAppScheme'"

Make sure the scheme name in your Fastfile matches exactly with the scheme name in your Xcode project. Scheme names are case-sensitive!

"Error cloning certificates git repo" / "terminal prompts disabled"

This is the error you'll see if your Match repository is private and you haven't set up SSH authentication:

fatal: could not read Username for 'https://github.com': terminal prompts disabled
Error cloning certificates repo, please make sure you have read access to the repository

Solution: Follow the SSH access setup section above to configure SSH authentication for your private certificates repository.

"Enter passphrase for /Users/runner/.ssh/match_key"

If you see this error, it means your SSH key was generated with a passphrase:

Agent pid 2195
Enter passphrase for /Users/runner/.ssh/match_key: 
Error: Process completed with exit code 1.

Solution: Regenerate your SSH key without a passphrase:

ssh-keygen -t ed25519 -C "github-actions-match" -f ~/.ssh/github_actions_match -N ""

The -N "" flag is crucial - it creates a key without a passphrase, which is required for automated CI/CD environments.

"Repository not found" / "Could not read from remote repository"

If you see this error when Match tries to clone your certificates repository:

ERROR: Repository not found.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.

This usually means the SSH key isn't being used properly by Git. The updated workflow above uses an SSH config file which is more reliable than environment variables.

Double-check:

Repository exists: Make sure git@github.com:NoamEfergan/brewbuddy_certs actually exists
Deploy key is added: Verify you added the public key to the repository's deploy keys
Write access enabled: Ensure "Allow write access" is checked for the deploy key
Private key is correct: Verify the MATCH_GIT_PRIVATE_KEY secret contains the complete private key

"Permission denied (publickey)"

This means your SSH key isn't properly configured:

Check your deploy key: Make sure you added the public key to your certificates repository's deploy keys
Check write access: Ensure "Allow write access" is checked for the deploy key
Check the private key secret: Verify MATCH_GIT_PRIVATE_KEY contains the complete private key (including -----BEGIN and -----END lines)

"No value found for 'app_identifier'"

If you see this error after Match successfully clones and decrypts the certificates repo:

🔓  Successfully decrypted certificates repo
[!] No value found for 'app_identifier'

Solution: Add your app's bundle identifier to the Match command:

- name: Set up code signing
  run: bundle exec fastlane match appstore --readonly --app_identifier com.yourcompany.yourapp

Replace com.yourcompany.yourapp with your actual bundle identifier (the same one you used when setting up Match initially).

"xcodebuild: error: Unable to find a destination matching the provided destination specifier"

This usually means there's an issue with the simulator or device specification. For now, don't worry about this - we'll cover device selection in more detail in the next post.

Adding code signing secrets

Now that you have Fastlane Match set up, you need to add the secrets to your GitHub repository so the CI environment can access your certificates:

Go to your repository on GitHub
Settings → Secrets and variables → Actions
Add these repository secrets:
- MATCH_REPOSITORY: The URL to your certificates repository (e.g., https://github.com/yourteam/ios-certificates.git)
- MATCH_PASSWORD: Your Match encryption passphrase
- MATCH_GIT_PRIVATE_KEY: SSH private key for accessing your private certificates repository

⚠️ Security Note: These secrets are encrypted by GitHub and only accessible to your workflow. Never commit the repository URL, passphrase, or private keys to your code repository.

Setting up SSH access for private Match repository

Since your certificates repository is private (as it should be!), you need to set up SSH authentication:

1. Generate an SSH key pair

On your local machine, generate a new SSH key specifically for GitHub Actions:

ssh-keygen -t ed25519 -C "github-actions-match" -f ~/.ssh/github_actions_match -N ""

Important: The -N "" flag creates the key without a passphrase. This is necessary for automated CI/CD environments where there's no interactive terminal to enter passphrases.

This creates two files:

~/.ssh/github_actions_match (private key)
~/.ssh/github_actions_match.pub (public key)

2. Add the public key to your certificates repository

Go to your certificates repository on GitHub
Settings → Deploy keys
Click "Add deploy key"
Title: "GitHub Actions Match Access"
Key: Copy the content of ~/.ssh/github_actions_match.pub
✅ Check "Allow write access" (Match needs to update the repository)
Click "Add key"

3. Add the private key to your main repository secrets

Go to your main app repository on GitHub
Settings → Secrets and variables → Actions
Add a new secret:
- Name: MATCH_GIT_PRIVATE_KEY
- Value: Copy the entire content of ~/.ssh/github_actions_match (the private key file)

4. Update your Match repository URL

In your Matchfile, use the SSH URL instead of HTTPS:

git_url("git@github.com:yourteam/ios-certificates.git")
storage_mode("git")
type("development") # The default type, can be overridden

Or if you prefer to keep the HTTPS URL in your Matchfile, you can override it in the workflow (shown below).

Testing your setup

To verify everything is working, you can test locally first:

# This should download and install certificates without prompting
MATCH_PASSWORD="your_passphrase" bundle exec fastlane match appstore --readonly

If this works locally, it will work in CI too!

Security considerations

Now that we're dealing with certificates and sensitive information, security becomes crucial. GitHub provides a feature called "Secrets" where you can store sensitive information encrypted. Never commit certificates, private keys, or passphrases directly to your repository.

We'll dive deeper into secure code signing practices in the upcoming posts, but the foundation is now in place!

What's next?

This is just the beginning! We've set up a basic workflow that builds your app on every push. In the next post, we're going to extend this to run your unit tests as well, and we'll start getting into some more advanced GitHub Actions features like caching and matrix builds.

And after that? Well, we'll get to the good stuff - automatically triggering TestFlight builds when you tag your branch with "testflight". But we need to walk before we can run!

Conclusion

Setting up GitHub Actions for iOS might seem daunting at first, but it's really just writing some YAML files and leveraging the Fastlane knowledge you already have. The beauty of this approach is that you're not learning an entirely new tool - you're just running your existing Fastlane scripts in the cloud.

Give this a try, and let me know how it goes! And if you run into any issues, don't worry - we've all been there. The GitHub Actions logs are usually pretty helpful in figuring out what went wrong.

Next up: running your unit tests with GitHub Actions! 🚀

Terminal Productivity for iOS Devs: Aliases, Scripts & Tips

NoamIfergan@gmail.com — Tue, 03 Jun 2025 00:00:00 GMT

Introduction

As iOS developers, we spend a significant amount of time in the terminal - whether it's running builds, managing simulators, or navigating between projects. Yet most of us are still typing the same long commands over and over again. What if I told you that with just a few simple terminal customizations, you could cut your daily command typing by 80% and automate the most tedious parts of iOS development?

In this post, I'll share my personal terminal setup that I've refined over years of iOS development. These aren't just theoretical productivity hacks - these are the actual aliases, functions, and scripts I use every single day. By the end of this post, you'll have a toolkit that will make your fellow developers wonder how you work so fast.

Let's dive in!

Essential iOS Development Aliases

Let's start with the basics - aliases that replace those long, hard-to-remember commands with short, memorable ones. Add these to your ~/.zshrc or ~/.bash_profile:

# Xcode and iOS Development
alias xc='open *.xcworkspace || open *.xcodeproj'
alias xcclean='rm -rf ~/Library/Developer/Xcode/DerivedData'
alias xcdevices='xcrun simctl list devices'
alias xcboot='xcrun simctl boot'
alias xcshutdown='xcrun simctl shutdown all'
alias xcreset='xcrun simctl erase all'

# Build shortcuts
alias build='xcodebuild -workspace *.xcworkspace -scheme'
alias buildclean='xcodebuild clean -workspace *.xcworkspace -scheme'
alias archive='xcodebuild archive -workspace *.xcworkspace -scheme'

# Fastlane shortcuts (if you use Fastlane)
alias fl='fastlane'
alias fltest='fastlane test'
alias flbuild='fastlane build'

# CocoaPods shortcuts
alias pod='bundle exec pod'
alias podup='bundle exec pod update'
alias podclean='bundle exec pod deintegrate && bundle exec pod install'

# Git shortcuts for iOS
alias gitclean='git clean -xfd && git reset --hard HEAD'
alias gitignore='curl -o .gitignore https://www.toptal.com/developers/gitignore/api/swift,xcode,cocoapods'

These aliases alone will save you hundreds of keystrokes per day. But we're just getting started - this is where things get really interesting.

Powerful Terminal Functions

Aliases are great for simple commands, but functions let you create more sophisticated automation. Here are my favorite iOS development functions that I honestly can't live without:

Quick Project Setup

# Create a new iOS project structure with common files
ios_project_setup() {
    if [ -z "$1" ]; then
        echo "Usage: ios_project_setup <project_name>"
        return 1
    fi
    
    mkdir "$1"
    cd "$1"
    
    # Create basic directory structure
    mkdir -p Scripts Documentation Assets
    
    # Download .gitignore
    curl -s -o .gitignore https://www.toptal.com/developers/gitignore/api/swift,xcode,cocoapods
    
    # Create README
    echo "# $1" > README.md
    echo "" >> README.md
    echo "## Setup" >> README.md
    echo "" >> README.md
    echo "\`\`\`bash" >> README.md
    echo "bundle install" >> README.md
    echo "bundle exec pod install" >> README.md
    echo "\`\`\`" >> README.md
    
    # Create Gemfile for Fastlane
    echo "source 'https://rubygems.org'" > Gemfile
    echo "" >> Gemfile
    echo "gem 'fastlane'" >> Gemfile
    echo "gem 'cocoapods'" >> Gemfile
    
    echo "✅ Project $1 setup complete!"
}

Smart Simulator Management

# Boot the most recent iOS simulator
boot_latest_sim() {
    local device_id=$(xcrun simctl list devices available | grep "iPhone" | tail -1 | grep -o "([A-F0-9-]*)" | tr -d "()")
    if [ -n "$device_id" ]; then
        xcrun simctl boot "$device_id"
        echo "✅ Booted simulator: $device_id"
    else
        echo "❌ No available iPhone simulators found"
    fi
}

# Install app on all booted simulators
install_on_all_sims() {
    if [ -z "$1" ]; then
        echo "Usage: install_on_all_sims <path_to_app>"
        return 1
    fi
    
    local app_path="$1"
    xcrun simctl list devices | grep "Booted" | while read -r line; do
        local device_id=$(echo "$line" | grep -o "([A-F0-9-]*)" | tr -d "()")
        if [ -n "$device_id" ]; then
            xcrun simctl install "$device_id" "$app_path"
            echo "✅ Installed on $device_id"
        fi
    done
}

Let me break down what these functions do, because the simulator management commands can be a bit cryptic:

- `boot_latest_sim()`: This grabs the latest iPhone simulator from your available devices and boots it up. No more manually opening Simulator.app and clicking through menus!
- `install_on_all_sims()`: Ever wanted to test your app on multiple simulator sizes at once? This installs your .app bundle on every currently running simulator. Super handy for screenshot automation or testing across different screen sizes.

Build Log Analysis

# Parse Xcode build logs for errors and warnings
analyze_build_log() {
    if [ -z "$1" ]; then
        echo "Usage: analyze_build_log <log_file>"
        return 1
    fi
    
    echo "🔍 Analyzing build log: $1"
    echo ""
    
    echo "❌ ERRORS:"
    grep -n "error:" "$1" | head -10
    echo ""
    
    echo "⚠️  WARNINGS:"
    grep -n "warning:" "$1" | head -10
    echo ""
    
    echo "📊 SUMMARY:"
    echo "Errors: $(grep -c "error:" "$1")"
    echo "Warnings: $(grep -c "warning:" "$1")"
}

Project Navigation Scripts

One thing that drives me crazy is navigating between multiple iOS projects. You know the drill - you're working on three different apps, each in a different folder, and you spend half your time just cd-ing around trying to remember where everything is. Here's how I solved it:

Quick Project Switcher

# Add this to your shell config
export IOS_PROJECTS_DIR="$HOME/Developer/iOS"

# Quick project navigation
ios_project() {
    if [ -z "$1" ]; then
        echo "Available projects:"
        ls -1 "$IOS_PROJECTS_DIR" | grep -v ".DS_Store"
        return 0
    fi
    
    local project_path="$IOS_PROJECTS_DIR/$1"
    if [ -d "$project_path" ]; then
        cd "$project_path"
        # Automatically open in Xcode if requested
        if [ "$2" = "open" ]; then
            xc
        fi
    else
        echo "❌ Project '$1' not found in $IOS_PROJECTS_DIR"
    fi
}

# Add tab completion for projects
_ios_project() {
    local projects=($(ls -1 "$IOS_PROJECTS_DIR" 2>/dev/null | grep -v ".DS_Store"))
    compadd -a projects
}
compdef _ios_project ios_project

Now you can type ios_project MyApp to instantly navigate to your project, or ios_project MyApp open to navigate and open in Xcode.

Advanced Automation Scripts

Automated Testing Script with Notifications

# Run tests and send notification when complete
test_and_notify() {
    local scheme="${1:-$(basename $(pwd))}"
    local start_time=$(date +%s)
    
    echo "🧪 Running tests for scheme: $scheme"
    
    if fastlane test scheme:"$scheme"; then
        local end_time=$(date +%s)
        local duration=$((end_time - start_time))
        osascript -e "display notification \"Tests passed in ${duration}s\" with title \"✅ $scheme\""
        echo "✅ Tests passed in ${duration}s"
    else
        osascript -e "display notification \"Tests failed\" with title \"❌ $scheme\""
        echo "❌ Tests failed"
        return 1
    fi
}

This one is a game-changer. How many times have you started a test run, then switched to Slack or Twitter while waiting, only to completely forget about it? This function runs your tests and sends you a macOS notification when they're done. You can even see how long they took right in the notification. No more wondering if your tests are still running or if they finished 10 minutes ago!

Dependency Update Checker

# Check for outdated dependencies
check_dependencies() {
    echo "🔍 Checking for outdated dependencies..."
    echo ""
    
    if [ -f "Podfile" ]; then
        echo "📦 CocoaPods:"
        bundle exec pod outdated
        echo ""
    fi
    
    if [ -f "Package.swift" ]; then
        echo "📦 Swift Package Manager:"
        swift package show-dependencies --format json | jq -r '.dependencies[] | "\(.identity): \(.requirement)"'
        echo ""
    fi
    
    if [ -f "Gemfile" ]; then
        echo "💎 Ruby Gems:"
        bundle outdated
    fi
}

Setting Up Your Terminal for Maximum Productivity

To make the most of these scripts, here's how to set up your terminal:

1. Install Essential Tools

# Install Homebrew if you haven't already
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install essential tools
brew install jq tree bat fzf ripgrep

2. Add to Your Shell Config

Add all the aliases and functions above to your ~/.zshrc (if using zsh) or ~/.bash_profile (if using bash):

# Edit your shell config
nano ~/.zshrc

# Reload your config
source ~/.zshrc

3. Create a Scripts Directory

# Create a dedicated directory for your iOS scripts
mkdir -p ~/Scripts/iOS
echo 'export PATH="$PATH:$HOME/Scripts/iOS"' >> ~/.zshrc

Pro Tips for Terminal Efficiency

Use fzf for fuzzy finding: Install fzf to quickly search through your command history and file system.
Set up tab completion: The project switcher above includes tab completion - use this pattern for your other functions too.
Create keyboard shortcuts: Map frequently used commands to keyboard shortcuts in your terminal app.
Use bat instead of cat: It provides syntax highlighting and line numbers.
Leverage tree for project structure: Quickly visualize your project structure with tree -I 'Pods|DerivedData'.

Bonus: Supercharge Your Terminal with Powerlevel10k

Now that we've covered all the functional aspects of terminal productivity, let's talk about making your terminal not just powerful, but beautiful and informative too. I use Powerlevel10k (p10k), which is hands down the best Zsh theme I've ever used.

Seriously, I've tried probably a dozen different themes over the years, and nothing comes close to p10k. It's fast, it's gorgeous, and it shows you exactly the information you need without being cluttered.

What is Powerlevel10k?

Powerlevel10k is a theme for Zsh that provides:

Lightning fast prompt rendering (100x faster than other themes)
Rich information at a glance - Git status, current directory, execution time, etc.
Highly customizable - configure it exactly how you want
iOS-specific info - Show Swift version, Xcode version, and more

Installation

# Install Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc

# Restart your terminal and run the configuration wizard
p10k configure

My iOS Developer Configuration

Here's how I configure p10k for maximum iOS development productivity:

# Add these to your ~/.p10k.zsh file after running p10k configure

# Show Swift version when in Swift projects
typeset -g POWERLEVEL9K_SWIFT_SHOW_ON_COMMAND='swift|xcodebuild|fastlane'

# Show Ruby version (for Fastlane/CocoaPods)
typeset -g POWERLEVEL9K_RBENV_SHOW_ON_COMMAND='bundle|pod|fastlane|gem'

# Show Node version (for React Native or web stuff)
typeset -g POWERLEVEL9K_NODE_VERSION_SHOW_ON_COMMAND='node|npm|yarn|react-native'

# Customize the prompt elements (left side)
typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(
  dir                     # Current directory
  vcs                     # Git status
  swift_version           # Swift version
  rbenv                   # Ruby version (for Fastlane)
  command_execution_time  # How long the last command took
  newline                 # Line break
  prompt_char             # The prompt character
)

# Customize the right side
typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(
  status                  # Exit code of last command
  background_jobs         # Background jobs indicator
  time                    # Current time
)

# Show execution time for commands longer than 3 seconds
typeset -g POWERLEVEL9K_COMMAND_EXECUTION_TIME_THRESHOLD=3

# Git status customization
typeset -g POWERLEVEL9K_VCS_CLEAN_FOREGROUND=76
typeset -g POWERLEVEL9K_VCS_MODIFIED_FOREGROUND=178
typeset -g POWERLEVEL9K_VCS_UNTRACKED_FOREGROUND=014

Why This Matters for iOS Development

With p10k configured like this, your terminal instantly shows you:

Git status - See if you have uncommitted changes at a glance
Swift version - Know which Swift version you're using when switching between projects
Ruby version - Important for Fastlane and CocoaPods compatibility
Command execution time - See how long your builds or tests took
Current directory - Never get lost in your project structure

Pro p10k Tips

Instant prompt: p10k has an "instant prompt" feature that shows your prompt immediately, even before zsh fully loads. Enable it with:
```
echo 'typeset -g POWERLEVEL9K_INSTANT_PROMPT=verbose' >>~/.p10k.zsh
```
Transient prompt: Makes your command history cleaner by simplifying past prompts:
```
echo 'typeset -g POWERLEVEL9K_TRANSIENT_PROMPT=always' >>~/.p10k.zsh
```

Custom segments: You can create custom segments. Here's one that shows if you're in an iOS project:

# Add to ~/.p10k.zsh
function prompt_ios_project() {
  if [[ -n *.xcworkspace(#qN) || -n *.xcodeproj(#qN) ]]; then
    p10k segment -f 208 -t "📱"
  fi
}

# Add ios_project to your POWERLEVEL9K_LEFT_PROMPT_ELEMENTS

The result is a terminal that's not just functional, but gives you crucial information at a glance. When you're juggling multiple iOS projects with different Swift versions, Ruby versions, and Git states, this visual feedback is invaluable.

Trust me, once you get used to seeing all this information in your prompt, you'll never want to go back to a boring terminal again. It's like having a dashboard for your development environment!

Conclusion

These terminal customizations have literally saved me hours every week. I'm not exaggerating - when you add up all the time saved from not typing long commands, not having to remember complex xcodebuild syntax, and getting instant visual feedback about your project state, it really adds up.

The beauty is that you can start small - pick a few aliases that solve your biggest pain points, then gradually add more as you discover new needs. I didn't build this setup overnight; it evolved over years of "ugh, I'm tired of typing this same command again."

The key is to pay attention to the commands you type repeatedly and ask yourself: "Could I automate this?" More often than not, the answer is yes, and it only takes a few minutes to set up.

Start with the aliases and basic functions, then gradually build up your toolkit. Your future self (and your wrists) will thank you!

What terminal shortcuts do you swear by? I'd love to hear about your productivity hacks! Hit me up on Twitter and let me know what I should cover next.

Use Git Hooks in iOS Projects (Without CI)

NoamIfergan@gmail.com — Wed, 07 May 2025 00:00:00 GMT

Introduction

In this blog, we talk a lot about Continuous Integration (CI) and how it can help you to automate your development process. But what if you don't want to set up a CI server? What if you just want to run some scripts before you commit your code? That's where Git hooks come in. Git hooks are scripts that run automatically at certain points in the Git workflow. They can be used to enforce coding standards, run tests, or even send notifications. In this blog post, I'll show you my favorite Git hooks that I use in my iOS projects. You can use them to make your life easier without a CI server. Let's get started!

Pre-commit Hook

The pre-commit hook is run before a commit is made. This is a great place to run tests or check for coding standards.
I use mine to run SwiftLint and SwiftFormat to check for coding standards and format my code. Here's how I set it up:

#!/bin/bash
# Pre-commit hook to run SwiftLint and SwiftFormat
# Check if SwiftLint is installed, if it's not - install it.
if ! command -v swiftlint &> /dev/null
then
    echo "SwiftLint could not be found, installing..."
    brew install swiftlint
fi
# Check if SwiftFormat is installed, if it's not - install it.
if ! command -v swiftformat &> /dev/null
then
    echo "SwiftFormat could not be found, installing..."
    brew install swiftformat
fi
# Run SwiftFormat first, as it might fix the linting issues
swiftformat .
# Run SwiftLint
swiftlint
# Check the exit code of SwiftLint
if [ $? -ne 0 ]; then
    echo "SwiftLint failed, please fix the issues before committing."
    exit 1
fi
echo "SwiftLint passed, ready to commit!"

Let's break it down a bit, as you might not be familiar with all the commands or with bash scripts:

command -v swiftlint &> /dev/null: This checks if swiftlint is installed. If it's not, it installs it using Homebrew.
swiftformat .: This runs SwiftFormat on the current directory. It will format your code according to the rules you have set up.
swiftlint: This runs SwiftLint on your code. If there are any issues, it will return a non-zero exit code.
if [ $? -ne 0 ]; then ...: This checks the exit code of the last command. If it's not zero, it means there were issues with SwiftLint, and we exit with a non-zero code to prevent the commit.
echo "SwiftLint passed, ready to commit!": If everything went well, we print a success message.

Pre-push Hook

The pre-push hook is run before you push your code to the remote repository. This is a great place to run tests or do some heavier things that you don't want to run on every commit but still want checked, such as unit tests or integration tests.
I use mine to run my unit tests before I push my code, using Fastlane. Here's how I set it up:

#!/bin/bash
# Pre-push hook to run unit tests
# Check if Fastlane is installed, if it's not - install it.
if ! command -v fastlane &> /dev/null
then
    echo "Fastlane could not be found, installing..."
    gem install fastlane
fi
# Run Fastlane
fastlane test
# Check the exit code of Fastlane
if [ $? -ne 0 ]; then
    echo "Unit tests failed, please fix the issues before pushing."
    exit 1
fi
echo "Unit tests passed, ready to push!"

Again, let's break it down a bit:

command -v fastlane &> /dev/null: This checks if fastlane is installed. If it's not, it installs it using RubyGems.
fastlane test: This runs the test lane in your Fastlane setup. You can customize this to run any tests you want, or any lane that you'd like.

Adding the Hooks to Your Project

To add the hooks to your project, you need to create a directory called hooks in your .git directory. Inside this directory, create two files: pre-commit and pre-push. Make sure to make them executable:

chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push

Now, every time you commit or push your code, the hooks will run automatically. You can customize them to fit your needs.

Conclusion

These might seem like small things, but they can save you a lot of time and headaches in the long run. By using Git hooks, you can automate your workflow and make sure that your code is always in a good state before you commit or push it. I hope you found this blog post helpful! If you have any questions or suggestions, feel free to reach out to me on Twitter or leave a comment below.

Parallelize iOS Unit Tests with Fastlane or CLI

NoamIfergan@gmail.com — Thu, 24 Apr 2025 00:00:00 GMT

Introduction

In this post, I'll show you two ways to run unit tests in your iOS app: using the Xcode CLI with Bash and using Fastlane. Both approaches have their pros and cons, and you can choose the one that best fits your workflow. Whether you're working in a CI/CD environment or running tests locally, these methods will help you automate your testing process.

Prerequisites

For both methods, you'll need:

Xcode installed
A working iOS app with unit tests

For the Fastlane method, you'll also need:

Fastlane installed

Method 1: Using Xcode CLI and Bash

This method uses the Xcode CLI (xcodebuild) and a Bash script to run your tests. It's lightweight and doesn't require any third-party tools.

Script

Here's the script to run your unit tests:

#!/bin/bash

set -u  # Treat unset variables as errors

# Configurable variables
SCHEME="YourSchemeName"
DESTINATION="platform=iOS Simulator,name=iPhone 16 Pro,OS=latest"
PROJECT="YourProject.xcodeproj"

# Run tests and capture exit code
set -o pipefail
xcodebuild \
-scheme "$SCHEME" \
-project "$PROJECT" \
-destination "$DESTINATION" \
-parallel-testing-enabled YES \
-parallel-testing-worker-count 4 \
clean test | tee xcodebuild.log | xcpretty

EXIT_CODE=${PIPESTATUS[0]}

if [ "$EXIT_CODE" -ne 0 ]; then
    echo "❌ Unit tests failed!"
    exit "$EXIT_CODE"
else
    echo "✅ All unit tests passed!"
fi

Running the Script

Save the script to a file (e.g., run_tests.sh), make it executable, and run it:

chmod +x run_tests.sh
./run_tests.sh

This will run your tests and display the results in the terminal.

Method 2: Using Fastlane

Fastlane is a popular tool for automating iOS and Android development tasks. It provides a simple way to run tests and integrates well with CI/CD pipelines.

Setting Up Fastlane

Install Fastlane:
```
brew install fastlane
```
Navigate to your project directory and initialize Fastlane:
```
fastlane init
```
Follow the prompts to set up Fastlane for your project.

Adding a Test Lane

Edit your Fastfile to add a lane for running tests:

default_platform(:ios)

platform :ios do
  desc "Run unit tests"
  lane :run_tests do
    scan(
      scheme: "YourSchemeName",
      devices: ["iPhone 16 Pro"],
      clean: true,
      parallel_testing: true,
      concurrent_workers: 4,
      output_directory: "./fastlane/test_output",
      output_types: "html,junit"
    )
  end
end

Running the Test Lane

Run the test lane using the following command:

fastlane run_tests

Fastlane will execute your tests and generate a report in the ./fastlane/test_output directory.

Comparison: Xcode CLI vs. Fastlane

Feature	Xcode CLI + Bash	Fastlane
Setup	Minimal	Requires Fastlane setup
Ease of Use	Requires scripting	Simple, declarative syntax
Output	Customizable with `xcpretty`	Built-in reports (HTML, JUnit)
CI/CD Integration	Manual	Seamless
Flexibility	High	High

Conclusion

Both methods are effective for running unit tests in your iOS app. If you prefer a lightweight, script-based approach, the Xcode CLI with Bash is a great choice. If you want a more feature-rich solution with built-in reporting and CI/CD integration, Fastlane is the way to go.

Try both methods and see which one works best for your workflow. Let me know if you have any questions or need help setting up either approach. Happy testing!

Run iOS Unit Tests on CI Without Fastlane

NoamIfergan@gmail.com — Tue, 15 Apr 2025 00:00:00 GMT

Introduction

In this post, I'm going to show you how to run unit tests in your iOS app using the Xcode CLI and Bash. This is a great way to run your tests without having to rely on Fastlane or any other third-party tools. It's also a good way to get familiar with the Xcode CLI and how it works.
You'd want to do this when you have a CI provider that doesn't have Ruby for some reason, can't install Fastlane, or just because you want to learn how to do it yourself.

Prerequisites

Xcode installed
Xcode CLI tools installed (if you've got Xcode, you've got these)
xcpretty installed (optional, but recommended for pretty output)
A working iOS app with unit tests

Setup

You need to know the names of your project and schemes. You can find this out by opening your project in Xcode and looking at the top-left corner of the window. The project name is the name of the file with the .xcodeproj extension, and the scheme is the name of the scheme you want to run tests for. For this example, we'll use MyApp.xcodeproj and MyAppTests as the scheme name.

#!/bin/bash

set -u  # Only treat unset variables as errors

# Configurable variables
SCHEME="YourSchemeName"
DESTINATION="platform=iOS Simulator,name=iPhone 16 Pro,OS=latest"
PROJECT="YourProject.xcodeproj"

Run tests

We're going to use xcodebuild to run the tests. This is the command that Xcode uses under the hood to build and run your app. The command looks like this:

#!/bin/bash

set -u  # Only treat unset variables as errors

# Configurable variables
SCHEME="YourSchemeName"
DESTINATION="platform=iOS Simulator,name=iPhone 16 Pro,OS=latest"
PROJECT="YourProject.xcodeproj"

# Run tests and capture exit code
set -o pipefail
xcodebuild test \
-scheme "$SCHEME" \
-project "$PROJECT" \
-destination "$DESTINATION" \
clean test | tee xcodebuild.log | xcpretty

EXIT_CODE=${PIPESTATUS[0]}

if [ "$EXIT_CODE" -ne 0 ]; then
    echo "❌ Unit tests failed!"
    exit "$EXIT_CODE"
else
    echo "✅ All unit tests passed!"
fi

Explanation

Ok, let's break this down a bit, as it can be quite scary to look at, especially if you're not used to the command line.

set -u: This tells Bash to treat unset variables as errors. This is a good practice to avoid bugs in your scripts.
SCHEME, DESTINATION, and PROJECT: These are the variables that you can configure to match your project. You can change these to match your project name, scheme name, and destination.
set -o pipefail: This tells Bash to return the exit code of the last command in the pipeline that failed. This is useful for capturing the exit code of xcodebuild and checking if the tests passed or failed.
xcodebuild test: This is the command that runs the tests. It takes the scheme, project, and destination as arguments.
| tee xcodebuild.log: This pipes the output of xcodebuild to a file called xcodebuild.log and also prints it to the console. This is useful for debugging and checking the output of the tests.
| xcpretty: This pipes the output of xcodebuild to xcpretty, which formats the output to be more readable. This is optional, but recommended for better output.
EXIT_CODE=${PIPESTATUS[0]}: This captures the exit code of the xcodebuild command. If the tests fail, this will be a non-zero value.
if [ "$EXIT_CODE" -ne 0 ]; then: This checks if the exit code is not equal to 0. If it is not, it means the tests failed.
echo "❌ Unit tests failed!": This prints a message to the console if the tests failed.
exit "$EXIT_CODE": This exits the script with the exit code of xcodebuild.
else: This is the else statement that runs if the tests pass.
echo "✅ All unit tests passed!": This prints a message to the console if the tests passed.
fi: This closes the if statement.

Running the script

To run the script, save it to a file called run_tests.sh and make it executable:

chmod +x run_tests.sh

Then, run the script:

./run_tests.sh

You should see the output of the tests in the console, and if the tests pass, you'll see a message saying "✅ All unit tests passed!". If the tests fail, you'll see a message saying "❌ Unit tests failed!" and the script will exit with a non-zero exit code.

Building on top of this

This script is the bare minimum to run unit tests in your iOS app. You can build on top of this by adding more features, such as:

Running UI tests
Running tests on a specific simulator
Running tests on a specific device
Running tests on a specific OS version
Running tests in parallel
Running tests on multiple simulators

And much more! Bash is incredibly flexible, and xcodebuild is a powerful tool that can do a lot more than just run tests. You can use it to build your app, archive it, export it, and much more. You can find more information about xcodebuild in the Xcode documentation. It's quite old, but it still has a lot of useful information.

For a list of all the available options for xcodebuild, you can have a look here, and you can always run xcodebuild -help in the terminal to see a list of all the available options.

Conclusion

In this post, we've shown you how to run unit tests in your iOS app using the Xcode CLI and Bash. This is a great way to run your tests without having to rely on Fastlane or any other third-party tools. It's also a good way to get familiar with the Xcode CLI and how it works. Let me know if you have any questions or if you want to see more examples of how to use the Xcode CLI and Bash to run tests in your iOS app. Happy testing!

Automatically Bump Version & Build Number with Fastlane

NoamIfergan@gmail.com — Thu, 10 Apr 2025 00:00:00 GMT

Introduction

We're nearing the end of our "Fastlane from zero to hero", and in this post we're going to automate just a little bit more of the housekeeping work it takes to release an app to the app store.
Increasing the version number and build number is something that we all have to do, but it's also something that we all forget to do. So let's automate it!

Pre-requisites

You should have a working Fastlane setup. If you don't, check out the previous posts in this series.
I'm going to go off of the assumption that you've got an API key, as a JSON file in your project. If this is a subject you're not familiar with, let me know, and I can write a post about it!

Build numbers

The first thing that we're going to do is compare the current build number with the one that we have in our project. This is important because we don't want to bump the build number if it's already the same as the one in the project.
We're going to be getting the latest build numbers from 3 different sources:

The latest build number from TestFlight
The latest build number from the App Store
The latest build number from the local project

Getting the latest build number from TestFlight

To get the latest build number from TestFlight, we're going to use the latest_testflight_build_number action. This action will return the latest build number for the app in TestFlight. It's a built-in action from Fastlane, so we don't need to worry about installing any additional gems, or writing the complex logic ourselves.

desc 'Compare the local build number to the latest test flight on ASC'
lane :compare_build_numbers do
  test_flight_version = latest_testflight_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i
end

This is assuming that you have a JSON file with your API key in the root of your project. If you don't, you can use the api_key parameter to pass in the key directly.

Getting the latest build number from the App Store

To get the version from App Store, we're going to use the same approach - using the built-in Fastlane actions.

desc 'Compare the local build number to the latest test flight on ASC'
lane :compare_build_numbers do
  test_flight_version = latest_testflight_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i

  live_app_version = app_store_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i
end

Getting the latest build number from the local project

Can you guess what we're going to be using? That's right - a built-in Fastlane action!

desc 'Compare the local build number to the latest test flight on ASC'
lane :compare_build_numbers do
  test_flight_version = latest_testflight_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i

  live_app_version = app_store_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i

  local_build_number = get_build_number.to_i
end

Comparing and bumping

Now that we've got all 3, we only really need 2; the local version, and which ever one of the other build numbers is highest.
So we can write a simple lane to compare the two, and bump the local version if it's lower than either of the other two.

lane :bump_build_number_if_needed do |options|
  local_build_number = options[:local_build_number]
  remote_build_number = options[:remote_build_number]

  if remote_build_number.to_i > local_build_number.to_i
    new_build_number = remote_build_number.to_i + 1
    increment_build_number(build_number: new_build_number)
  elsif remote_build_number.to_i == local_build_number.to_i
    increment_build_number
  end
end

This might look a bit scary, but let's break it down:

We take in the local and remote build numbers as parameters.
We compare the two, and if the remote build number is greater than the local build number, we increment the remote build number by 1, and set that as our build number.
If the remote build number is equal to the local build number, we just increment the local build number by 1.
If the remote build number is less than the local build number, we don't do anything ( So we don't bump when we don't need to!).

Putting it all together

Now that we've got all the pieces, we can put them together in a lane.

desc 'Compare the local build number to the latest test flight on ASC'
lane :compare_build_numbers do
  test_flight_version = latest_testflight_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i

  live_app_version = app_store_build_number(
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  ).to_i

  local_build_number = get_build_number.to_i

  bump_build_number_if_needed(
    local_build_number: local_build_number,
    remote_build_number: test_flight_version > live_app_version ? test_flight_version : live_app_version
  )
end

lane :bump_build_number_if_needed do |options|
  local_build_number = options[:local_build_number]
  remote_build_number = options[:remote_build_number]

  if remote_build_number.to_i > local_build_number.to_i
    new_build_number = remote_build_number.to_i + 1
    increment_build_number(build_number: new_build_number)
  elsif remote_build_number.to_i == local_build_number.to_i
    increment_build_number
  end
end

And that's it! Now we can run the compare_build_numbers lane, and it will automatically bump the build number if it's lower than the latest build number on TestFlight or the App Store.
This is a great way to make sure that we never forget to bump the build number again, and it saves us a lot of time in the long run. Now let's do the same, but for your version number.

Version numbers

The version number is the same approach, but is even a little bit easier, because we can use the same built in Fastlane action to get both the App Store version and the TestFlight version.

Getting remote versions

First thing we need is the remote version, which we can get using the app_store_build_number action, which returns the version in it's SharedValues. Let's see how that looks:

desc 'Compare the local version number to the live and TF ones, and bumps it if needed.'
lane :compare_version_numbers do
  app_store_build_number(
    live: true,
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  )
  live_version_number = lane_context[SharedValues::LATEST_VERSION]

  app_store_build_number(
    live: false,
    app_identifier: 'com.example.app',
    api_key_path: 'iTunesConnectKey.json'
  )
  tf_version_number = lane_context[SharedValues::LATEST_VERSION]
  tf = Gem::Version.new(tf_version_number)
  live = Gem::Version.new(live_version_number)
end

This is assuming that you have a JSON file with your API key in the root of your project. If you don't, you can use the api_key parameter to pass in the key directly.
Just to break it down a little bit:

We call the app_store_build_number action with the live parameter set to true, which will return the live version number.
We call the app_store_build_number action with the live parameter set to false, which will return the TestFlight version number.
We convert the version numbers to Gem::Version objects, which allows us to compare them easily.

Getting the local version

To get the local version, we can use the get_version_number action, which will return the version number from the Info.plist file.

lane :project_version_number do
  version_number = get_version_number(
    xcodeproj: "some_project.xcodeproj",
    target: 'SomeTarget'
  )
  version_number
end

Comparing and bumping

So just like before, now we've got 3 versions, but we really only need 2. so we can write a lane that expects 2 versions, compare them, and bump them if we need to.

lane :bump_version_number_if_needed do |options|
  local_version_str = options[:local].to_s
  remote_version_str = options[:remote].to_s
  local = Gem::Version.new(local_version_str)
  remote = Gem::Version.new(remote_version_str)
  puts "Remote version: #{remote}, local version: #{local}"

  if remote > local
    puts 'Remote is higher than local'
    increment_version_number(version_number: options[:remote])
    puts 'Bumping to remote + 1'
    increment_version_number(bump_type: 'patch')
  elsif remote == local
    increment_version_number
  elsif local > remote
    puts 'Local version is higher than remote, no need to bump'
  end
end

Once again, this may seem a bit scary, but let's break it down:

We take in the local and remote version numbers as parameters.
We convert them to Gem::Version objects, which allows us to compare them easily.
We compare the two, and if the remote version number is greater than the local version number, we increment the remote version number by 1, and set that as our version number.
If the remote version number is equal to the local version number, we just increment the local version number by 1.
If the remote version number is less than the local version number, we don't do anything ( So we don't bump when we don't need to!).

Conclusion

In this post, we've seen how to automate the process of bumping the build number and version number using Fastlane. This is a great way to make sure that we never forget to bump the build number again, and it saves us a lot of time in the long run. You can just pick and drop this code into your Fastfile, and it will work out of the box. If you have any questions, or if there's anything else you'd like to see, let me know!

How to Unit Test SwiftUI Views Without View Models

NoamIfergan@gmail.com — Mon, 31 Mar 2025 00:00:00 GMT

Introduction

The most common architecture pattern in SwiftUI is MVVM. This is a great pattern, but it can be a bit overkill for simple views. In this post, we're going to talk about how to unit test SwiftUI views without a view model. This is a great way to keep your code clean and simple, and it's also a great way to write unit tests for your views.

Reasoning

Not every view needs a view model. I know this might be a controversial statement, but hear me out. If your view is simple enough, you can just use the view itself as the model. This is especially true for views that are just displaying data and don't have any complex logic. In these cases, you can just use the view itself as the model and write your tests against it.

So if you've been writing a view with small logic, but you still want to make sure that your logic is fully covered, repeatable, and predictable, this is my way of doing it.

Static methods

This is the most obvious way to do it. You can just write a static method in your view and call it from your tests. This is a great way to keep your code clean and simple, and it's also a great way to write unit tests for your views. It also helps with forcing you to have pure functions, which is something I personally love.

Here's an example of how to do this:

The View

struct ContentView: View {
  @State private var someString = "Hello, world!"
    var body: some View {
        VStack {
            Text(someString)
          Button("reverse string") {
            someString =  Self.reverseString(someString)
          }
        }
        .padding()
    }

  static func reverseString(_ string: String) -> String {
    String(string.reversed())
  }
}

As you can see in this very important method that's clearly carrying the business logic of the app, we have a static method that reverses a string. This is a pure function, and it doesn't depend on any state. This is a great way to write unit tests for your views, and it's also a great way to keep your code clean and simple.

The Test

import Testing
@testable import SwiftUI_unit_testing

struct ContentViewTests {

@Test
  func testStringBeingReversed() {
    let baseString = "abc"
    let expectedString = "cba"
    let reversedString = ContentView.reverseString(baseString)
    #expect(reversedString == expectedString)
  }

}

Simple enough, isn't it? All we need to do is call the static method and check if the result is what we expect. This is a great way to write unit tests for your views, and it's also a great way to keep your code clean and simple. There isn't even a need to instantiate the view!

Pitfalls

Like everything else in life, there are upsides and downsides to this approach. Here are a few things to keep in mind:

Pure functions might not be the right tool: I'm a fan of using whatever tool is right for the job. Sometimes, a pure function is just not the correct tool.
State observability: If your view is using @State or @Binding, you might need to use a different approach. The updates don't show in the tests, so you could look into using UI tests to cover this.
Lack of context: SwiftUI views are just that - views. They're visual components, and while we can test the logic, we can't test the visual aspect of it. For that, you might want to look into snapshot testing or UI testing.

Conclusion

In this short post, we've discussed how to unit test SwiftUI views without a view model. As you can see, like anything else, it's a decision and you should be mindful when you make it. Sometimes, a view model is just not needed. Other times, it absolutely is, if you want to test side effects of methods, different states, and so on. This should just be yet another tool in your belt. Don't fall into the tribalism of "MVVM is the only way" or "MV is the only way." Use the right tool for the job, and you'll be fine.

Run iOS Unit Tests Automatically with Fastlane

NoamIfergan@gmail.com — Tue, 25 Mar 2025 00:00:00 GMT

Introduction

In our latest post, we spoke about how to build your app with Fastlane. In this post, we're going to talk about how to run your unit tests with Fastlane. But firstly, why would we even want to do this?

Reasoning

Unit tests are important, we all agree on that. Also, we all write unit tests (right?), but if we don't run them - they're meaningless.
While manually running them is fine, it's not the most efficient way to do it. We can automate this process with Fastlane, and have it run every time we push to our CI, or every time we want to run our tests.

Pre-requisites

I'm assuming you've already got Fastlane installed. If you don't, you can follow this quick guide.
Also, I'm going to assume you've got some unit tests in your project. If you don't, you should probably write some.

Setting up

We're going to be building off of the Fastlane file in the previous post, which at the moment looks like this:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release", export_method: "app-store", output_directory: "./build")
  end

end

If you need a refresher about what's going on, you can read the post here, but a quick summary is that we're building our app with Fastlane and exporting it in a file that is ready to be shipped to the App Store.

Explaining the tool

We're going to be using the scan tool that comes with Fastlane. This tool is used to run your tests, and it's very easy to use. You can read more about it here. It's a great tool to have in your belt, and it's very easy to use. Let's go over a few of the flags that we're going to be using:

`scheme`

This is the scheme that you want to run your tests on. If you've got multiple schemes, you can specify which one you want to run your tests on. This is very useful if you've got different schemes for different environments, or if you've got different schemes for different parts of your app.

`clean`

This flag is used to clean the build folder before running the tests. This is useful if you want to make sure that you're running your tests on a clean slate, and that there's no leftover files from previous builds.

`devices`

This flag is used to specify which devices you want to run your tests on. This is useful if you've got different devices that you want to run your tests on, or if you want to run your tests on a specific device. This is useful if you've got snapshot tests that are per-device, for example.

Writing the lane

We're going to add a new lane to our Fastfile, called test. This lane is going to run our tests, and it's going to look like this:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release", export_method: "app-store", output_directory: "./build")
  end

  desc "Run the tests"
  lane :test do
    scan(scheme: "MyApp", clean: true, devices: ["iPhone 12 Pro Max"])
  end

end

Explanation

In this lane, we're running our tests on the scheme MyApp, cleaning the build folder before running the tests, and running the tests on the device iPhone 12 Pro Max. You can change the scheme, the devices, and any other flags that you want to use, to suit your needs. This will also produce a results file called report.junit in the ./fastlane/test_output directory, which you can use to visualize the test results.

Running the tests

Now that we've got our lane set up, we can run our tests by running bundle exec fastlane test in our project directory. This will run our tests on the specified scheme, clean the build folder before running the tests, and run the tests on the specified device.

Conclusion

And that's it! You've now got your tests running with Fastlane. This is a great way to automate your testing and increase your confidence in your code. You can read more about the scan tool here. In the next post, we're going to talk about how to run UI tests with Fastlane. Stay tuned! 🚀

How to Build an iOS App with Fastlane (Step-by-Step)

NoamIfergan@gmail.com — Wed, 19 Mar 2025 00:00:00 GMT

Introduction

Last week we discussed how to setup Fastlane. This week we're going to be doing the first step in many workflows, building the app.
Building the app is what you're used to doing in Xcode, by pressing Command + R or Command + B, but when we're talking about building the app from the command line, with whatever configuration we want, we're talking about Fastlane.

The Fastfile

This will be the first time in this series that we're going to be looking at the Fastfile. The Fastfile is the file that contains all the lanes that you can run. A lane is a set of commands that you can run.
We have had one before, when we looked into auto-bumping SPM versions, but we're going to start from scratch here.

Let's start with the basics:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

This is the basic setup of a Fastfile. We're setting the fastlane version and the default platform. We're also specifying that we're going to be working with iOS. Any new lanes or commands that we add will be added below this.
Like we mentioned before, we can also import any other Fastfiles we have, but we're not going to do that here. Let's keep it nice and simple!

Building the app

We're going to be using the incredibly powerful gym action to build the app. This action is going to build the app and create an .ipa file that we can use to distribute the app.

  desc "Build the app"
  lane :build do
    gym
  end

This will just do the bare minimum, and if you run it you might actually see a failure because some things are not set up, or more importantly, this will still require your input when run, which is not something we want when we're writing automations.
We want these lanes to be able to run entirely on their own, either on our machine, or on a CI/CD provider (foreshadowing?!).
The complete list of parameters is available here, but we're going to be looking at a few of them here.

The `scheme` parameter

This is the name of the scheme that you want to build. This is the same as the scheme you would select in Xcode when you're building the app.

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp")
  end

The `configuration` parameter

This is the configuration that you want to build the app with. This is the same as the configuration you would select in Xcode when you're building the app. The default value is Release

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release")
  end

The `export_method` parameter

This is the method that you want to use to export the app. This is the same as the method you would select in Xcode when you're exporting the app. For most iOS apps, if you plan on later on submitting to TestFlight or the app store, you would use app-store.
If you're building an SPM package, you'd use package. The options available are: app-store, validation, ad-hoc, package, enterprise, development, developer-id and mac-application

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release", export_method: "app-store")
  end

The `output_directory` parameter

This is the directory where the .ipa file will be saved. The default value is ./output

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release", export_method: "app-store", output_directory: "./build")
  end

The complete Fastfile

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'

default_platform :ios
platform :ios do

  desc "Build the app"
  lane :build do
    gym(scheme: "MyApp", configuration: "Release", export_method: "app-store", output_directory: "./build")
  end

end

## Conclusion

This is it! This is the complete Fastfile that will build your app. You can run this lane by running bundle exec fastlane build in the terminal. This will build the app, and save the .ipa file in the ./build directory.
That is the first step in so many of the automation steps that we're going to be looking into in the future, and we will be doing a lot of customization to this lane in the future.
Let me know if you have any questions, or if you want me to cover anything in particular in the future. I'm always looking for new ideas!

Intro to Fastlane for iOS – How to Start Right

NoamIfergan@gmail.com — Mon, 10 Mar 2025 00:00:00 GMT

Introduction

In our last post we spoke about why we should go with Fastlane for iOS. In this post, we will talk about how to get started with Fastlane.
I think it's important to note that Fastlane is a great tool for you to use, regardless of if you're using it for a big company project or a small indie app. It's a great tool to have in your belt.

Pre-requisites

There are a few things that you need to have before you can start. Firstly, we need to make sure we've got Ruby installed on our machine. This isn't a very difficult thing to do, and the way recommended by Fastlane in their docs is rbenv.

Secondly, you need, of course, the Xcode toolchain installed. If you've got Xcode installed, you're good to go. If you don't, then you're reading the wrong blog post.

And last but not least, is to actually install Fastlane itself. You can install it with Homebrew, but that means it's installed on your machine, so if you want it to run on some sort of a CI (Foreshadowing!?) you might want to install it with Bundler.

Installation

Installing Fastlane with Bundler is as easy as running gem install bundler, followed by bundle init in your project directory, and then adding gem 'fastlane' to your Gemfile. After that, you can run bundle install and you're good to go.

When you finish, your Gemfile should look something like this:

# frozen_string_literal: true

source "https://rubygems.org"

gem "fastlane"

Getting started

Now that you've got Fastlane installed, you can run bundle exec fastlane init in your project directory. This will create a fastlane directory in your project, with a Fastfile in it. This is where you will write your Fastlane lanes. The prefix bundle exec is important, as it makes sure that you're running the Fastlane version that you've installed with Bundler.

When prompted by Fastlane to choose what usage you need, select 4, as we're going to customize our Fastlane lanes, and do our setup manually.

Conclusion

And that's it! You've now got Fastlane installed on your machine, and you've got a Fastfile in your project.
This was a bit of a shorter post, but I think it's important to get the basics out of the way before we dive into the more complex stuff. You can read more about the setup on Fastlane's docs.
In the next post, we're going to talk about how to write your first Fastlane lane, and what you can do with it. Stay tuned! 🚀

Intro to Fastlane for iOS – Why It Matters

NoamIfergan@gmail.com — Mon, 03 Mar 2025 00:00:00 GMT

Introduction

I'm sure you've heard about Fastlane by now. If you haven't, this will be a very weird blogpost for you.
It's the industry standard for automating iOS development tasks. It's a collection of tools that help you automate the most tedious tasks in iOS development. And it's a personal favorite of mine.

However, just because you've heard of it, doesn't mean that you feel comfortable using it. Learning a new thing is daunting, and Fastlane is, for now at least, written in syntax that might be new to you as well - Ruby.

But fear not! In the following few weeks, we're going to go from zero to hero when it comes to Fastlane, and automate all the things!

But first, why would we even want to ?

Why Automate?

Consistency

Humans are not good at doing the same thing over and over again. We get bored, we get tired, we get distracted. And when we do, we make mistakes. And mistakes are bad. They can lead to bugs, crashes, and even worse, security vulnerabilities.

Also, when you have a team of developers, you want them to work in the same way. You want them to follow the same steps, to use the same tools, to have the same environment. This is crucial for the maintainability of your codebase.

Lastly, and perhaps even more importantly, there are some tasks that are just too boring to do manually. You don't want to spend your time doing things that a computer can do for you. You want to spend your time writing code, solving problems, and creating value.

Speed

Computers are fast. They can do things in milliseconds that would take you hours. And they can do them 24/7. So why not let them?

By automating the bumping of the version of your SPM package, you can save yourself a few minutes every time you release a new version. By automating the generation of screenshots for the App Store, you can save yourself a few hours every time you release a new app.

Laziness

I'm a lazy person. I don't like doing things that I don't have to do. And I'm sure you are too. So let the computer do the boring stuff for you, and you can focus on the fun stuff.

Why Fastlane?

It's the best

Fastlane is the best tool for automating iOS development tasks. It's used by thousands of developers around the world, and it's the de facto standard for automating iOS development tasks. It is absolutely the industry standard, and regardless of which company you work for, and whatever CI/CD provider they use, you will find Fastlane there.

It's constantly updated

Fastlane is constantly updated with new features, bug fixes, and improvements. It's maintained by a team of dedicated developers who are always looking for ways to make it better. And it's open source, so you can contribute to it as well!
But what that means for us, is that we don't need to worry about it going the way that Cocoapods did, and we don't have to worry that the new Xcode version will brick it. And if it does, you can count on their incredible support to fix it.

It's easy to use

Syntax is a matter of opinion, and I'm sure that some of you will disagree with me on this one, but I find Fastlane's syntax to be very easy to use. It's very readable, and it's very easy to understand what's going on. And if you don't understand something, you can always look it up in the documentation.
The Ruby syntax is very human readable to me, and with very minimal setup you can have VSCode be very helpful in your Fastlane journey.

But even nicer than that, it has everything you would ever need when just starting out already built into it. Do you need to run your tests? use scan .do you need to manage certificates? there's match. Do you need to upload your app to TestFlight? there's pilot. Do you need to upload your app to the App Store? there's deliver. And so on, and so on. You don't need to write it all from scratch!

Conclusion

So, in conclusion, we're going to learn Fastlane because it's the best tool for automating iOS development tasks. It's constantly updated, easy to use, and has everything you would ever need already built into it. And it's going to save you time, make your codebase more maintainable, and make your life easier. I'm excited about it! Are you? 🚀

10 Useful Fastlane Built-In Actions You Should Use

NoamIfergan@gmail.com — Mon, 17 Feb 2025 00:00:00 GMT

Introduction

We're programmers. We love writing code. But, there are always going to be some edge cases that we didn't think about, something that we didn't test against (if we test at all 😉), or some way to use our code that we didn't intend for.
Well, luckily for us, most of the time, someone else has already thought of that edge case and has written an action that probably already does what we want to do.

I'm not talking about the big known actions like scan or pilot or gym. I'm talking about the little guys, the ones that you might not have heard of, or the ones that you might not have thought to use.

The beauty about these actions is that you don't even need to have Fastlane setup in your project to use them! As long as you've got Fastlane installed on your machine, you can just use them with fastlane run <action>.

Incrementing versions

Remember when we wrote our own lane to increment SPM version numbers? Well, I'm sure you've been thinking about writing the same kind of logic for incrementing your build and app version numbers. This is something we do a lot, when we release TestFlights, when we release to the store, when we release to internal testers, etc.

Well, you'll be happy to know that Fastlane has a built-in action for those!
The first one is increment_version_number. Just running it with a simple fastlane run increment_version_number will increment version's patch (assuming you're using semantic versioning, and if you don't - you should be). You can also use it to increment the minor or major versions, or even set the version to a specific number.

The sister-action to this is increment_build_number. This one is a bit more straightforward, as it only increments the build number. You can also set the build number to a specific number, or even increment it by a specific number.

Git

This is a bit of an over-arching one, but I'm sure that if you've spent more than 5 minutes working on your own Fastlane code, you've done something like sh("git add .") or some other kind of hacky way to interact with git.
Well, there are actually built-in actions for almost all of the common git actions, so you don't need to do that anymore!

There's git_add, which allows you to add either everything, or just specific files and directories. git_commit, that allows you to commit the code you've just added, and of course, git_push, that allows you to push your code to the remote.

But there are also some other git built-in actions that you may not know about, like ones to create a pull request, or get the changelog between commits.

Some fun ones

It's not always business up in here. There are also some fun built-in actions to spice your life up a bit.
One of my all-time favorites is say, which makes the machine speak the given message out loud. This is weirdly useful for when you're running something locally, like a release or a test, and you want to do it in the background and know when it's done.
You can be an adult and have it say things like "done", but I like putting it in exceptions in my code, so when something goes wrong it says "oh no, poopoo".
It's unironically a great way to know when a background task is done.

The opposite of it is, of course, rocket! All this action does is print out an ASCII rocket. Granted, the rocket is a bit... phallic looking.
But it's a fun thing to put at the end of long lanes that you know are going to take a while, just to give you a little bit of joy at the end of it.

Summary

So these are just some of my most used built-in actions from Fastlane. There are of course more of them available, and even MORE than those if you just search for the actions on Fastlane (but those won't be "official", so might not be as battle tested).
And of course, you can always write your own Fastlane action!
Let me know if you have any favorite built-in actions, or if you've written your own!

How to Create Custom Fastlane Actions

NoamIfergan@gmail.com — Mon, 03 Feb 2025 00:00:00 GMT

Introduction

While Fastlane provides many built-in actions, sometimes you need something specific to your workflow. Custom actions let you create reusable code that integrates seamlessly with Fastlane, but also gives you the flexibility to extend Fastlane's functionality.

Basic Structure

Create a new action by running:

fastlane new_action

This will bring up the Fastlane CLI and will prompt you for some questions about your new action. In our case, we're going to create an action that bump the minor version of a given semver string. If you remember, we've used this logic here.

So we're going to call our action patch_bump. This will create a file called patch_bump_action.rb in the fastlane/actions directory. The file contains quite a lot of boilerplate and dummy code, we can remove most of it, and keep the following:

module Fastlane
  module Actions
    class PatchBumpAction < Action
      def self.run(params)
        # Add your code here
      end

      def self.description
        "Bumps the patch version of a given sem-ver string"
      end

      def self.available_options
        [
          FastlaneCore::ConfigItem.new(
            key: :version,
            description: "The version to bump",
            optional: false
          )
        ]
      end

      def self.is_supported?(platform)
        true
      end
    end
  end
end

Breakdown of the action syntax

module Fastlane is the namespace for all Fastlane actions
module Actions is the namespace for all custom actions
class PatchBumpAction is the name of the action
def self.run(params) is the method that will be called when the action is executed
def self.description is a method that returns a description of the action
def self.available_options is a method that returns an array of options that the action accepts. Each option is a FastlaneCore::ConfigItem object. The key is the name of the option, description is a description of the option, and optional is a boolean that indicates whether the option is required or not.
def self.is_supported?(platform) is a method that returns a boolean indicating whether the action is supported on the given platform.

Implementing the action

Now that we have the basic structure of the action, we can implement the logic to bump the patch version of a given semver string. How exciting! we're going to reuse the logic we've had in the previous post.

  def self.run(params)
    version = params[:version]
    version_number_array = version.split('.').map(&:to_i)
    version_number_array[-1] += 1
    version_number_array.join('.')
  end

This is a very simple implementation (and honestly? shouldn't need it's own action!), but it should give you an idea of how to implement custom actions in Fastlane.

Using the action

To use the action in your Fastfile, you can call it like this:

lane :bump_patch do
  new_version = patch_bump(version: "1.2.3")
  puts "New version: #{new_version}"
end

So this is very similar to how you would use a built-in Fastlane action. You can pass in the parameters as a hash, and the action will return the new version number. The difference is that this action can also be called as a standalone thing, outside of a Fastfile, and of course, can be tested!

Testing the action

`RSpec` setup

First we need to add RSpec to our Gemfile:

group :development do
  gem 'rspec'
end

# Add these to handle the warnings and LoadError
gem 'logger'
gem 'mutex_m'
gem 'abbrev'

Then run bundle install to install the gem.

After that, we want to add a spec helper file. Add the following to the spec_helper.rb file:

mkdir -p spec/support
touch spec/spec_helper.rb

Add the following to the spec_helper.rb file:

require 'fastlane'
require_relative '../actions/patch_bump_action'

RSpec.configure do |config|
  config.expect_with :rspec do |expectations|
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end

  config.mock_with :rspec do |mocks|
    mocks.verify_partial_doubles = true
  end

  config.shared_context_metadata_behavior = :apply_to_host_groups
end

This tells RSpec to load the Fastlane gem and our custom action before running the tests.

Writing the tests

Given how simple this action is, we can write a test for it in the spec/actions/patch_bump_action_spec.rb file:

require 'spec_helper'

describe Fastlane::Actions::PatchBumpAction do
  describe '#run' do
    it 'bumps the patch version' do
      result = Fastlane::FastFile.new.parse("lane :test do
        patch_bump(version: '1.2.3')
      end").runner.execute(:test)

      expect(result).to eq('1.2.4')
    end
  end
end

We're not going to go deeper into how to test for edge cases, but you can always find more information about that, or if you want more - ask me!

Running the tests

To run the tests, you can use the following command:

bundle exec rspec

And if everything went well, you should see something like this:

Best Practices

Remember: Custom actions live in your project's fastlane/actions/ directory. If you create something generally useful, consider turning it into a plugin!

Always validate input parameters
Use environment variables for sensitive data
Keep actions focused and single-purpose
Add proper error handling using UI.user_error!
Write tests for your actions
Document usage and parameters

Conclusion

Look at all that! You've written your first Fastlane action, and even went all 10x developer on it by adding unit tests! Well done you! 🎉
if you've got any questions, or would like to know more about Fastlane, hit me up! Thanks for reading!

Run SwiftFormat on CI: Keep iOS Code Clean

NoamIfergan@gmail.com — Mon, 20 Jan 2025 00:00:00 GMT

Introduction

In case you haven't heard of swiftformat yet, you've either been living under a rock, or just have been living your life wrong.
It's a tremendous tool to keep your codebase clean and consistent, and it's the first thing I add to any project I'm working on.
However, having it run on your machine is one thing, but having it run on your CI is a whole different ball game. The easiest way I found to get it done, is by adding a script to download it (if needed), and run it as a step in your CI provider.

Prerequisites

So there are a few small things that we need to do before we run the script. Firstly, we need to actually install SwiftFormat.
This can be done very easily using something like Homebrew, or by downloading the binary from the releases page.
I prefer the Homebrew way, as it's easier to keep up to date, and it's easier to install on a CI provider.

brew install swiftformat

Secondly, and this is an optional step, we need to have a .swiftformat.yaml file in our project. this is the file where we specify the rules we want SwiftFormat to use / ignore.
You don't have to do this, if you don't, SwiftFormat will use the default rules.
If there's interest, I can do a post explaining the rules, what they do, and how to set them up. Let me know!

Setting up the script

So we're going to use Bash to run this script. the reason we're using Bash is that it's available on almost all CI providers, and it's easy to write. Here's the script I use:

#!/bin/bash
set -e

# Function to commit changes if any Swift files were changed
commit_changes() {
    echo "SwiftFormat has performed some changes, committing them."
    # These two are optional, if you need to set specific user / email for Git. these can be stored in an environment variable,
    # or are provided by the CI provider.

    # git config user.email "${DEPLOYMENT_EMAIL}"
    # git config user.name "${DEPLOYMENT_USER}"
    git add ./\*.swift
    git commit -m "Automatic: Committing SwiftFormat changes"

    # Push changes, setting upstream if needed
    git push origin HEAD || git push --set-upstream origin HEAD
}

# Run SwiftFormat
echo "Running SwiftFormat..."
swiftformat .

# Check for changed Swift files and commit them if any
if git status --porcelain | grep -q '\.swift'; then
    echo "Changed Swift files found, preparing to commit..."
    commit_changes
else
    echo "No changes to .swift files to commit."
fi

Explanation

Bash scripts run from top to bottom, so we need to write our code accordingly. We first define the functions we're going to use, then run SwiftFormat itself, and after that we can invoke the function to commit the changes.

`commit_changes()`

If you've never written / read a Bash script before, this might look a bit daunting. But don't worry, I'll explain what's happening here.
Firstly, we're using the systems Bash with what is known as a Shebang. After that, we're setting the -e flag, which tells Bash to exit the script if any command returns a non-zero exit code. This is useful to prevent the script from continuing if something goes wrong.

Next, we're writing a method. This is exactly the same as a method you'd write in Swift or any other programming language.
What this method does, is firstly it prints out that we're starting to commit, then (commented out) if we need to - we're setting up the git config with the email and username we want to use for the commit.

After that, we're adding all the modified .swift files that have been changed, committing them with a message, and then pushing them to the remote repository.
We don't want to add any temp files or anything else that have been changed, so we're using git add ./\*.swift to only add modified .swift files.

Running SwiftFormat

At this step, we're printing out that we're running SwiftFormat, and then we're running it with the swiftformat . command. This will run SwiftFormat on all the .swift files in the current directory.
The command will look for a local .swiftformat.yaml file, and if it doesn't find one, it will use the default rules.

Checking for changes

After running SwiftFormat, we're checking if there are any changes to the .swift files. If there are, we're printing out that we're preparing to commit, and then we're calling the commit_changes function.
The way we're doing this is with a simple if statement, firstly we're using the git status --porcelain command to get the status of the repository. The --porcelain flag is used to get the status in a machine-readable format. We're then piping this output to grep to search for any .swift files that have been changed.
We're adding the -q flag to grep to make it quiet, and only return a non-zero exit code if it finds a match. If it does, we're printing out that we're preparing
to commit, and then we're calling the commit_changes function. This is because we don't really care about which files have been changed, we just care that there are files that have been changed.

If no files have been found, there's nothing to commit, congratulations!
If there are files found, we're going to the commit_changes() method, which we explained above.

Conclusion

And that's it! it really was that easy to write a script that:

Run SwiftFormat
Checks if there are any files changed
Commits the changes if there are any

You can now plop this script into your CI provider. Depending on your provider, you may need to make it into an executable, using something like chmod +x /path/to/your/script.sh. However, with a lot of providers like CircleCI, scripts can run as executables out of the box, so check with your providers docs.
I hope you find this useful!

My Favorite Xcode Shortcuts for Power Users

NoamIfergan@gmail.com — Mon, 13 Jan 2025 00:00:00 GMT

Introduction

Oh Xcode, what a love-hate relationship I've got with you. So many good things in that IDE, yet so many shitty things all at once. However, love it or hate it, Xcode is our bread and butter, and unless you work with a very specific workflow, you'll be spending most of your time in Xcode. So why not make the best of it and learn some shortcuts to make your life easier?
Here are a few of the shortcuts I use on a daily basis. I hope you'll find them useful too!
I will be referring to their default key combinations, but you can always change them in the preferences (I have!)

Command palette

If you've used something like VSCode or an IntelliJ IDE, you're probably familiar with the command palette. It's a quick way to access any command in the IDE. In Xcode, you can access it with Cmd + Shift + A. The reason I'm starting with this one is that it can honestly replace almost all of the following ones. I use this command all the time, to do things like reset package caches, generate initializers, or honestly anything else. It's a great way to discover new features in Xcode too. I've remapped it to Cmd + Shift + P, so my muscle memory doesn't go away when I spend time in VSCode writing Fastlane stuff (if you haven't seen it yet, this is how I work on my Fastlane stuff.)

Open quickly

If you've watched any YouTube tutorial, you've undoubtedly seen the person presenting using this shortcut. It's one of those "once you start using it you will never stop using it". All it does is give you a quick search bar to open any file in your project. It's a great way to navigate your project without having to use the project navigator. You can access it with Cmd + Shift + O. I've remapped it to Cmd + P, because I use it that much.

Edit all in scope

You know when you're refactoring and you've realized that you've named a variable wrong? How could it possibly be called first_name when it obviously should be firstName? Well, if that variable is also used in 10 more places in the file, you can use Cmd + F to find them all and replace them one by one, or use the big bulky refactor from the above-mentioned command palette, or you can use Cmd + Ctrl + E to edit all in scope. It's a great way to quickly change a variable name, or a method name, or anything else that you want to change in a file. It's a great way to keep your code consistent and clean.
The important bit here is that this edit all is in scope. So if you're inside a method, it'll only rename inside that method. If you're at the top level of the file, it'll rename everything in the file.

Reveal in project navigator

This is one of those that I couldn't believe that I'd gone so long without knowing. You know how you're working on a file, and you want to see where it is in the project navigator? You can right-click on the file and select "Reveal in project navigator", or you can use Cmd + Shift + J to do it. It's a great way to quickly see where a file is in your project, and it's a great way to keep your bearings in a large project. I use it all the time when I'm working on a new project and I'm not sure where everything is.

Bonus one - Format File by SwiftFormat

If you've known me for more than 20 minutes, you've heard me rave about SwiftFormat. It's my most used tool ever (the rest are here), and it's the first thing I add to any project I'm working on.
You can use it from the command line, or you can use it as a pre-commit hook, but you can also use it as an Xcode extension. I've chosen the latter, and remapped the key combination to Shift + F3, and use that about a thousand times a day. It's a great way to keep your code consistent and clean, and it's a great way to make sure that you're not spending time on formatting your code, but on writing it.

Conclusion

There are a million more shortcuts in Xcode, and I'm sure you've got your own favorites. Almost all of them can be accessed from the command palette, so I'd recommend starting there. I hope you've found these useful, and I'd love to know what your favorite shortcuts are! Let me know on socials!

Intermediate Fastlane: Smarter iOS Automation

NoamIfergan@gmail.com — Mon, 06 Jan 2025 00:00:00 GMT

Introduction

So by now, if you've been working on mobile development for any longer than a few weeks, you've probably used Fastlane. I know I talk about it a lot in this blog, but it's genuinely one of my favorite tools out there, and I think most people don't use it to its full potential. So in this post, I'm going to show you some more advanced Fastlane features that you might not have seen before.

Separate Fastfiles

When you write your normal code, you won't put everything in the same massive file, right? (RIGHT?) So why would you do that with your Fastlane setup? You can split your Fastlane setup into multiple files, which can make it easier to manage and understand.

I like to have all of my Fastlane files have fastfile in the name, so I can easily see which files are Fastlane files. So for example, I'll have the main Fastfile, and a separate VersionBumpingFastfile for all of my version bumping logic (Which you can learn more about here!).

The way you do this is by using the import method in your Fastfile. So if you have a file called VersionBumpingFastfile in the same directory as your Fastfile, you can import it like this:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'
import 'VersionBumpingFastfile'
# The rest of your normal Fastfile here..

By doing it like this, you can now call any lane in your VersionBumpingFastfile from your main Fastfile, or as standalone commands from the terminal, and you get the nice separation of concerns that you're used to in your normal code.

`before_all` and `after_all`

Think about your normal XCTest suite (I know I know, you're using the shiny new test framework, but try to remember what the olden days looked like). You have setUp and tearDown methods that run before and after each test, respectively. Fastlane has similar hooks that you can use to run code before and after your entire Fastlane run.

This is particularly useful if you've got things that need to happen regardless of which lane you're running. For example, you might want to set up some environment variables, or clean up some files before you start running your lanes. You can do this with the before_all and after_all hooks in your Fastfile.

before_all do
  setup_circle_ci
end

lane :beta do
  build_app(scheme: "MyApp")
  upload_to_testflight
end

after_all do |lane|
  clean_build_artifacts
end

This sets up the environment for CircleCI and cleans up files after the Fastlane run. There are also some great examples of this on the Fastlane docs here, where they use the after_all block to notify a Slack channel when the Fastlane run is complete, which is mega useful.

Embrace the lane syntax

I know we're all coming from different languages and different syntax, but Fastlane has its own way of doing things. Let's look at some lane patterns that can make your code more readable and maintainable.

Firstly, the is_ci helper is your friend. It helps you write conditional lane logic. For example, instead of writing:

lane :deploy do |options|
  if ENV['CI'] == 'true'
    match(type: "appstore")
  end
  build_ios_app
end

You can write:

lane :deploy do |options|
  match(type: "appstore") if is_ci
  build_ios_app
end

You can also use lanes to handle error conditions elegantly:

lane :push_to_git do |options|
  begin
    push_to_git_remote
  rescue => ex
    handle_git_error(error: ex)
  end
end

private_lane :handle_git_error do |options|
  UI.error(options[:error])
  create_git_branch
  push_to_git_remote(force: true)
end

Another way you can make your lanes more readable is by using early returns for validation. For example, instead of writing:

lane :release do |options|
  if options[:version]
    if options[:version].match(/\d+\.\d+\.\d+/)
      increment_version_number(
        version_number: options[:version]
      )
      build_app
      upload_to_app_store
    else
      UI.user_error!("Invalid version format")
    end
  else
    UI.user_error!("Version is required")
  end
end

You can write:

lane :release do |options|
  UI.user_error!("Version is required") unless options[:version]
  UI.user_error!("Invalid version format") unless options[:version].match(/\d+\.\d+\.\d+/)

  increment_version_number(
    version_number: options[:version]
  )
  build_app
  upload_to_app_store
end

Conclusion

These are by no means the end all be all of Fastlane tips, but they're some of the more advanced features that I think a lot of people don't know about. There are a lot more great features, some of them are documented here, and some of them are just waiting for you to discover them. I hope this post has been helpful, and that you can take your Fastlane skills to the next level!

Improve Your Fastlane Developer Experience

NoamIfergan@gmail.com — Mon, 09 Dec 2024 00:00:00 GMT

Introduction

If you've been in mobile development for more than 2 minutes, you've heard of Fastlane.
Either you've used it yourself and you're a pro, or you're just starting out and you're a bit overwhelmed by the sheer amount of things you can do with it.
Like any other incredible tool, the iceberg of information and tooling can be quite daunting. In this post, I'll show you a few tricks and tips that I've picked up over the years that might help you get more out of Fastlane.

You'll notice that a lot of these are Ruby-centric, but in case you missed it, Fastlane is written in Ruby, so it's a good idea to get familiar with it! (at least until Fastlane with Swift comes out of beta)

Editor

First thing you'll want to do is to set up your editor to work with Fastlane. You can of course use whatever editor you want, but I'll show you how to set it up in VSCode (and as an extension of that, Cursor and any other VSCode-based editor).

The first plugin you're going to want to install is Fastlane Snippets. It's a simple plugin that allows for common shortcuts and snippets (duh) for things that you're going to be writing a lot.

The second one will be the Ruby LSP plugin from Shopify. This is a language server plugin that will help you with syntax highlighting, autocompletion, and other things that you might expect from a language server.

These two alone will be more than enough to take you from the non-syntax highlighting, no autocompletion, no snippets world you're probably used to editing Fastlane things in Xcode to a much more pleasant experience.

Formatting and linting

Just like we've got tools like SwiftLint and SwiftFormat, we've got tools for Ruby too.
The most common one is Rubocop. It's a linter and a formatter, and it's very configurable. You can set it up to be as strict or as lenient as you want, and it will help you keep your code clean and consistent. Also, unless Ruby is the main language that you use on a day-to-day basis, it will also help you with the small pitfalls that you might not be aware of.

Installing Rubocop is as simple as any other gem, just add gem 'rubocop', require: false to your Gemfile, and run bundle install.
The require: false means that the gem will be installed but not automatically loaded when your Ruby application starts.
Now the next time you open and save your Fastfile, you'll see all the issues that Rubocop has with your code, and you can fix them as you go. Rubocop can even auto-fix a lot of the issues for you, so you don't have to worry about it.

Ruby versioning

You may want to have different versions of Ruby installed on your machine, or just have a manager to handle the versions for you. The one I use is rbenv. Installation is mega easy using Homebrew, and it really simplifies the whole "what version of Ruby do I need for this project" thing.

Theme 👀

I know, I know, this is a bit of a personal preference, but I've found that using a theme that is easy on the eyes really helps with the whole "I'm going to be staring at this for hours" thing. I use the Monokai theme from BeardedBear, and I love it. They've got a bunch of other options, even some light mode ones if you're into that sort of thing.

Results

Congratulations! You've now got a much nicer dev experience when working on Fastlane. You've got syntax highlighting, autocompletion, snippets, linting, formatting, and even a nice theme to look at. You're all set to take on the world of Fastlane!

You've gone from this:	To this:

Conclusion

I hope you liked these small but impactful tips you can do to have a nicer Fastlane dev experience. I'd love to know if you've got other tools and tips that I've missed, let me know on socials!

Swift Devs: Should You Use Skip or Kotlin Multiplatform?

NoamIfergan@gmail.com — Mon, 02 Dec 2024 00:00:00 GMT

Introduction

Multiplatform tools are not a new thing. There are well-established players out there, like React Native or Flutter, and even some old deprecated ones, like Xamarin / MAUI. But recently, two new players have entered the game: Skip and KMP. Both of them are multiplatform tools, but they have different approaches. In this article, we will compare them and see which one is better for you.

Overview

KMP (Kotlin Multiplatform)

A framework developed by JetBrains, the people behind Kotlin and incredible IDEs like IDEA, WebStorm, and PyCharm. KMP allows you to write code once and run it on multiple platforms, like iOS, Android, and the web. It is based on Kotlin, a modern language that is very nice to work with and is very similar to Swift in many ways.

KMP takes the approach of "share the logic, divide the UI". This means that you write the business logic once, and then you write the UI for each platform separately. This is a good approach if you want to have a native look and feel on each platform, but it can be a bit more work. Your UI will be SwiftUI on iOS, Jetpack Compose on Android (There is also a web side, but I'm not a web dev so I can't talk about it).
This means that you will have to write your UI twice, which might sound like a hassle to some or a great feature to others.
For me, this was a great feature, as I believe that the only way to get native performance and feel from UI is to write it natively.

If you wanted to go a bit deeper, you could also use Compose Multiplatform to have your UI written once, in Kotlin. However, that is still in alpha, so I can't recommend it for production.

The biggest drawback for us iOS developers here will be the fact that this heavily relies on Kotlin, a new language to some. However, the language is very easy to pick up, and with AI tools, this really isn't the hurdle it once was.

Skip

Skip is the other end of the spectrum - you write Swift and SwiftUI code, and that in turn gets compiled into Kotlin and Compose code for you.
Obviously, as Swift developers, this sounds like an incredible premise - you don't need to learn a new language, you don't need to learn a new framework, you just write Swift and SwiftUI, and you get Android for free.
This is a bit of a double-edged sword though - you are relying on a tool to do the conversion for you, and that might not always be perfect. The beauty of it is that, like KMP, you can write UI in SwiftUI and it will get converted into Compose, or you can write just your business logic in Swift, and write the UI in Compose, if you're more comfortable with that. And as far as cross-platform performance goes, since it converts your code to Compose for you, you're getting as close to native Android as possible.

Dev experience

KMP

As a JetBrains tool and a Kotlin-first tool, the main IDE that you will be working in will either be IDEA (paid or community version), or my recommendation, Android Studio. This is a great IDE, and it has a lot of features that make working with KMP a breeze. JetBrains IDEs are a bit marmite - you either love them or hate them. I personally love them, but I know a lot of people who don't.
However, any iOS-related work that you'll be doing, whether that be any project configuration work, code signing, and indeed any SwiftUI work, will be done in Xcode. This means that you will have to switch between IDEs, which can be a bit of a hassle. JetBrains have said that they're working on a standalone IDE for KMP, but that is still in the works.

Skip

Skip setup is done in the terminal, using their CLI, which is well documented on their website. It feels very similar to setting up a new Swift package, and it's very easy to get started. The main IDE that you will be working in will be Xcode, which is great for us iOS developers. You will be able to do all of your work in one place, and you won't have to switch between IDEs. This is a big plus for me, as I like to have everything in one place, even if that one place is Xcode.

Summary

While Kotlin and JetBrains IDEs are great, the comfort and familiarity of writing Swift code in Xcode is just unmatched, at least until JetBrains comes out with their standalone IDE.
This one goes to Skip, for me.

Support and documentation

KMP

KMP has tremendous support from the community and from JetBrains themselves, and they are very responsive to tickets opened and issues raised. The documentation is also very good, and there are a lot of tutorials and guides out there to help you get started.
Obviously, being a bigger and more established company gives them the ability to have a bigger team and more resources to put into support and documentation.

Skip

The docs for Skip are great. Getting up and running with a basic project is fully covered, and won't take you long at all. Even a more complex project is well documented, and you should be able to get up and running in no time.
The support is also great, and when I had a question I asked it in the Slack, and was responded to by the creator on the same day, which is very impressive.
However, and this is by no fault of the Skip team, they are a younger product and a much smaller team, so the support and documentation might not be as good as KMP's.

Summary

This one is weirdly hard to call. They're both well documented on their own website and have good support, but KMP being just that much bigger and having a larger community, I think I have to give this one to KMP.

Price

KMP

KMP is free, regardless of the size of the team or project using it. This is a big plus, as it means that you can try it out without any risk, and you can use it for any project, regardless of the size.

Skip

Skip has a free tier for indie developers, which in my opinion is very generous and should be more than enough for you to have a look, play around, and even deploy a full app to both stores without ever paying.
However, for teams and more than one closed source project, there is a cost associated with it. This is a bit of a downside, but it's understandable, as they need to make money somehow, and they're not a big company like JetBrains.

Summary

This one goes to KMP, for being free for everyone, but I would like to give a special mention to Skip for having a very generous free tier.

Conclusion

While I think Skip is an incredible tool with an endless amount of potential, for a lot of you, KMP might be the better choice. It's more established, has a bigger community, and is free for everyone. However, if you're a Swift developer, and you want to write Swift code, and you don't mind a bit of a learning curve, Skip is a great choice, and I don't think you'll be disappointed.
For 99.9% of indie devs, you'll be happy with both, so I would recommend building a small app (I built a Pokemon app), spend the day with the frameworks, and see which one you like better.

Intro to Scripting with Swift (for Automation)

NoamIfergan@gmail.com — Fri, 22 Nov 2024 00:00:00 GMT

Reasoning

As Swift developers (whether working with iOS, macOS, visionOS, or any other OS), we're used to using Swift for building apps. But Swift has evolved and grown over the years, and now we can even use it for scripting. This allows us to leverage all of the qualities that we love about Swift, without wasting time googling syntax.

The Basics

As a Swift developer, you already know how to write scripts with Swift, you just may not know it yet.
The basics of scripting with Swift are incredibly simple:

Create a new file with a .swift extension
Write your Swift code
Run the file with swift <filename>.swift

Yes, it's that simple. Let's give it a try:

import Foundation

let name = "Noam"

func greeting(for name: String) -> String {
    return "Hello, \(name)!"
}

print(greeting(for: name))

I know, I know, what an exciting script. But it's a start! All we need to do now is create a file with this incredibly simple script and run it with swift <filename>.swift.
You can just copy the above, and run pbpaste > Greeting.swift in your terminal, and then run swift Greeting.swift.

Great job! You've just written your first Swift script. Now let's dive a bit deeper.

Passing Arguments

This greeting is good and all, but as I'm sure you could've guessed, it's a bit simple and hardcoded. Let's make it more dynamic by passing the name as an argument.

import Foundation

func greeting(for name: String) -> String {
    return "Hello, \(name)!"
}

if CommandLine.arguments.count > 1 {
    let name = CommandLine.arguments[1]
    print(greeting(for: name))
} else {
    print("Please provide a name")
}

You know the drill: copy the above, save it to a file, and run it with swift <filename>.swift <your name>.

Hurray! Look at you, passing arguments to your script like a pro.
You'll notice that the arguments passed in are stored in the CommandLine.arguments array, and the first argument is the name of the script itself.

User Input

Now, while this script works, it requires us to know that a parameter is required and what that parameter is. Let's make it more user-friendly with a readLine prompt.

import Foundation

func greeting(for name: String) -> String {
    return "Hello, \(name)!"
}

if CommandLine.arguments.count > 1 {
    let name = CommandLine.arguments[1]
    print(greeting(for: name))
} else {
    print("Please provide a name")
    if let name = readLine() {
        print(greeting(for: name))
    }
}

Now we're getting somewhere! This script will prompt the user for a name if one isn't provided as an argument.

Some Pizazz

As a command line script, we can also leverage the power of the terminal. Let's add some color to our script.

import Foundation

func greeting(for name: String) -> String {
    return "Hello, \(name)!"
}

if CommandLine.arguments.count > 1 {
    let name = CommandLine.arguments[1]
    print("\u{001B}[0;32m" + greeting(for: name) + "\u{001B}[0;0m")
} else {
    print("\u{001B}[0;31mPlease provide a name\u{001B}[0;0m")
    if let name = readLine() {
        print("\u{001B}[0;32m" + greeting(for: name) + "\u{001B}[0;0m")
    }
}

As you can see, we can use all of the fun parts of the terminal, like adding colors, supporting ASCII art, and more.

File I/O

While writing CLI tools and commands is fun, handling files is a common task for scripts. Let's write a script that writes to a file, then reads it and prints it to the console.

import Foundation

let filename = "test.txt"

func writeToFile(_ filename: String, contents: String) {
    do {
        try contents.write(toFile: filename, atomically: true, encoding: .utf8)
        print("Wrote to file \(filename)!")
    } catch {
        print("Failed to write to file \(filename)")
    }
}

func readFromFile(_ filename: String) -> String? {
    do {
        return try String(contentsOfFile: filename, encoding: .utf8)
    } catch {
        print("Failed to read from file \(filename)")
        return nil
    }
}

func readAndWrite(name: String) {
    writeToFile(filename, contents: "Hello, \(name)!")
    print("Contents of the file: \(readFromFile(filename)!)")
}

if CommandLine.arguments.count > 1 {
    let name = CommandLine.arguments[1]
    readAndWrite(name: name)
} else {
    print("\u{001B}[0;31mPlease provide a name\u{001B}[0;0m")
    if let name = readLine() {
        readAndWrite(name: name)
    }
}

And like before, we'll save this to a file, and run it with swift <filename>.swift.

As you can see, we are now both reading and writing from a file. This is a common task for scripts, and Swift makes it incredibly easy and, more importantly, safe.

Additional Resources

The French Connection conference has recently released their talk videos, including an excellent presentation by Natan Rolnik about this very topic! You can check out his talk here, and visit his blog at swifttoolkit.dev.

Conclusion

As you've seen, writing scripts in Swift is incredibly easy. This can be expanded upon almost endlessly - the obvious next step is compiling an executable. You have all the power of Swift, with its type safety and elegant syntax, at your disposal. So go ahead, write some scripts, and have fun with it!

My Favorite Dev Tools for iOS & CI/CD

NoamIfergan@gmail.com — Mon, 18 Nov 2024 00:00:00 GMT

Introduction

I'm a big tool fan boi. I love finding tools that either help make my life easier, more comfortable, or just cooler. So here's a list of some of my favorite tools that I use on a daily basis.

LazyGit

I know I know, everyone has they're preferred git and they aren't likely to change it, and a terminal, keyboard-based, no mouse git client is a hard sell for most people. but hear me out!

Firstly, it's incredibly quick. I can stage, commit, push, pull, and do everything else I need to do with git in a fraction of the time it would take me in the terminal.

Secondly, because it's all in the terminal, I can do everything with my keyboard, and once you master all of the shortcuts, you'll be flying through your git workflow.

Lastly, it's just so damn pretty. I mean, look at it! It's like a little game, and I love it. It makes me feel like a real hacker, and that's all I've ever wanted.

Xcodes

Yup, Xcodes, plural, not Xcode. This incredible tool help manage all of your Xcode installations. It's a simple GUI that allows you to download, install, and switch between different versions of Xcode with ease.
No more waiting 4 hours for a download from the App Store, no more downloading zip files and doing the hard work yourself. Just click a button, and you're good to go.
It helps as well that it's insanely quick because it uses parallel downloading, so getting a version downloaded and installed is a matter of minutes, not hours.

In addition to all that, you can see your installed version AND installed platforms (like which iOS versions you've got), so you can clean up the ones you don't use, and minimize a bit of the insane disk space that Xcode takes up.

Copilot for Xcode

The official Github plugin for copilot. I've used Copilot for Swift development before on VSCode, and it was nice but not particularly useful. But in Xcode, it's a whole different story.
It's lightyears better than the apple intelligence one, in my opinion, and it really speeds up my development.

I think the main bit to have in mind when using it is - this is an assistant, not a boss. It's there to help you, not to do the work for you. So use it as a tool, not as a crutch.
So don't expect to give it a prompt and have it spit out and entire functioning app, but do you need help with protocol conformance? It's got you covered. Unit tests? east peasy. It's a great tool, and I highly recommend it.

Raycast

Oh Raycast, my beloved Raycast. I've been using Raycast for a while now, and I can't imagine my life without it.
I know for a fact that i'm not even using it to it's fullest potential, but even with the small amount that I do use, it's a game-changer.
I use it to quickly open meetings, search file, open apps, and even to do quick calculations. It's like spotlight, but on steroids. As a matter of fact, I've disabled spotlight on my Mac because I never use it anymore.

Not only that, but the built-in paste board has changed my life completely and i don't know how i ever lived without it.
Honestly I cannot recommend Raycast enough, it's a must-have for any Mac user.

Arc Browser

By now I'm sure most of you have heard of Arc. I know they're a bit controversial at the moment, given that the CEO has announced that they're not going to be adding and new features to it, but honestly? I don't care.

I've been using Arc for about 18 months now, since i started working for a company that heavily realized on the Google suite ( think, Google Meet, Google Sheets etc), and a Chromium-based browser was a godsend.

I was a hated of the design first, but not only did it grow on me, I'm at a point where I can't go back. The smart PR folder for all of my PR tabs, the pinned tabs, the key-board shortcuts (are you seeing a pattern here?), and the built-in ad blocker. It's just so good.

Plus, it's written in Swift, which is fun little tidbit that I love to tell people.

So if you haven't tried Arc yet, I highly recommend it. It's a great browser, and I'm sure you'll love it. Or don't. live your life. But you should try it.

Conclusion

These are just 5 of the tools I use on a daily basis, but there are a ton more than are just as good and cool but haven't made the cut for this list, like iTerm, Bartender, CleanMyMac, and so many more, but these are the ones that I use every single day, and I can't imagine my life without them. I'd love to hear what tools you use on a daily basis, and if you have any recommendations for me, so please let me know!

Bump Swift Package Version Automatically with Fastlane

NoamIfergan@gmail.com — Fri, 15 Nov 2024 00:00:00 GMT

Introduction

If you're using SPM (Swift Package Manager) for your SDKs/ packages / to have a modularized project, you might have had an issue with forgetting to bump the version of the package before merging, and having to do a silly PR after the fact, usually called "bump_version", and have your teammates mock you and your forgetfulness.
Well, fear no more ! I am here to show you how to automate this process using Fastlane!

Assumptions

You've already got Fastlane setup for your project, and that you've got familiarity with what Fastlane is and how it works.
Your SPM project is following sem-ver versioning
You create releases for your SPM package on GitHub
Your git config is setup correctly, and you can push to the remote without any issues.

Plan

So, how are we going to do this? well, easy enough! what we're going to do, is create a flow that will:

Check the current version of our package
Check the remote version of our package
If the remote version is higher than the local version, we'll bump the version of our package
If the remote version is the same as the local version, we'll bump it still
if the local is higher than the remote, we'll leave it as is (as it was already bumped)
We'll push the new version to the remote
We'll sit back and have a coffee, knowing that we've automated this process and our imposter syndrome is at bay

Implementation

We're going to follow the steps above, by writing lanes and ruby methods to assist us. (ICYMI, Fastlane is Ruby based, so we can use Ruby!)

Step 1: Find the current package version

Following the steps we've outlined above, let's start by finding out what's the current version of our SPM package.
To do that, let's write a quick ruby method:

desc 'The version of the SPM pacakge'
def package_version
  version_line =
    File.open('../Package.swift') do |file|
      file.find do |line|
        line =~ /^let packageVersion =/
      end
    end
  version_line.tr!("'a-zA-Z\n=\"\s", '')
end

Let's unpack it a bit, because it's a bit daunting to look at:

First we find the Package.swift file. we need to put a ../ before it, because things are being called from the fastlane folder.
Once we found and opened the file, we're reading it until we find the line starting with let packageVersion =
Lastly, we're removing all the characters we don't need, so we're trimming the line and leaving just the version number.

Step 2: Find the remote package version

Great! so we have a way to get the local package number, now we need a way to get the remote one as well!
To do that we're going to, you've guessed it, write another ruby method:

desc 'Get the latest version that was released on git'
def released_package_version
  sh('git', 'describe', '--tags', '--abbrev=0', log: false) do |status, output, _command|
    return '0.0.0' unless status.success?
    return output.to_s.tr("a-z'\n\s", '')
  end
end

Again, a bit of a mouthful, but let's break it down:

We're calling git describe --tags --abbrev=0 to get the latest tag that was released, suppressing log output for cleaner results.
If the command fails, we're returning 0.0.0 as a default value
And again we're using a similar regex to trim the output and leave just the version number.

Step 3: Comparing

Now that we've got methods to get both local and remote version of our package, let's compare them and see if we need to bump.
Can you guess what we're going to do? yes, write another method!

desc 'Bumps the version of an SPM package if needed.'
def bump_version_if_required
  local_version_number = package_version
  remote_version_number = released_package_version
  # If the local version is smaller or equal to the remove version, bump it
  if Gem::Version.new(local_version_number) <= Gem::Version.new(remote_version_number)
    # Here we're going to bump the version
  else
    # If it's not, it was already bumped and we can ignore it
    puts 'Local version number is up to date'
  end
end

This one is a bit more straightforward, we're comparing the two versions, and if the local version is smaller or equal to the remote version, we're going to bump it.
We're using the built in Gem::Version class to compare the two versions, so we don't have to deal with the sem-ver
comparing ourselves.

Step 4: Bumping the version

Now that we've got the comparison, we need a way to actually bump the version when it's needed.

Firstly, let's write a to do the actual bumping:

def bump_version_number(version_number)
  version_number_array = version_number.split('.').map(&:to_i)
  version_number_array[-1] += 1
  version_number_array.join('.')
end

This method takes in a version, bumps it's patch number and returns the new version. simple!

Next, we need to write a method that will actually write the new version to the Package.swift file:

def bump_version(remote_version)
  package_version_key = 'let packageVersion = '
  file_path = '../Package.swift'
  file_contents = File.read(file_path)
  matching_line = file_contents.lines.find { |line| line.include?(package_version_key) }
  new_version_number = bump_version_number(remote_version)
  puts "New local version number: #{new_version_number}"
  new_line = "#{package_version_key}\"#{new_version_number}\"\n"
  updated_contents = file_contents.gsub(matching_line, new_line)
  File.write(file_path, updated_contents)
end

This is very similar to what we've done above when we wanted to read the version number, but this time we're writing it back to the file.
So let's break it down:

We're setting variables for things that we're going to use in a few places, because DRY! (remember, just because it's automation code, doesn't meant it doesn't need to be good code!)
Reading the line we want, and storing it in a variable
Bumping the version number
Creating a new line with the bumped version number
Replacing the old line with the new one
Writing the new contents back to the file!

And that's it, voila and you've bump the version of your SPM package! let's have a quick update at our bump_version_if_required method, to include the new bumping logic:

desc 'Bumps the version of an SPM package if needed.'
def bump_version_if_required
  local_version_number = spm_package_version
  remote_version_number = released_package_version
  # If the local version is smaller or equal to the remove version, bump it
  if Gem::Version.new(local_version_number) <= Gem::Version.new(remote_version_number)
    # Here we're going to bump the version
    puts 'Bumping version number'
    bump_version(remote_version_number)
    puts 'Version number bumped'
    puts spm_package_version
  else
    # If it's not, it was already bumped and we can ignore it
    puts 'Local version number is up to date'
  end
end

Step 5: Pushing the new version

Now that we've bumped the version, we need to push it to the remote, so that it's up to date.
let's write a lane that will do that for us. We're going to use the git action that Fastlane provides, to do this, so we will need to have
require 'git' and fastlane_require 'git' at the top of our file:

lane :commit_to_git do |options|
  repo = options[:repo] || Git.open('.')
  current_branch = repo.current_branch
  git_commit(path: '.', message: options[:commit_message])

  begin
    repo.push('origin', current_branch)
  rescue Git::GitExecuteError => e
    raise e unless e.message.match?(/no upstream branch/)

    repo.push('origin', current_branch, set_upstream: true)
  end
end

This just takes in a parameter, commit_message, and a repo, and commits and pushes the changes to the remote.
If for some reason the remote isn't there, or we get an error, we print it out so we'll know what happened.
let's add that to our bump_version_if_required method:

desc 'Bumps the version of an SPM package if needed.'
def bump_version_if_required
  local_version_number = spm_package_version
  remote_version_number = released_package_version
  # If the local version is smaller or equal to the remove version, bump it
  if Gem::Version.new(local_version_number) <= Gem::Version.new(remote_version_number)
    # Here we're going to bump the version
    puts 'Bumping version number'
    bump_version(remote_version_number)
    puts 'Version number bumped'
    repo = Git.open('.')
    commit_to_git(commit_message: "Bump version number from #{local_version_number} to #{spm_package_version}", repo: repo)

  else
    # If it's not, it was already bumped and we can ignore it
    puts 'Local version number is up to date'
  end
end

Step 6: Putting it all together

Well done on making it so far! we've done it, we've created a flow for us to automate the version bumping of
our SPM package, and we've done it using Fastlane! let's put it all together in a Fastfile, so we can call it easily:

#!/usr/bin/ruby
# frozen_string_literal: true

fastlane_version '2.225.0'
fastlane_require 'git'

# rubocop:disable Metrics/BlockLength
default_platform :ios
platform :ios do
  desc 'The version of the SPM pacakge'
def spm_package_version
  version_line =
    File.open('../Package.swift') do |file|
      file.find do |line|
        line =~ /^let packageVersion =/
      end
    end
  version_line.tr!("'a-zA-Z\n=\"\s", '')
end

desc 'Get the latest version that was released on git'
def released_package_version
  # Get the most recent Git tag, suppressing log output for cleaner results
  sh('git', 'describe', '--tags', '--abbrev=0', log: false) do |status, output, _command|
    # Returns a placeholder if no Git tags have been defined, indicating no release has been made
    return '<never released>' unless status.success?

    # Removes any lowercase letters, apostrophes, newline, and whitespace characters from the Git tag,
    # so we get just a number,and  returns the cleaned version number as the result of the method
    return output.to_s.tr("a-z'\n\s", '')
  end
end

desc 'Bumps the version of an SPM package if needed.'
def bump_version_if_required
  local_version_number = spm_package_version
  remote_version_number = released_package_version
  # If the local version is smaller or equal to the remove version, bump it
  if Gem::Version.new(local_version_number) <= Gem::Version.new(remote_version_number)
    # Here we're going to bump the version
    puts 'Bumping version number'
    bump_version(remote_version_number)
    puts 'Version number bumped'
    repo = Git.open('.')
    commit_to_git(commit_message: "Bump version number from #{local_version_number} to #{spm_package_version}", repo: repo)

  else
    # If it's not, it was already bumped and we can ignore it
    puts 'Local version number is up to date'
  end
end

def bump_version_number(version_number)
  version_number_array = version_number.split('.').map(&:to_i)
  version_number_array[-1] += 1
  version_number_array.join('.')
end

def bump_version(remote_version)
  package_version_key = 'let packageVersion = '
  file_path = '../Package.swift'
  file_contents = File.read(file_path)
  matching_line = file_contents.lines.find { |line| line.include?(package_version_key) }
  new_version_number = bump_version_number(remote_version)
  puts "New local version number: #{new_version_number}"
  new_line = "#{package_version_key}\"#{new_version_number}\"\n"
  updated_contents = file_contents.gsub(matching_line, new_line)
  File.write(file_path, updated_contents)
end

lane :commit_to_git do |options|
  repo = options[:repo] || Git.open('.')
  current_branch = repo.current_branch
  git_commit(path: '.', message: options[:commit_message])

  begin
    repo.push('origin', current_branch)
  rescue Git::GitExecuteError => e
    raise e unless e.message.match?(/no upstream branch/)

    repo.push('origin', current_branch, set_upstream: true)
  end
end

lane :bump_spm_package do
  puts bump_version_if_required
end

end

And that's it! now you can call fastlane bump_spm_package and it will bump the version of your SPM package for you!
this can be called locally or from a CI, whatever your setup is.

This was a lot of fun to do, and shows how small things can really increase our quality of life, and remove a concern from us - so we can focus on what's really important, arguing on Twitter
Thanks for reading!

How to Write Your First CircleCI Orb

NoamIfergan@gmail.com — Fri, 08 Nov 2024 00:00:00 GMT

Reasoning

The issue we've faced at work is that we've had multiple projects, living in multiple repos, each with their own CircleCI config file. While this might work (ish), it's no ideal for several reasons:

It's hard to maintain. If we want to change something in the config, we have to do it in multiple places.
It's hard to keep in sync. If we want to add a new job, we have to do it in multiple places.
It scratches me wrong. as a programmer, I don't like to repeat myself. I like to keep things DRY.

Approach

So to combat all of the above, i've looked into a few options from CircleCI. The first one I looked at was Dynamic Configs [link needed]. This is a good approach for some, but it felt a bit overcomplicated for us, and it didn't feel like tool for the job. it's not about having configs that dynamically change according to the project, it's about having a set of reusable jobs that we can use across multiple projects.

So naturally the next step was authoring an Orb. If you've ever used CircleCI for iOS development, or used it to have Slack alert - you've used Orbs before. Orbs let you setup reusable jobs, commands, and executors that you can use across multiple projects. They're a great way to keep your config DRY, and to keep your config in sync.

The main attracting points for us were:

We could have a single source of truth for our jobs. If we wanted to change a job, we could do it in one place.
We could have our executors setup in once place. this means that when we needed to update our Xcode version, or the MacOS version, we only needed to do it once.
There's a dev release before a prod release. this means that we don't have to break everything everywhere at once; we can develop and test and only deploy when we're ready and sure of ourselves.

Getting started

Firstly, I am going to assume you've got all the right permissions for the repo / project that your'e working on.
i'd suggest you start off using the orb template that CircleCI provides. You can find it here. This will give you a good starting point for your orb. This will give you the basic file structure so we can keep working on it; now let's go over the files and what they do, and why you might care about them:

@orb.yml

This is the "front page" of your orb, this is where you have the description of the orb, and it holds the description of the orb, the home and source URLs (where does this orb live? ), and perhaps most importantly - this is where you will define any orbs that your orb depends on (if any). So for our usage as an iOS app, we had to use the macos orb, and the slack orb which we used for notifications.

Commands

This folder is where you put all of your, well, commands. Commands are the building blocks of workflow, these should be concise, and encapsulated. We will go into how to write a command in a bit.

Executors

This is where you can define what you jobs will run on. Executors are the environment that your jobs will run in. This is where you can define the image, the environment variables, and the resources that your job will have access to. For our example, this is also where you define your mac version, and your xcode version, which are very important.

Includes

This is where you can any scripts you want to be bundled into the orb. These are BASH scripts that you can use in your jobs, and having them here means that you can keep your jobs clean and concise, and you have the ability to write tests for them (although I never did, because I'm a bad person).

Jobs

These are the meat and potatoes of your orb - these are the things that will be visible to the config calling the orb, this is where you will define what parameters you need, what executors you will use, and what commands you will run.

Examples

Here you should put what an example usage of your orb would look like. This is a good place to show off what your orb can do, and how it can be used.

Writing an executor

Like we mentioned, executors are the machines and environments that your jobs will run on. Here's an example of an executor that we used in our orb:

description: >
  Default mac executor

macos:
  xcode: "16.0.0"
  resource_class: macos.m1.medium.gen1

shell: /bin/bash --login -o pipefail

environment:
  FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT: "120"
  FASTLANE_XCODEBUILD_SETTINGS_RETRIES: "5"

So we have the description, which is pretty self explanatory. We then have the macos key, which is where we define the xcode version that we want to use, and the resource class that we want to use. We then have the shell key, which is where we define the shell that we want to use. Finally, we have the environment key, which is where we define any environment variables that we want to use. This is where we define the FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT and FASTLANE_XCODEBUILD_SETTINGS_RETRIES variables, which are used by fastlane.

Writing a command

Like we mentioned above, commands are the building blocks of jobs. They can have as many or as few steps as you'd like, but they should be concise, and encapsulated. Here's an example of a command that we used in our orb:

description: "Execute fastlane based on the lane name"

parameters:
  fastlane_type:
    type: string

steps:
  - run:
      name: Executing fastlane << parameters.fastlane_type >>
      command: |
        bundle exec fastlane << parameters.fastlane_type >>

This command is pretty simple, it takes a fastlane_type parameter, and then runs the fastlane command with that parameter. As you can see it's quite reusable, this can be called from where ver and doesn't depend on anything or any project.

Writing a job

Now that you've written a command, you can write a job. Jobs are the things that will be visible to the config calling the orb, and if your commands relies on other things happening before it, or after it, this is where you'll define that flow. Here's an example of a job that we used in our orb:

description: >
  Execute any lane

parameters:
  fastlane:
    type: string

executor: mac_executor

steps:
  - load_workspace
  - restore_cache_gems
  - fastlane_execute_lane:
      fastlane_type: <<parameters.fastlane>>

This job is a bit more complex, it takes a fastlane parameter, and then runs a series of commands before running the fastlane command. This is where you can define the flow of your jobs, and how they should be run. Lets explain a bit of what's going on here:

1. The description is to explain to whatever is calling this job what the does the job do. pretty self explanatory.
2. The parameters are the things that you can pass to the job. In this case, we're passing a `fastlane` parameter, which is a string.
3. This needs to run on a mac machine, so we use a mac executer that we've defined in the `executors` folder.
4. We then run a series of commands, `load_workspace`, `restore_cache_gems`, and then `fastlane_execute_lane` which is the command we defined above. To call a job, you just need to use it's file name. so we saved the above job as `fastlane_execute_lane`, so we call it as `fastlane_execute_lane`.

Orb development

Congratulations! You've written your first orb, with a command, a job, and an executor. Now you're ready to use it's dev version and try it out. if you've used the template provided above, you'll notice that this orb project has a .circleci folder, which holds a config. we're not going go over how things work in that config, but what you need to know for now is - if you push your branch, a workflow will be triggered that will create a dev version of your build. This will happen in the publish job, and when it's done you'll be able to see the hash of your new dev orb ( which will be available for 90 days), or you can just use @dev:alpha to use the latest dev version of your orb.
Now you can import it in whatever config that you want to use it in, for example:


version: 2.1

orbs:
our-orb: our-org/orb-name@dev:alpha

// The rest of your config...

Now you've got your orb in your config, you can start using it's jobs in your workflows.
Here's an example of how you might use the job we defined above:

fastlane:
  jobs:
    - checkout_code
    - our-orb/fastlane:
        fastlane: "test"
        requires:
          - checkout_code

So by doing this, we've defined a workflow that will run the checkout_code job, and then run the fastlane job that we defined in our orb. This is a very simple example, but you can see how you can start to build up your workflows using the jobs that you've defined in your orb. You can also pass those variables through the pipeline, you can have them passed in as ENV variables, or you can hard code them, it's up to you.

Once your'e done, if you merge your orb into master / main, and create a tag with a sem-ver version, your orb will be published and available for use in any config that you want to use it in.

Conclusion

This was a very high level overview of how to write an orb, and how to use it in your config. There's a lot more that you can do with orbs, and a lot more that you can do with CircleCI. I've really enjoyed working with them, and the CircleCI documentation is nice and descriptive, but can be a tad overwhelming.
I hope you've enjoyed this brief post, and I'd love to hear if you've got questions or comments. I'm always looking to learn more, and to help others learn more too.