This post covers what changed, how it impacts your CI/CD pipelines, what fastlane did to patch the issue (for most users), and what to expect moving forward.

🤔 So, what is this “template_name” thing?

This is what I asked myself when I saw this issue was gaining a lot of traction in fastlane issues and PRs, so here’s what I learned:

Apple provides certain entitlements only to approved developers — things like:

• com.apple.developer.healthkit.access (advanced HealthKit access)

• com.apple.developer.driverkit

• com.apple.developer.carplay-messaging

These are commonly referred to as custom entitlements or additional entitlements, but the new official term by Apple is “managed capabilities”. Apple requires that developers request access to them before they can be used and, upon approval, associates a special App ID template with the developer’s account.

The only way to generate a provisioning profile with those entitlements programmatically used to be passing that template’s identifier — the template_name — to Apple’s API when creating a profile.

fastlane supported this through the template_name parameter in match. It worked reliably for years, despite the fact that Apple never documented or officially supported the parameter.

😬 Apple removes support for template_name

If you saw an error like:

The provided entity includes an unknown attribute - 'templateName' is not an attribute on the resource 'profiles' - /data/attributes/templateName

It’s because in late May 2025, Apple removed support for the template_name parameter altogether. That change broke profile creation for all users of fastlane — even those not using managed capabilities — since fastlane would serialize template_name parameter as nil, which Apple’s API also started rejecting.

See GitHub Issue #29498 for the initial bug report.

🩹 The temporary fix for most users

To quickly unblock the majority of teams — the ones not using managed capabilities — a PR was merged that removes the template_name parameter entirely for everyone.

If you’re not using managed capabilities, this fix is already available in the latest fastlane release v2.228.0. You can resume generating profiles with match as usual.

🚧 Still Broken for Managed Capabilities

If your app depends on one of Apple’s managed capabilities, this fix stops the crashes, but it will create provisioning profiles that don’t include your custom entitlements. There is currently no official way to programmatically specify which App ID template to use when creating a provisioning profile.

To solve this, Apple recommends using automatic signing via Xcode or Xcode Cloud, which automatically selects the right template when managing signing for your app, but we know how things end with automatic signing in large teams 😅 which is the whole point of using match.

🚀 What’s Next?

The fastlane team deprecated the template_name parameter in match until Apple provides an official way to handle managed capabilities (fka custom entitlements) through automation. For now:

• If you don’t use custom entitlements: You’re safe. fastlane works as expected again.

• If you do: You’ll need to manually manage profiles via the Developer Portal or use Xcode’s UI until Apple updates their APIs.

  • See Apple - Provisioning for managed capabilities to learn more.

  • Since Apple migrated from “additional entitlements” to “managed capabilities”, you may need to re-assign some of these entitlements to your App IDs, if they are missing. You can request additional entitlement migration to managed capabilities via this contact form (as the Account Holder) if any previously assigned entitlements are not visible.

The team will be actively monitoring the situation and will update fastlane’s documentation and tooling once Apple provides a supported alternative.

Let us know if you’ve been affected by this change — or if you’ve found a workaround we should document!

📚 Want to Learn More?

• Apple: Adding capabilities to your app

• Apple: Capabilities documentation

• Apple: Entitlement migration request form

• fastlane issue tracking the bug, and the PR that fixed it: [sigh][match] fix issue where unknown attribute template_name is being sent when creating provisioning profiles #29591

I’ve been using GitHub's "Settings" App to easily sync and maintain repository settings, as well as streamline the creation and configuration of new repositories. Today I’ll go through why I use it, its use cases, and how to avoid common pitfalls that I’ve faced! 😊

Why should I sync settings using a config file?

Synchronizing settings via a config file enhances consistency, efficiency, and transparency. It empowers teams to propose changes via Pull Requests, ensuring a democratized and traceable approach to repository configurations.

This is more evident when managing open source repositories, and even more critical at scale, when managing tens if not hundreds of repos. For example, if you have 10 repositories, you would need to manually update 10 repositories to add a new collaborator. With the GitHub "Settings" App, you can simply update the config file and create a Pull Request to update all 10 repositories. The same goes for label management, branch protections, and more.

Another benefit of using the GitHub "Settings" App is that it allows you to easily create new repositories with the correct settings. This is especially useful when you want to quickly create a new repository with the same settings as you're already used to, without having to manually configure them. I found that this streamlines my workflow of new project creation, and also ensures that I don't forget to add any important settings that I would otherwise stumble upon later.

How can I implement this?

To utilize this functionality, first, install the GitHub "Settings" App and choose which repositories you'd like it to have access to. I select "All repositories" so it applies to current and also future repos automatically.

Next, if you intend to use a single file to manage multiple repositories, it's a good idea to create a dedicated repository for this, called YOUR_ORG_NAME/.github, e.g. https://github.com/rogerluan/.github. This allows you to create a centralized config file, which will then be inherited in all the other repos you want to manage. Keep in mind you should still create a .github/settings.yml file in each repository you want to manage, as this is where the app will look for the settings file, but then you can simply point it to the centralized file. Here's a sample "child" file: https://github.com/rogerluan/arkana/blob/main/.github/settings.yml

Then, define the repository settings in a file named .github/settings.yml. This includes specifying details like collaborators, issue labels, and branch protections. As far as I can tell, the way this app works is that it will parse the raw yaml file and anything that is in it will be sent directly into GitHub's API and be used to update the settings. This means that there's no official list of supported settings for this app, as you can pass anything that is supported by the GitHub API, so the GitHub's API is what should be considered the source of truth.

For a sample list of settings, you can check out the GitHub "Settings" App documentation or if you prefer, there's also my personal settings file that I use for my repositories.

Common Issues

When configuring your file, a small typo, indentation issue, or use of unsupported settings can cause the app to fail, and it fails silently. So it's common to find users frustrated, complaining that the settings aren’t syncing, because there's no user feedback pointing out what's wrong with your file. To overcome this issue, I suggest using a setting file that already works, and go from there. I particularly had issues configuring branch protection and topics (topics can’t have spaces, FYI), but if you follow my file, you should be fine!

Another very important issue to keep in mind is the security implications of using this app. The app will have write access to all the repositories you grant it access to, so it's important to keep your settings file secure. I strongly recommend adding mechanisms to prevent PRs from being merged without someone reviewing that the settings file is being changed (e.g. CODEOWNERS feature, danger code review to check if the settings file is being changed). Failing to do so could be catastrophic, as it would allow anyone to change your repository settings without your knowledge, like changing branch protection rules, adding collaborators, or even making repositories public.

Conclusion

The GitHub "Settings" App significantly simplifies repository settings management at scale, and I love using it for my open source projects! Its ability to centralize configuration and enable Pull Requests for settings adjustments makes it an invaluable tool for modern development workflows.

For more detailed information on the GitHub "Settings" App, you can visit their official page: GitHub Apps - Settings.

Ever since this year’s WWDC, especially after watching the session Debug with structured logging, I’ve been super excited to stop using 3rd party log utilities. First-class citizen treatment for logs is something taken for granted for developers that use other IDEs, like Android Studio, or any other JetBrains IDE. But for developers that dedicate their professional and sometimes personal lives to building software for Apple platforms, we were still in stone age… until now!

In this article I won’t dive into details about why you’d want to use OSLog; instead, you can check the awesome features that OSLog provides in the link above, which is a summary I wrote about that WWDC session.

The information shared in this article is a summary of multiple sources, from developers of open source logging utilities, to Apple employees.

I want to use OSLog! What now?

Despite the excitement around OSLog, it's essential to understand and acknowledge its capabilities and limitations.

Apple's unified system log offers a powerful and efficient logging solution. It's designed for classification and long-term persistence, aiding in debugging issues over extended periods. The log entries are categorized by subsystem, category, and type, with customizable settings for each. This level of detail is beneficial, especially when combined with tools like the Console app and Instruments, which provide sophisticated searching and log entry correlation capabilities.

However, it's crucial to be aware of some limitations of OSLog. For example, the system log API's deep integration with the compiler makes it challenging to be wrapped efficiently. Additionally, in iOS, the system log's reading capabilities are restricted: apps can only access log entries created by their current process. This means that if an app crashes, the subsequent launch, being a different process, won't have access to the logs from the previous instance. This limitation can be a significant drawback if you’re relying on these logs to debug crashes.

Because it pretty much can’t be wrapped, this means we can’t extend its functionality beyond what Apple offers out-of-the-box. Thus, we’re left with no remote logging, no logging to multiple destinations, nor custom logging format, etc.

If you’re starting a new project now, or if you don’t have anything in place and are still using good ol’ print(…) statements, you can probably simply start using OSLog directly.

Now, if you’re interested in those features that OSLog doesn’t offer, you’ll have to choose between your current logging framework and OSLog, unfortunately.

The middle-ground solution

As someone who has been using logs mostly to log messages to the console while debugging features/bugs, I could easily replace all my logging utilities with the OSLog API directly. However, I wouldn’t like to give up on the ability to enable other features in the future, such as remote logging, exporting logs, etc. — features usually available in robust logging frameworks.

To help solve this, I found that a good middle-ground for me was to use a function identical to the official OSLog API on release builds, and use OSLog’s actual API in debug builds. In practice, this means:

#if DEBUG
// In debug builds, we use the system-provided os_log function.
@_exported import OSLog
#else
/// A clone of OSLogType. Don't extend these types as they must match the OSLogType values.
enum MyLogType {
    /// The debug log level.
    case debug
    /// The informative log level.
    case info
    /// The default log level.
    case `default`
    /// The error log level.
    case error
    /// The fault log level.
    case fault
}

/// This overloaded function helps solve a compiler error when using the os_log function with an implicit logType.
/// This will be used in non-debug builds.
func os_log(
    _ message: StaticString,
    file: StaticString = #file,
    function: StaticString = #function,
    line: UInt = #line,
    args: Any...
) {
    os_log(.default, message, file: file, function: function, line: line, args: args)
}

/// This will be used in non-debug builds.
func os_log(
    _ logType: MyLogType = .default,
    _ message: StaticString,
    file: StaticString = #file,
    function: StaticString = #function,
    line: UInt = #line,
    args: Any...
) {
    let stringMessage = String(describing: message)
    switch logType {
    case .debug: myCustomDebugLog(stringMessage, file: file, function: function, line: line, params: args)
    case .info, .default: myCustomInfoLog(stringMessage, file: file, function: function, line: line, params: args)
    case .error, .fault: myCustomErrorLog(stringMessage, file: file, function: function, line: line, params: args)
    }
}
#endif

Usage will be identical between debug and release builds, e.g.:

os_log(.debug, "This is a log")

Yes, this means you’ll have to replace all those myCustomDebugLog(…) spread throughout your codebase with os_log(…), but this would need to be done only once, and then from then on you’d start using just os_log(…) everywhere.

This will result in good usability with Xcode’s console during development (debug builds), but using your own logging framework in release builds, which may include e.g. logging to multiple destinations, exporting logs to a file, etc.

Conclusion

While OSLog brings much-needed improvements and integrations for Apple's logging ecosystem, it is not a complete replacement for third-party robust logging frameworks like CocoaLumberjack, SwiftyBeaver, XCGLogger, and many others, especially for developers requiring advanced logging features and cross-platform support. But if you’re interested in just improving the DevX and productivity while implementing and debugging features locally, there’s a good middle-ground alternative you may consider!

References

• Debug with structured logging

• Should everyone migrate to OSLog? #1363

• Your Friend the System Log

• Not mentioned in this article but a good read: Exporting data from Unified Logging System in Swift

When I launched Statused, the goal was simple yet ambitious: to streamline communication across various departments involved in app development and deployment. I envisioned a tool where updates on app and build statuses would be just a Slack notification away, eliminating the back-and-forth and the endless wait for emails to come in. This tool would prevent the need for one developer to relay information to the rest of the team. And, thanks to the incredible support and feedback from all of you, Statused has come a long way.

Today, I’m thrilled to share that Statused is expanding its horizons even further. We’re bridging not just communication gaps but also platform ones. That's right - Android support is coming to Statused!

This leap forward means that our Android developer friends can join in on the ease and transparency that our iOS teams have been enjoying. All departments of the company will be on the same page when it comes to the different stages of the app release cycle, without the need for an Android or iOS developer being the middleman of the information.

As this product grows, so does our understanding of how valuable it is to have QA teams, marketing teams, engineering teams, and project managers all on the same page, effortlessly. Statused is not just a tool; it's a meeting ground, a communal space where each department can stay informed and in sync with each stage of the app’s deployment process.

So, to my fellow tech enthusiasts, whether you’re part of a scrappy startup or a tech titan - give Statused a whirl. And to our Android users, welcome aboard! Let’s continue to bridge gaps, one update at a time.

Oh, and we’re on Product Hunt too! Check out our launch there and consider upvoting and providing feedback if you’re keen!

Open Statused for Android launch page on Product Hunt

What is Statused? 💭

If this is your first time here and you haven’t heard about Statused yet, it’s a service that monitors your apps and delivers real-time Slack notifications when Apple & Google review status changes (for example, when you submit it for review or when Apple approves or rejects your app), when there are new TestFlight builds available, and when your app finishes processing.

I launched Statused 2 months ago, in September 2023, and have been receiving great feedback from the community, which helped me improve the service even further 🚀

You can check it out here: https://statused.com

Credits 💪

Huge shout-out to our first customer and friends at Skeelo, an ebook & audiobook subscription service in Brazil. Their help was crucial in providing feedback to improve the tool and service, as well as in helping us test the alpha version of our Android workflows. 🎉

Google’s documentation for creating Google Play credentials can be confusing and hard to follow, specially without visuals. This step-by-step guide aims to resolve that.

Tip: If you see Google Play Console or Google Developer Console in your local language, add &hl=en at the end of the URL (before any #...) to switch to English. All the links below already have this to make it easier to find the correct buttons.

1. Write down your Developer Account ID

Open the Google Play Console, click in Account Details, and write down the Developer Account ID listed there. You’ll use it later.

2. Enable the Google Play Developer API

Before using this API, you must enable it. Open the Google Play Developer API page, select an existing Google Cloud Project that fits your needs, and hit ENABLE. If you don't have an existing project or prefer to have a dedicated one for your current needs (e.g. fastlane, Statused), create a new one here and follow the instructions. I personally like having a dedicated project called Google Play Console Project and use it for all my needs 😊

3. Create a Service Account

1. Open Service Accounts on Google Cloud and select the project you'd like to use.

2. Click the CREATE SERVICE ACCOUNT button at the top of the Google Cloud Platform Console page.

3. Verify that you are on the correct Google Cloud Platform project by looking for the Developer Account ID from earlier within the light gray text in the second input, preceding .iam.gserviceaccount.com, or by checking the project name in the navigation bar. If you realize you don’t have the correct project selected, open the picker in the top navigation bar, and find the right one.

4. Provide a descriptive Service account name, depending on what you intend to use this account for, e.g. “fastlane-supply”, or “statused”, etc.

5. Copy the generated email address that is displayed below the Service account-ID field for later use.

6. Click DONE (don't click CREATE AND CONTINUE as the optional steps such as granting access are not needed):

   

4. Create your API key JSON

After creating your service account, you’ll end up in a page that shows the list of your service accounts. Next:

1. Click on the Actions vertical three-dot icon “⋮” of the service account you just created.

2. Select Manage keys on the menu.

3. Click ADD KEY → Create New Key.

4. Make sure JSON is selected as the Key type, and click CREATE.

5. Save the file on your computer when prompted and remember where it was saved at.

5. Invite your service account to your Google Play Console

1. Open the Google Play Console and select Users and Permissions.

2. Click Invite new users.

3. Paste the email address you saved earlier into the email address field.

4. Make sure App Permissions tab has no apps in there.

5. Click on the Account Permissions tab.

6. Choose the permissions you'd like this account to have. This will depend on the purpose of the account you’re creating.

   1. For fastlane, I recommend Admin (all permissions), to avoid permission issues down the road. If you feel adventurous, you may want to manually select some checkboxes and leave out some of the more permissive Release permissions such as Release to production, exclude devices, and use Play App Signing. Of course, this means your API key won’t be able to release to production programmatically, so you’ll have to do it manually, likely via the Google Play Console website.

   2. For Statused, the only permission you’ll need is View app information and download bulk reports (read-only). This makes this API key more secure, as it’s read-only, which is enough for the access that Statused needs. It should look like this:

      

7. Click on Invite User.

Validating your API key access

You’re done creating and configuring your API key, congrats! Next, we should verify whether everything is working as expected.

If you're configuring an API key for Statused, you can simply upload your key and the system will validate the key for you.

If you’re going to use it for fastlane, there’s an action to validate your key:

bundle exec fastlane run validate_play_store_json_key json_key:path/to/your/api/key.json

Keep in mind that this action will only validate whether your key can connect to the API successfully, but not whether it can access your apps to manage them. To check whether you configured your key correctly to access your apps, you’ll need to run one of the fastlane supply actions. If it’s not configured correctly, it will raise the following error:

FastlaneCore::Interface::FastlaneError (Google Api Error: Invalid request - The caller does not have permission)

Conclusion

After following this step-by-step guide, you should be up and running with your Google Play API key, ready to use it to manage your releases, upload builds, update metadata, and even monitor your phased rollout distribution percentage if you’re using Statused.

If you’re still experiencing issues after following this guide, don’t hesitate to reach out! I’ll do my best to improve this guide to make it easier for everyone moving forward!

References

Official documentation by Google

How it all started

Circa 2020, I was leading an iOS project involving multiple teams, such as design, marketing, and a dedicated QA team. As a startup, the work was fast-paced, and we shipped often. However, on every app release, the following would happen:

• I was asked whether the app was already live or not, by the project manager;

• The QA team wasn't sure when the app was ready to be tested on TestFlight;

• The marketing team didn't know precisely when a specific version of the app was released to the App Store so they could track the impact and effectiveness of onboarding and SEO changes in the app;

• When the app got rejected for a silly reason, we would often only realize hours later. The weight was on the iOS team to identify the rejection and inform the rest of the team so we could fix it and resubmit the app.

These issues were not only frustrating but also time-consuming. I was spending a lot of time on Slack, answering questions and providing status updates.

If the entire team had visibility into the app's status, these issues would be solved. I started looking for a tool that would provide this visibility. Still, at that time, Apple was migrating their APIs from iTunes Connect to App Store Connect, so most of the tools I found were outdated or didn't provide the information I needed. So I decided to build my own tool during my free time.

The first version of this tool was released in August 2020, and it was a simple script that would poll the app's status from App Store Connect and post a message on Slack when the app or build status changed. It was a simple solution, but it solved our issues, and the team loved it. At that time, I ran the tool locally on my machine, so I kept it running 24/7 (yeah, tell me about it!).

I open-sourced the tool, which got some traction on GitHub. I was happy that other teams were also using and contributing to it, and this led me to invest more time on it.

One of the pain points was setting it up and, of course, running it locally on a machine 24/7 wasn't ideal. Hosting it on the cloud has costs, so I wanted to create a SaaS version of the tool. But I never really pursued it because it would require knowledge in areas I wasn't familiar with, such as web dev and cloud infrastructure…

Until recently!

How it's going

I took the leap and invested time and money to build a SaaS version of the tool. I'm still learning a lot, but I'm enjoying the process. I must admit that web dev is not my favorite thing, but I'm learning a lot and happy to see the tool come to life.

The tool supports registering multiple App Store Connect accounts, apps, and Slack channels.

You can check it out here: https://statused.com

What's next

If this tool is helping you and your team, consider subscribing to the SaaS version. This will help me cover the costs of hosting and development, and it will also help me prioritize new features and improvements.

If this service starts to get traction, I'll be able to invest more time in it, and I'll be able to add more features such as:

• Support for more platforms such as Google Play;

  • UPDATE: As of Nov 9, 2023, Statused fully supports monitoring Google Play Store to notify you about the status of your Android apps! Check it the integration docs here.

• Support for more notification channels such as Discord, Telegram, Microsoft Teams, and email;

  • UPDATE: As of Jan 13, 2025, Statused supports custom webhooks, which allows you to trigger custom workflows but also integrate with any tool that supports it - such as Discord, Telegram, Teams. Check out the documentation for more details.

• Provide metrics and insights about your app releases.

But I also would love to hear your ideas! If you read this story and thought about something cool that would help you and your team, feel free to reach out to me at roger@statused.com 🤗

I hope this tool helps your team as much as it helped mine!

Oh, and we’re on Product Hunt too! Check out our launch there and consider upvoting and providing feedback if you’re keen!

Go to Statused launch page on Product Hunt

Nearly every mobile project will ship with secrets like API keys from services, webhook URLs, or maybe even some specific seed data you need. Choosing where to store them properly is key (pun intended), as it could potentially cause your company to go bankrupt over a leaked API key that earns a massive bill. Yes, that’s the worst-case scenario regarding billing, as it’s the case with e.g. the Google Maps SDK API key if you haven’t restricted its access to your app domain only.

In backend and web frontend projects, it’s a common practice to store your keys locally in .env files and load them from env vars in CI. But for mobile, I think that not enough importance is given to storing your keys away from your codebase in plaintext or — worse — in your Info.plist.

Some businesses offer remote secret management services so that you can fetch your secrets from their API during runtime. But some services can’t wait for you to fetch API keys from another service. Sometimes you need them right away during the app launch. Also, depending on how those services implement their authentication, you’ll have a local API key anyway, so you’ll need to think about how to store that, too.

Another way is to obfuscate your app secrets locally.

Enters Arkana

Arkana is an open-source project I created to obfuscate the secrets used in your codebase.

Arkana uses code generation to provide your app with its secrets. Secrets are fetched from env vars during Arkana runtime (not your app’s runtime), their values are encoded using a salt generated on each run, and source code is generated using the provided keys and the generated encoded values.

During your app’s runtime, the encoded value is decoded so your app can use the values initially stored in your env vars.

This encoding mechanism makes it difficult for attackers to read your secrets in plain text from your app’s binary (for instance, by using unix strings or other tools like stefanesser/dumpdecrypted and Yelp/detect-secrets).

Arkana supports Xcode projects (iOS/macOS) and works with Swift Package Manager, CocoaPods, and local CocoaPods (aka Development Pods). Although it was built with Android support by design, it doesn’t support Android projects just yet.

FAQ

I’ve written more about this project FAQs on its page itself, so you might want to check it out directly:

• How can I install Arkana?

• How should I use Arkana?

• Is this safe?

• Why not cocoapods-keys?

• Why not a CocoaPods Plugin?

Conclusion

Arkana has helped me immensely, and nowadays, I don’t start new projects that need secrets without it. Setting it up takes a few minutes, and it will pass security audits from rigorous top-tier cybersecurity companies (yup!). If you think your company’s app secrets are not so safe, perhaps it’s time to bring this up with your team. 💪

We’re waiting for an eager, community-driven Android contributor to open a PR ✨ to say we officially support both platforms. If that’s you, we can start discussions here. 🤗 If you know someone who could help, I’d love for you to share this project with them!

Emerge is a service that provides lots of tools to improve your app in many different ways, like reducing the app size, improving launch and runtime performance, identifying dead code in your codebase during runtime, and more.

If you’re fortunate enough to be using Emerge in your pipeline, you’ll notice that some features are only possible if you submit your linkmaps to them. A linkmap file is defined as a map file which details all symbols and their addresses in the output image.

The official documentation from Emerge shows where you should put your linkmap, but here we’ll go over detailed instructions on how to achieve that.

Enable linkmap generation

Linkmap generation is disabled by default on Xcode, so we have to enable it. Xcode has the LD_GENERATE_MAP_FILE build setting, defined as:

Activating this setting will cause the linker to write a map file to disk, which details all symbols and their addresses in the output image. The path to the map file is defined by the Path to Link Map File (LD_MAP_FILE_PATH) setting. Defaults to NO.

If you set your build settings via Xcode, search for LD_GENERATE_MAP_FILE (or Write Link Map File) in Xcode’s Build Settings and set it to YES. But if you configure your build settings using config files like me, open your base .xcconfig file and set:

LD_GENERATE_MAP_FILE = YES

Next, there’s the LD_GENERATE_MAP_FILE build setting:

This setting defines the path to the map file written by the linker when the Write Link Map File (LD_GENERATE_MAP_FILE) setting is activated. By default, a separate file will be written for each architecture and build variant, and these will be generated in the Intermediates directory for the target whose product is being linked.

Defaults to $(TARGET_TEMP_DIR)/$(PRODUCT_NAME)-LinkMap-$(CURRENT_VARIANT)-$(CURRENT_ARCH).txt

I recommend customizing the path where the linkmaps are generated, so you can easily find them later (we’ll need it):

LD_MAP_FILE_PATH = $(SRCROOT)/.build/Linkmaps/$(PRODUCT_NAME)-LinkMap-$(CURRENT_VARIANT)-$(CURRENT_ARCH).txt

You can also set that value via Xcode’s Build Settings panel if you prefer.

If you decide to customize your LD_MAP_FILE_PATH, you will also need to make sure its directory exists prior to building your app, otherwise the linkmap files won’t be generated. You can do this as part of your build pipeline, e.g. by adding a new Run Script to your Build Phases, or adding a step in your CI scripts, like fastlane.

Note: some projects might generate multiple linkmaps, and others might generate just one, and that’s expected.

Attaching your linkmaps to .xcarchive

Emerge requires you to submit your linkmaps to the .xcarchive file you upload to them, like this:

├── MyApp.xcarchive
│   ├── Info.plist
│   ├── dSYMs
│   │   └── MyApp.app.dSYM
│   ├── Products
│   │   └── Applications
│   │       └── MyApp.app
│   └── Linkmaps
│       └── MyApp-LinkMap.txt

Let’s see how that would look like, via fastlane:

# In your `fastlane/Fastfile`

SRCROOT = File.expand_path("..") # Adjust this accordingly to your project's structure
LINKMAPS_DIR = File.join(SRCROOT, ".build/Linkmaps")

lane :archive do
  …
  FileUtils.mkdir_p(LINKMAPS_DIR) # This directory must exist before building your app
  build_app(…) # Code that will build your app
end

lane :distribute do
  distribute_to_emerge
  distribute_to_app_store
end

private_lane :distribute_to_emerge do
  attach_linkmap_to_xcarchive
  emerge(…) # Code that will upload your .xcarchive to emerge
end

private_lane :attach_linkmap_to_xcarchive do
  xcarchive_path = Fastlane::Actions.lane_context[Fastlane::Actions::SharedValues::XCODEBUILD_ARCHIVE]
  source_dir = LINKMAPS_DIR
  destination_dir = "#{xcarchive_path}/Linkmaps"
  FileUtils.cp_r(source_dir, destination_dir, remove_destination: true)
  UI.success("Copied linkmaps to xcarchive: #{destination_dir}")
end

Conclusion

In this article you learned what linkmaps are, how to generate them, and how to send them to Emerge. These are needed to enable certain features from Emerge.

If you still don’t use Emerge in your projects, you can sign up here.

Subscribe to this publication to be notified when more articles come out :)

Subscribe now

If you catch yourself in need to run Xcode 14.3 under Rosetta via the UI, check out this awesome article made by @sarunw: https://sarunw.com/posts/open-using-rosetta-in-xcode-14-3

Now, if you’re looking to run Xcode 14.3 under Rosetta via CLI (using xcodebuild), you need to use the same trick that was used to run macOS apps:

xcodebuild -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 14 Pro,arch=x86_64' clean build test

In other words, simply append ,arch=x86_64 to your destination argument.

And if you’re using fastlane, since 2.113.0 you can pass this argument to fastlane scan CLI:

bundle exec fastlane scan --clean --workspace MyWorkspace.xcworkspace --scheme MyScheme --device "iPhone 14 Pro" --run_rosetta_simulator

Or add the same argument to your scan action in your Fastfile:

desc "Runs all the tests"
lane :test do
  scan(
    workspace: "MyWorkspace.xcworkspace",
    scheme: "MyScheme",
    device: "iPhone 14 Pro",
    run_rosetta_simulator: true,
  )
end

Conclusion

Since Apple enforced Xcode 14.1 to be installed as of late April, when Xcode 14.3 was already available, many of us saw ourselves upgrading to Xcode 14.3 straight away, instead of going through 14.1 or 14.2. For those of you who don’t support running Xcode builds (and simulator runs) on native Apple Silicon, these config changes will be needed when running on Xcode 14.3.

I think that embedding a build status badge to your project’s README file is one of the first things you do after you set up your CI and get a running build for the first time. It’s such a small detail but gives so much confidence to whoever’s viewing your project, that the main branch is green, all tests and checks are passing, etc. This is even more important in open source projects.

But in case your project is closed-source and/or at least your Jenkins instance is, you’re gonna have a hard time understanding how to achieve this. Although there’s a plugin that offers the badges itself, the badges alone aren’t going to help if to view the badge image, you need to enter a username and password 😅

This article shows you how to have the badge image provided by Jenkins to become fully public, while keeping the rest of your Jenkins safe and private.

Preparing the ground

1. Install these plugins:

   • https://plugins.jenkins.io/embeddable-build-status

   • https://plugins.jenkins.io/role-strategy

2. Navigate to “Manage Jenkins” → “Configure Global Security” → Set "Role-Based Strategy", if you haven’t already.

   1. If you’re setting this up for the first time, beware that you’ll have to set up role-based permission strategy for your entire team. Until you do so, once you enable this setting, your entire team will lose access to Jenkins and only your current (admin) account will have access.

3. Now that you installed and enabled role-based permissions, the plugin can be configured from “Manage Jenkins” → “Manage and Assign Roles”.

Configure a new public role to view badges

Under the “Global roles” section, add a new role (e.g. “Public”) and check the "Job ViewStatus" checkbox as its only permission:

Then scroll down to the “Item roles“ and create a new role (e.g. “View Status Badge Permission“), setting the name of your Jenkins Job in the “Pattern” field, and check the “Job Read” permission:

Don’t forget to hit the “Save” button at the bottom of the page, before continuing.

Then, navigate to “Assign Roles” view in the left menu, and check both checkboxes: “Anonymous → Public” and “Anonymous → View Status Badge Permission” that you just created:

Again, don’t forget to hit the “Save” button at the bottom of the page to make sure your changes are persisted.

Getting the badge image URL

Navigate to the Job that you want to display badges for. In my case, that’s under job/protected-branches-multibranch-pipeline/job/master, and then click on the “Embeddable Build Status” menu in the left menu:

That should take you to a page with preformatted options for your badge, e.g. in markdown, HTML, etc. Use the “unprotected” ones in your README file (or wherever you’re going to display them).

Conclusion

With the setup seen in this article, you’ll open up your build status to be seen by the public (with no authentication whatsoever), and only that. The rest of your Jenkins jobs, builds, code coverage, reports, artifacts, etc, will all remain behind user authentication.

As an engineer and avid programmer, you’re always identifying patterns in everything you see, so if you face something like this:

enum Direction {
    case left, right, up, down

    var icon: UIImage {
        switch self {
        case .left: return UIImage(named: "ic-left")!
        case .right: return UIImage(named: "ic-right")!
        case .up: return UIImage(named: "ic-up")!
        case .down: return UIImage(named: "ic-down")!
    }    
}

Your OCD is triggered and your hands start shaking immediately. “I MUST refactor this code to simplify it! Let’s factor out the similar logic, and make everything much simpler!”

enum Direction: String {
    case left, right, up, down

    var icon: UIImage {
        return UIImage(named: "ic-\(rawValue)")!
    }    
}

Ahhh, much better! I just improved this code so much!

Let’s understand below why this is not a good idea when scaling your codebase.

For the purposes of this article, “dynamic strings” refer to any string value that can’t be represented as a StaticString, i.e. text that isn’t known during compile time. This includes strings composed by string interpolation, string concatenation, and using string variables.

1. Unfortunately, UIImage initialization isn't very safe in iOS

Due to the fact that we’re force unwrapping the UIImage initialization above, if anything goes wrong when initializing that image, that code would crash. This could happen when introducing a new enum case, for instance: the developer adding the new enum case could easily miss the fact that the icon computed variable is using the enum’s raw value to initialize (and force unwrap) an image, and forget to add its associated image to the project’s xcassets resource folder, resulting in a crash.

When opting for the explicit initialization of each image (the first snippet), the developer would get a compile-time error when they add a new enum case, which would force them to think about how to handle it, and thus add the image resource to the project.

2. Tools that identify unused resources aren’t as effective

There are amazing tools out there like LSUnusedResources that help you identify and delete unused assets in your project. However, these tools will most likely use regex expressions to search for usages of your assets in your codebase, and if you disguise your UIImages using string concatenation, interpolation, or other forms of dynamic strings, it clearly won’t find them and thus wrongfully mark them as unused assets. If you blindly trust the tool (something you shouldn’t be doing anyway) and delete those assets, you’ll get runtime crashes the next time you run your app and try to access those assets.

3. Developers looking for usage of assets won’t find them

A curious developer sees those assets named ic-down, ic-left, etc… and thinks:

— I wonder where they’re being used?

He then searches for "ic-down”, “ic-left”, etc… but can’t find anything other than the asset itself. No use cases.

He has two options now: prematurely conclude that they’re not being used and delete them (which would be the wrong thing to do), or try searching for substrings (randomly), such as “left” (which would earn hundreds of unrelated results), or try to narrow them down by searching for “ic-” (again, potentially hundreds of unrelated results), or “-left” (potentially no results, in our example). This developer now has to guess what the developer who originally implemented the code was thinking and how they decided to implement the code that accesses these assets. Frustrating, right? Not to mention it’s unproductive. Not the best DevX.

4. Refactors become a nightmare

Scenarios 1 and 3 can happen in isolation, but those scenarios become particularly more critical and recurring when the project needs to undergo some sort of refactor, be it an architecture change, or a file structure re-organization, simply refactoring files from UIKit to SwiftUI, or from Objective-C to Swift, etc. Each change you make you need to be more careful, double and triple check your changes, double down on review, double down on manual exploration testing (the most expensive type of tests), just to ensure that everything will go out smoothly. Whereas, if the project (and the team) followed the convention of never initializing images using dynamic strings, certain refactors would be a lot smoother.

Needless to say I’m a big fan of codebase standardization, consistency, and Convention Over Configuration. 🤓

Meta-programming kicks in

Of course. I couldn’t write this article without mentioning meta-programming, and amazing developer tools like SwiftGen and Sourcery.

Meta-programming helps not only reduce the pain of manually writing out boilerplate code, but in this case the most important benefit is making your images compile-time safe. Without digging into its implementation detail (there are a bunch of articles explaining just that e.g. the official one from SwiftGen, this one from Kodeco (former Ray Wenderlich) and this other one), your code could become something like this:

enum Direction {
    case left, right, up, down

    var icon: UIImage {
        switch self {
        case .left: return UIImage.Icons.Direction.left
        case .right: return UIImage.Icons.Direction.right
        case .up: return UIImage.Icons.Direction.up
        case .down: return UIImage.Icons.Direction.down
    }
}

And, in case anything goes wrong with your asset clean up or refactor, your code won’t compile anymore and you will know exactly where things went wrong. Typos in asset names will be a thing from the past, and developers can easily find where the assets are being consumed (in the generated files, by searching like they normally would).

Exceptions

My image identifiers come from the backend, and my images are stored locally

Here I’d say it depends on the quantity. I would probably avoid having backend-driven image identifiers and locally-stored images if possible, but if that’s not the best approach for your project, I’d probably still declare images explicitly (without using dynamic strings) if there’s a reasonable number of images to be mapped. If there are thousands of them, then probably not. 🙃

It’s too complicated to use meta-programming

Believe me, it’s not! But, of course, if you’re an indie developer bootstrapping a pet project, or if it’s a small project with 10-20 images, it’s okay to declare them using string literals. But as the project grows, the advantages of having your image references compile-time safe start to stand out.

Conclusion

Keeping your image initialization code static has multiple benefits:

• Code safety

• Smoother usage of tools that identify and clean up unused assets

• It’s more productive to have your codebase follow a single standard, contributing to your team’s DevX

• Keep your future self (or colleagues) sane, by making refactors easier

If you or your team is still using dynamic strings in your codebase, consider if that’s really the best approach for your project. Maybe you’ve already faced some of the issues highlighted in this article.

And if you have legitimate use cases to initialize UIImages using dynamic strings, reach out to me on @rogerluan_, I’d love to learn more!

Subscribe now

Over the course of years, I worked closely with deep links, facing many different issues. Some of those issues were reported repeatedly as they could be sometimes user error, or lack of support in certain 3rd party apps. As I learned from these mistakes, I put together this page with links to articles and documentation that helped me solve common setup issues and also recurring ones — even when the issue could be tied to a user’s device specifically.

The links below are mostly from Branch and AppsFlyer, two of the most popular deep link providers, but that doesn’t mean that each resource applies only to their respective services or SDKs. In fact, most of them are independent of the service and apply to deep links in iOS in general, while some even apply to Android deep links as well.

Disclaimer: for the purpose of keeping the lingo simple, I’ll use “Universal Link” and “deep link” interchangeably in this article. Universal Links are Apple’s brand name for what’s popularly known as “deep links”, while Google calls theirs “App Links”. Deep links can also be interpreted as those app-specific URL schemes like “whatsapp://”, but popularly most people generalize and call those, as well as Universal Links and App Links as simply “deep links”.

Troubleshooting Deep Link Issues

• Branch - iOS Troubleshooting: Must-read resource on how to solve common deep link issues (Branch-specific, or not). Contains potential solutions to problems that include (but are not limited to):

  • App not opening when using deep link.

  • App not passing data when using deep link.

  • Deferred deep linking not working.

  • How to re-enable Apple Universal Links.

  • Determining if deep link is from Branch or not (without network connection).

• Branch - Apple Universal Links

  • Explains how Universal Links work.

  • Lists examples of known apps that might not support deep links very well, e.g. Chrome, Facebook, WeChat, Twitter, LinkedIn, Instagram, Pinterest, etc.

  • Contains other valuable troubleshooting FAQ that are not included elsewhere.

• Branch - Deep links do not open the app

  • Explains great examples of why your deep links might not be opening the app. Definitely a must-read.

• Branch - Viewing deep link data

  • Example specific to Branch on how to view deep link data: simply add ?debug=1 to the end of your deep link. (Works for Branch’s deep links only)

• Branch - 3 Steps to Troubleshoot iOS 9 and iOS 10 Universal Links

• AppsFlyer - OneLink troubleshooting and FAQ: This is a great resource for troubleshooting OneLink issues, including (but not limited) to answering these questions:

  • Which method should I use for opening apps — Universal Links, App Links, or URI schemes?

  • Which operating systems allow URI schemes to open the app?

  • Do I need to update the app after iOS Universal Links and Android App Links setup?

  • Can I redirect existing users to a web page instead of the app?

  • Can I redirect tablet users to a different app or URL then mobile app users?

  • Can I assign an app to multiple OneLink templates?

  • Can I delete a OneLink template?

  • Can I change the subdomain in a OneLink template?

  • Can the domain/subdomain of a OneLink template be applied to the template ID of another template?

  • Can I use the same subdomain for more than one template?

  • How can I redirect desktop users?

  • How can I redirect Chrome OS users?

  • Does OneLink work without the AppsFlyer SDK?

  • What methods are available for creating OneLink custom links?

  • Can OneLink custom links open the app from a browser?

  • Why doesn't the OneLink URL open the app or deep link existing users?

  • Why does my OneLink URL open a blank page in Chrome?

  • Can I use OneLink for redirection on Brave?

  • Do OneLink custom links take longer to load than other links?

  • How can I record the cost per install when using OneLink?

  • How can I prevent parameter forwarding on redirections?

  • Are single-platform custom links still available?

  • Can I change the short URL ID after saving a link?

  • Can I wrap and shorten OneLink (or deep links)?

  • Can I use OneLink (or deep links) in emails?

  • How do users get redirected to their regional app store?

  • Why isn't my OneLink URL redirecting users to the specified domain?

  • What parameters are mandatory for OneLink custom links?

  • Can parameters be appended to the short URL?

  • What custom media source names can I use?

  • What attribution parameters can be added to a OneLink?

  • Are custom parameters added to OneLink custom links available in raw data?

  • Are parameter names case sensitive?

  • Can I use deep links in social apps (unpaid)?

  • Can I use deep links with ad networks (paid)?

  • How can I solve the iOS app-launching issue from social media apps?

  • Can I use deep links on Instagram?

  • Can I use deep links for redirection on WeChat?

  • Why are Android users with the app installed being redirected to a web URL and not into the app when they click a link on Facebook webview?

  • How can I A/B test the Social app landing page?

  • How can I bypass the app selection dialog?

  • What deep linking methods should be implemented?

  • Can a URI scheme (af_dp parameter) be used for deep linking?

  • Does OneLink deep linking work for iOS 14?

  • Does OneLink deferred deep linking work for iOS 14?

Deep Link Developer Documentation

• AppsFlyer - iOS Unified Deep Linking

  • Has a super helpful visual diagram of how deep linking works on iOS, and explains some implementation details.

• Branch - Create Ad Links

  • Explains how Ad Links should be created.

• Branch - Universal Email Integration Guide

  • Thorough guide explaining how to integrate Branch's Universal Email solution with your Email Service Provider (ESP).

  • If you're using Iterable as your ESP, a must-read is Iterable - Deep Links Setup.

Understanding Deep Links Concepts

• Branch - Deterministic Matching

• Branch - Predictive Modeling

• Branch - Probabilistic Modeling

• Branch - SKAdNetwork

  • Explains how SKAdNetwork works, in particular with Branch.

  • Contains lots of helpful tables and a visual diagram of how SKAdNetwork works.

• AppsFlyer - Making sense of Universal Links and App Links

• Branch - Best Practices to Secure User Opt-In on iOS 14

• Branch - A Marketer-Friendly Guide to SKAdNetwork Conversion Values

• Branch - NativeLink and App Clips: Solving the Deferred Deep Linking Challenges of Private Relay

• Branch - Glossary

  • An extensive glossary on common terms used around the industry, engineers, and marketers.

• AppsFlyer - Glossary

  • A mobile marketing glossary featuring must-know industry terms, topics, and concepts to help you keep up.

App Tracking Transparency Prompts

When the subject is deep links, we’re often associating them with ad attribution, thus, App Tracking Transparency requests. I found this very useful resource that shows examples of prompts that other apps are using in the wild. Definitely worth checking out if you show this prompt to users:

Status Pages of Deep Link Services

Sometimes Branch and AppsFlyer go down. This causes issues creating deep links (which would impact your BE if you’re creating them through their API), resolving deep links (or their parameters) in the app, and so on. If you identify an uncommon issue, check if the services are up and running:

• https://status.appsflyer.com

• https://status.branch.io

Online Deep Link Validators

Online deep link validators check if a given URL is properly set up for Universal Links (iOS) and App Links (Android). This allows you to check if the apple-app-site-association and assetlinks.json on a website is properly formatted for deep links as defined by Apple and Google, respectively.

• https://branch.io/resources/aasa-validator - iOS only.

• https://www.appsflyer.com/tools/link-validator - Android and iOS.

• https://yurl.chayev.com - Android and iOS.

In this new “Later” view, that has been rolling out since March 2023 according to their announcement, you have three tabs:

• In progress: for all reminders that are still pending and haven’t been marked as completed yet. This includes overdue and upcoming reminders.

• Archived: for messages you had previously marked as “bookmarked”. Slack actually merged two features into the “Later” feature: the “Slackbot Reminders” and the “bookmarked” messages.

• Completed: for reminders you marked as completed.

You can also quickly create a new reminder by clicking the “New reminder” button at the top right corner of the page. I believe this wasn’t possible via UI before, you had to write a command in Slack like “/remind remind me to review all open pull requests by 5pm“, so for those of you who are not used to the command proper syntax/format, having this feature readily available in a visual interface should be really helpful and lower the barrier of entry for users that still don’t use Slack reminders.

Why would I manage tasks/reminders within Slack? Why not a proper project management tool like Jira, GitHub Projects, Trello, etc?

If you’re curious as to what are the use cases that justify using Slack Reminders, check out my other blog post where I fully utilize Slack features and share some tips & tricks to become a Slack super user:

Conclusion

I think this is an exciting new feature to use within Slack, and I can’t wait for it to become available to everyone. I believe it provides a clearer view into what’s overdue and what’s next, by properly displaying the reminders by due date, helping us prioritize them.

It’s 2023 and you and your team decided to move away from the current CI provider you have, towards a self-hosted Jenkins CI. Great! In this article we won't cover the pros/cons of using one CI system against another, but rather be laser focused in showing how to set up a fully working Jenkins CI environment for iOS.

Although you can probably get an environment up and running in a couple hours by discovering Jenkins on your own, and even be able to run an iOS build on it, there are lots of small issues that compound over time and make such naive implementation quite unsustainable.

I did a lot of experimenting, and struggled for a few weeks to get everything right, specially after getting multiple cryptic errors alongside issues that would happen “every once in awhile”. After surprisingly not finding a comprehensive guide on “Jenkins best practices”, I decided to put this one together to share knowledge I learned the hard way. 🥲

Preconditions

I won’t be covering the steps needed to get yourself a macOS machine. This article assumes you have a bare metal machine running macOS (yes, macOS is required), and that you have already installed Jenkins in your machine. If you haven’t installed Jenkins yet, here’s the official guide (this step is straightforward): https://www.jenkins.io/doc/book/installing/macos

Furthermore, in this article we’re going to be using Homebrew, rbenv, xcodes, and Bundler. I won’t go into details as to why I recommend each one of these (maybe in a future post 😉), but feel free to reach out to me if you’re curious!

Installing dependencies

First and foremost, we need to install Homebrew. You should follow the instructions in this link — it’s quite straightforward.

Updating your ~/.zshrc file

These settings should get you up and running more easily, and features a security measure for fastlane. Append this to your ~/.zshrc file:

# Initialize rbenv if it's already installed
export PATH=$PATH:/usr/local/bin:$HOME/.rbenv/bin:$HOME/.rbenv/shims
if which rbenv > /dev/null; then
  eval "$(rbenv init -)"
fi

# Set these according to your project's needs/configuration
export XCODE_VERSION="14.3"
export BUNDLER_VERSION="2.2.32"
export RUBY_VERSION="3.1.2"

# For security measures, ask fastlane to not store your fastlane password.
# Even though your CI workflows and scripts probably doesn't even use App Store Connect User+Password anymore, if you happen to run fastlane manually in the CI machine, you don't want it to accidentally store your own Apple ID password in its Keychain.
export FASTLANE_DONT_STORE_PASSWORD="1"

# Required by fastlane (to prevent issues with unicode)
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
export LANGUAGE=en_US.UTF-8

Note that depending on which cloud provider you’re using (e.g. AWS, Azure, etc), your existing ~/.zshrc file might already have some content in it, thus, simply append the snippet above at the end of the file, to avoid issues.

After updating your ~/.zshrc file, source it to apply the changes (or kill your SSH session and start a new one):

source ~/.zshrc

Then, you can copy and paste this snippet in your Terminal to get your dependencies set up more easily:

echo "Installing rbenv and the right ruby version that your project uses"
brew install rbenv ruby-build
rbenv install $RUBY_VERSION
rbenv global $RUBY_VERSION

echo "Speeding up gem installs"
echo "gem: --no-document" >> ~/.gemrc

echo "Initializing rbenv (will run the initialization code that we just saved in the ~/.zshrc file)"
source ~/.zshrc

echo "Installing bundler"
gem install rubygems-update
gem update --system
gem install bundler -v $BUNDLER_VERSION

echo "Installing xcodes"
brew install xcodesorg/made/xcodes

echo "Installing the Xcode version your team uses"
echo "Note that this one is gonna take a long while (maybe 10-20 minutes). Take a break, and once it's, done you're gonna need to enter the sudo password so the installation completes"
brew install aria2
xcodes install $XCODE_VERSION --experimental-unxip --select --update

Configuring your git credentials

For this step, I wrote a dedicated article. Pause reading this article and follow the instructions on this other article to get your git credentials configured in your Jenkins machine:

roger.ml

Authenticating with GitHub on Jenkins CI using a GitHub App

This guide is targeted to users who want to use a GitHub App to perform GitHub authenticated requests (such as cloning repos, pushing commits, opening PRs, listening to events, updating GitHub Checks, etc) from within Jenkins. Why a GitHub App? Why not a shared bot account…

Read more

3 years ago · Roger

Configuring Jobs

There is a race condition in how Jenkins picks up which branches to build when using different strategies to “discover” branches (i.e. “Exclude branches that are also filed as PRs” VS “Only branches that are also filed as PRs”). This causes problems like PRs being stuck in a forever “pending” state, thus blocking them from being merged. For this reason, we are going to need 2 Job pipelines:

• One will build all branches that aren’t intended to be filed as PRs, e.g. main, master, develop, staging, production (depends on how you call them).

• Another to build all the other branches, that may become PRs.

Took me a really long time to figure this out, as about 5-10% of the times the PRs would get stuck and become unable to get merged because they fell in some weird state. This was the only fully working solution I found to this problem.

Configuring the Job that will build all branches that won’t become pull requests

Go to https://<your_jenkins_domain.com>/view/all/newJob to create a new job. Choose Multibranch Pipeline from the options:

I like appending the project type (in this case, Multibranch Pipeline) to the pipeline name, so I know which structure it uses, just by the name. Thus, in this case I’d name it something like protected-branch-multibranch-pipeline 😊

When setting things up for this Job, these are the key settings you need to follow:

• GitHub Credentials: select the GitHub App Credentials you added in the “Configuring your git credentials” section above.

• Add a new behavior “Discover branches” and select “All branches”.

  • Add a “Filter by name (with regular expression)” filter under this section, with the text “master” or “(master|staging|production)”

• Periodically if not otherwise run: ☑️

  • Interval: 1 minute.

  • Honestly this one comes from a time where Jenkins wasn’t always picking up the builds it needed to run. But it was in the very beginning of the process, before I even use GitHub App, so I’m not sure whether this one can be turned off. Possibly.

All the remaining settings not mentioned above are up to you to decide how to fill (e.g. are specific to your project, or tastes).

👋 Before continuing, a quick announcement!

Statused notifies your team automatically when your app changes status on App Store Connect or Google Play — submitted, approved, rejected — even pending contracts.

I built it as an indie dev to solve this exact pain. It’s like having the webhooks Apple & Google never gave us.

→ Try Statused – dev teams are loving it!

Configuring the Job that will build pull requests

Visit https://<your_jenkins_domain.com>/view/all/newJob again to create a new job, and choose Multibranch Pipeline from the options. Again, I’ll recommend naming it something like pull-requests-multibranch-pipeline, so you can easily identify it in the future.

Follow the same steps as above, except the behavior you’re going to add is “Discover pull requests from origin”, selecting the strategy as “The current pull request revision“:

Configuring your Jenkinsfile

You didn’t think I’d skip the most critical part, did you?

In the steps above, when configuring a new Job, you had to select the path of your Jenkinsfile. The way of setting up Jenkins explained in this article has to be matched with a particular way to configure your Jenkinsfile and your CI scripts, so I’ll cover them below.

Here’s a template you can use for the main Jenkinsfile, which can be used to run both protected-branch-multibranch-pipeline and pull-requests-multibranch-pipeline:

pipeline {
    agent any
    options {
        ansiColor('xterm') // Adds color to logs, enable via https://github.com/jenkinsci/ansicolor-plugin
        timeout(time: 8, unit: 'HOURS') // Set the timeout limit for builds
        disableConcurrentBuilds(abortPrevious: true) // Cancel the previous build upon pushing newer commits in the same branch
    }
    environment {
        // Set up all your secrets (aka credentials) here, e.g. API keys for fastlane, danger, etc.
        APP_STORE_CONNECT_API_KEY_ISSUER_ID = credentials('APP_STORE_CONNECT_API_KEY_ISSUER_ID')
        APP_STORE_CONNECT_API_KEY_KEY = credentials('APP_STORE_CONNECT_API_KEY_KEY')
        APP_STORE_CONNECT_API_KEY_KEY_ID = credentials('APP_STORE_CONNECT_API_KEY_KEY_ID')
        DANGER_GITHUB_API_TOKEN = credentials('DANGER_GITHUB_API_TOKEN')
        MATCH_PASSWORD = credentials('MATCH_PASSWORD')
        // …etc
    }
    stages {
        stage("1. Set Up") {
            steps {
                withCredentials([usernamePassword(credentialsId: '<team_name>_github_app', usernameVariable: 'GITHUB_APP_USERNAME_TOKEN', passwordVariable: 'GITHUB_APP_PASSWORD_TOKEN')]) {
                    sh '''
                    source ~/.zshrc # Needs to be run to set up the right PATH env var, initialize rbenv, and everything else we configured previously in the ~/.zshrc file

                    # Refs.: https://git-scm.com/docs/gitcredentials#_custom_helpers and https://stackoverflow.com/q/61146986/4075379
                    git config credential.username ${GITHUB_APP_USERNAME_TOKEN}
                    git config credential.helper "!echo password=${GITHUB_APP_PASSWORD_TOKEN}; echo"

                    # From now on you can add your scripts here, e.g. make, bundle install, pod install, xcodebuild build and test, etc.
                    make
                    '''
                }
            }
        }
        stage("2. Static Code Analysis") {
            steps {
                sh '''
                source ~/.zshrc # Yes, unfortunately you need to run this every time you declare a new "sh" shell script in your Jenkinsfile.
                bundle exec rake danger
                '''
            }
        }
        stage("3. Build & Distribute") {
            steps {
                withCredentials([usernamePassword(credentialsId: '<team_name>_github_app', usernameVariable: 'GITHUB_APP_USERNAME_TOKEN', passwordVariable: 'GITHUB_APP_PASSWORD_TOKEN')]) {
                    sh '''
                    source ~/.zshrc
                    bundle exec fastlane archive_and_distribute # This action needs access to GITHUB_APP_USERNAME_TOKEN and GITHUB_APP_PASSWORD_TOKEN env vars directly
                    '''
                }
            }
        }
    }
    post {
        // Always clean your workspace after you finish using it, otherwise after a few builds you will end up with a full disk and your machine will likely die.
        always {
            cleanWs(cleanWhenAborted: true, cleanWhenFailure: true, cleanWhenNotBuilt: true, cleanWhenSuccess: true, cleanWhenUnstable: true, deleteDirs: true)
        }
    }
}

Explaining the “withCredentials” function

The way the “withCredentials” function works is as follows:

// 1st parameter is the name of your GitHub App credentials ID, as you registered in Jenkins.
// 2nd and 3rd parameters are variable names you're declaring now, so you can name them whatever, but you will need to reference them later, so make them relatable.
withCredentials([usernamePassword(
    credentialsId: '<team_name>_github_app',
    usernameVariable: 'GITHUB_APP_USERNAME_TOKEN',
    passwordVariable: 'GITHUB_APP_PASSWORD_TOKEN'
)])

The input is the Credentials ID that you registered earlier in your Jenkins credentials. That gives access to this Jenkins plugin to be able to generate ephemeral tokens (username and password) that can then be used to make HTTPS requests to GitHub. It’s critically important for you to understand that this is a HTTPS auth, and not SSH — so if you have git commands relying on SSH down the pipeline, you should identify that you’re running under a CI environment and switch them to use HTTPS instead. A common example for this, in an iOS environment, is the Git URL used by fastlane match.

The first time we’re generating such ephemeral credentials, we’re exposing them to git config credential.helper, so that any git operation (that uses HTTPS) after that moment (even in other Stages) will be able to run without asking for username and password again. In the example above, you can observe this on Stage 2, where we’re invoking danger (which posts comments to GitHub, so it needs credentials), and we didn’t need to generate new credentials for it. Different from the Stage 3, where we need access to the credentials env vars directly, and the env vars don’t persist from one Stage to another, so we re-generate the credentials, thus, setting values to the env vars again.

If you’re wondering, here’s how you could configure the fastlane match action in your Fastfile:

git_url = is_ci? ? "https://#{ENV["GITHUB_APP_USERNAME_TOKEN"]}:#{ENV["GITHUB_APP_PASSWORD_TOKEN"]}@github.com/myorg/myrepo.git" : "git@github.com:myorg/myrepo.git"

match(git_url: gir_url)

Note 1: you must have the GitHub Branch Source plugin on version 2.7.1 or above to use these APIs. This feature was introduced and announced in 2020.

Note 2: as the announcement states, the API token you get will only be valid for one hour. So don’t get it at the start of the pipeline and assume it will be valid all the way through.

Final touches

There are two remaining things to do before you call it a day for your Jenkins setup journey.

Builds are getting stuck forever

This might happen when your pipeline tries to access git within the pipeline (e.g. when running pod install, or fetching SPMs, etc). It could be caused because your machine is asking for the Keychain password authentication, but that is not surfaced on the Jenkins logs. It’s unfortunate, but the only solution I found to be fully working in this case is to log on the machine with access to the user interface (e.g. VNC, not SSH), and clicking in “Always Allow" in the pop up that shows up asking for permission to access “login.keychain”. Enter the root password of the macOS machine when prompted.

You only need to do this once, then never again.

Xcode git credentials clash with GitHub App’s credentials

There’s an issue that causes builds to fail with error:

stderr: remote: Invalid username or password

This would happen in about 5-10% of the builds, breaking them. Turns out that Xcode’s git credentials may clash with the ones we’re setting and then it breaks. To fix this, simply follow my answer on this Stack Overflow question:

You will need to repeat those steps every time a new Xcode version is installed.

Conclusion

In this (admittedly) long guide, you learned a highly opinionated way to set up your Jenkins machine, tailored for an iOS environment. If you’re working with other environments, the majority of the tips shown in this article will help you get on the right track as well, such as for Android, React, Flutter, Node, etc. What will change is probably just your dependencies, and the specific examples I gave when setting up your Jenkinsfile.

When I initially set up my first Jenkins machine, I got my first build in a matter of hours, but it was far from an environment that would fit the team’s needs. GitHub Checks are definitely a must have for example (something that is not straightforward to set up), and the environment should be 100% stable, with no flakiness, otherwise the CI system won’t be trusted by your team. In other words, I got 80% of the work done very quickly, but the remaining 20% to get a polished CI pipeline took me literally weeks. I hope that by following this guide you won’t have to worry about the environment, and will be able to focus on what matters: building the perfect pipeline for your project, and your team 🤗

In my next blog post, I’ll cover what you can do to preserve the hard work you did to set up your Jenkins machine. To put it simply: how to save a backup of your CI! Stay tuned.

This guide is targeted to users who want to use a GitHub App to perform GitHub authenticated requests (such as cloning repos, pushing commits, opening PRs, listening to events, updating GitHub Checks, etc) from within Jenkins.

Why a GitHub App? Why not a shared bot account?

• The Rate Limit for a GitHub App scales with your organization size, whereas a user based token has a limit of 5000 requests per hour, regardless of how many repositories you have.

• For organizations that enforce 2FA to be enabled, with GitHub Apps there’s no need to manage 2FA tokens for (potentially multiple) bot accounts.

• To improve and tighten security: the Jenkins GitHub App that you will create requires a minimum, controlled set of privileges compared to a service user and its personal access token, which would require a much wider set of privileges.

• Access to GitHub Checks API: GitHub Apps can access the the GitHub Checks API to create check runs and check suites from Jenkins jobs and provide detailed feedback on commits as well as code annotation.

Why not an SSH key?

• It’d also require you to have a bot account with shared credentials across the team.

• Share the same limitations of username + password authentication explained above.

• From experience, Jenkins doesn’t play well with SSH keys, and plugins that work with it are quite buggy.

Why should I trust you?

I spent over 90 hours on trial-and-error process to figure out which authentication method works best, amongst username + password, personal access tokens, SSH keys, and GitHub App. If you’d like to figure out on your own all the reasons why to not use any other auth other than GitHub App, you’re in for a treat! 😉

Getting started

Before you get started make sure you have the required permissions:

GitHub

You'll need the permission to create a GitHub App.

If you're creating it on a personal account, then you can skip this requirement.

If you’re creating it in a organization, you need to be either the organization owner, or have been granted the permission to manage GitHub Apps.

Jenkins

You'll need the permission to create a new credential and update a job’s configuration. The specific permissions are:

• Credentials/Create

• Job/Configure

Creating the GitHub App

Follow the official GitHub guide for creating an app.

The only fields you need to fill out (currently) are:

• Github App name, e.g.: Jenkins - <team name>

• Homepage URL: your company’s website or a GitHub repository.

• Webhook URL: your Jenkins instance, e.g. https://<jenkins-host>/github-webhook/

When setting up the required permissions for your GitHub App for a given repository, set the following permissions:

• Administration: read-only.

• Checks: read & write (so it can update the GitHub Checks in your pull requests).

• Contents: read-only (to read the Jenkinsfile and the repository content during git fetch).

• Metadata: read-only.

• Pull requests: read-only (or read & write if you intend to open pull requests using the bot at some point).

• (Optional) Webhooks: If you want the plugin to manage webhooks for you, then select read & write.

• Commit statuses: read & write.

Under “Subscribe to events”, subscribe to all events, and proceed to creating the GitHub App.

Authenticate to the GitHub App

After creating the GitHub App, you will need to generate a private key to authenticate to the GitHub App. Simply click in “Generate a Private Key” button.

Convert the private key for Jenkins

After you have generating and downloading the private key, you’ll need to convert it into a different format that Jenkins can use with the following command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in key-in-your-downloads-folder.pem -out converted-github-app.pem -nocrypt

👋 Before continuing, a quick announcement!

Statused notifies your team automatically when your app changes status on App Store Connect or Google Play — submitted, approved, rejected — even pending contracts.

I built it as an indie dev to solve this exact pain. It’s like having the webhooks Apple & Google never gave us.

→ Try Statused – dev teams are loving it!

Install the GitHub App to your organization

From the install app section of the newly created app, install the app to your organization. From here you can install the app on all repositories of your organization or in select repositories only. Once installed, you will have configuration options for the app on your selected account.

Add the Jenkins credential

You can add the Jenkins credential via the UI, or using the Jenkins Configuration as Code (a.k.a. JCasC) Plugin.

Via UI

• Navigate to the Add Credentials page in your Jenkins instance

• Fill out the form as follows:

  • Kind: GitHub App.

  • ID: give an identifiable name to this credential (you will use this in your Jenkinsfile to load this credential). Example: “<team_name>_github_app”.

  • App ID: the GitHub App ID, which can be found in the About section of your GitHub app, under the General tab.

  • API Endpoint (optional): only required for GitHub Enterprise.

  • Key: paste the contents of the converted private key from the previous section.

  • Owned (optional): if you've installed your same GitHub app on multiple organizations you’ll need to specify the name of the organization or user this app is going to be used on, e.g. “exampleorganization” for https://github.com/exampleorganization

• Click “Create”

Via Jenkins Configuration as Code (a.k.a. JCasC) Plugin

credentials:
  system:
    domainCredentials:
      - credentials:
        - gitHubApp:
            appID: "1111"
            description: "GitHub app"
            id: "github-app"
            # apiUri: https://my-custom-github-enterprise.com/api/v3 # optional only required for GitHub enterprise
            privateKey: "${GITHUB_APP_KEY}"

Conclusion

After following the steps in this tutorial, you should have a fully working GitHub App that can be used to access your repositories and perform actions on GitHub, such as cloning repos, pushing commits, creating PRs, listening to events, updating GitHub Checks in PRs, etc. In an upcoming tutorial I’ll cover how to use properly use this GitHub App credentials to set up the remaining of your Jenkins pipeline.

Today’s how-to guide will be quite short and simple. If you’re here, chances are you’re running a Debian distro and struggled to find Swift installation steps in Swift’s Get Started official page. Follow the steps below (tested only in Debian 11) to install Swift and be able to run Swift code in your distro:

1. Update your packages:

   sudo apt update

2. Install required dependencies:

   sudo apt-get install libncurses5 clang libcurl4 libpython2.7 libpython2.7-dev

   When being asked if you want to continue, press Y and Enter.
   

3. Download Swift:

   1. Find the Swift version you want to install in Swift.org’s Official Download page. At the time of writing, the latest version available was Swift 5.8, so I went with that.

   2. Right click on x86_64 for the row Ubuntu 18.04 and copy the link. In this case, this is what I got: https://download.swift.org/swift-5.8-release/ubuntu1804/swift-5.8-RELEASE/swift-5.8-RELEASE-ubuntu18.04.tar.gz

   3. Download the tar.gz in your Debian distro:

      wget https://download.swift.org/swift-5.8-release/ubuntu1804/swift-5.8-RELEASE/swift-5.8-RELEASE-ubuntu18.04.tar.gz

4. Extract the downloaded package:

   tar xzf swift-5.8-RELEASE-ubuntu18.04.tar.gz

5. Move Swift’s binary to /opt/

   sudo mv swift-5.8-RELEASE-ubuntu18.04 /opt/swift/

6. Configure your PATH environment variable:

   echo "export PATH=/opt/swift/usr/bin:$PATH" >> ~/.bashrc

   This will modify your ~/.bashrc file to include the path of the Swift executable you just installed.
   
   Apply your changes in your current shell session via:

   source ~/.bashrc

7. Verify if your installation succeeded:

   swift -version

   You should see something like this:

   Swift version 5.8 (swift-5.8-RELEASE)
   Target: x86_64-unknown-linux-gnu

Conclusion

Installing Swift on a Debian server may seem daunting at first, but by following the step-by-step article, you can easily set up a functional Swift environment in no time! 😉

• 🏋️‍♂️ Make it nearly impossible to miss anything important in Slack

• 🦾 Help make you accountable for everything that goes on in Slack

• 🎯 Improve your productivity

When combined, this will make you become a… Slack power user! 🦸‍♂️

This article is divided in 8 main tricks:

1. 🤖 Use Slackbot’s reminders

2. 🗣️ Chat with yourself

3. 📬 Mark messages as unread

4. 🎯 Don't multitask

5. 🧹 Clean up your side bar

6. 🔍 Search

7. 🔕 Limit your surface area

8. ⌨️ Use your keyboard

1. 🤖 Use Slackbot’s reminders

Slackbot is your friend, and friends remind you to do things. In my opinion, Slack's ability to set reminders to yourself is the best tool to avoid dropping messages unanswered.

When to use: when a conversation isn’t quite done. There are 3 scenarios where a conversation isn’t over yet:

1. You didn’t fully read it yet, so you don’t really know. Set reminders on messages so later you can continue reading where you left off. “I think this is important to be read but I don’t have the time now and I want to move on” type of message.

   • It’s ok if you don’t feel like reading a long wall of text now, or the topic is not critical. But you don’t want to forget about getting back to that message, so set yourself a reminder about it and move on with your normal duties until you’re ready to read it (say, tomorrow).

2. The conversation requires someone’s (your or other people’s) action to be taken, but this action is not the final step yet. Example: “I’ll investigate and report back.”

   • In these cases, creating a Jira ticket is probably an overkill, but following up, say, a week later, is worth while, to make sure we don’t drop it. This is the one of the most common reasons tasks are forgotten if no one keeps track of them, because it’s not tracked anywhere else except in Slack.

   • If the pending action is the task itself (e.g. “I’ll fix this later”), it’s probably worth it to simply track it in your ticket-tracking system (e.g. Jira) instead of in a Slack reminder. This allows you to give closure to the Slack thread, as it already served its purpose (the discussion), and use a ticketing system to track… you guessed it: tickets.

3. You’re waiting for someone to respond (you, or other people).

   • Here I would most likely not schedule a reminder, unless it’s a hyper critical topic that can’t be dropped. I tend to avoid scheduling reminders for every conversation to avoid being overwhelmed by reminders that would just automatically get resolved. Instead, for low priority conversations, I trust that other team members will carry the conversation and I’ll be notified when that happens. When there’s a conclusion, we can act on it.

What should I do with the Slack reminders once Slackbot gets back to me with them?

Go through them, one by one, and check what’s the status of that task. You can choose to take 1 of 3 actions: mark it as completed, snooze it, or delete it. See this simple decision tree:

• Was the topic (or the pending action) resolved?

  • Yes: great! Mark it as completed, and move on to the next reminder.

  • No: can you do it yourself?

    • Yes: wanna do it now?

      • Yes: go do it right now, no distractions. Come back to this reminder when you’re done. If you prefer, you can snooze it to when you think you’ll finish it (e.g. 20mins or 1h from now).

      • No: then snooze the reminder to be reminded about it again in the future, and move on to the next reminder.

    • No: follow up with whoever should be responsible for getting it done. Then snooze the reminder to be reminded about it again in the near future, and move on to the next reminder.

I rarely delete a reminder. When I do, it basically means “won’t do”: the topic is no longer relevant, or I don’t intend to do it anymore, for whatever reason.

2. 🗣️ Chat with yourself

It may sound a bit weird, but one of the most underrated features in Slack is the ability to chat with yourself. It's a private DM like any other, but with yourself and no one else. Messages sent there are editable forever, regardless of your Slack organization's message editing policies. They are also kept forever (according to your Slack’s retention plan), and indexed in searches.

According to Slack itself:

This is your space. Draft messages, list your to-dos, or keep links and files handy. You can also talk to yourself here, but please bear in mind you’ll have to supply both sides of the conversation.

I use this chat to:

• Take notes;

• Journal;

• Save anything that is not important enough to be permanently documented somewhere public (e.g. a wiki, Confluence, Notion), but at the same time I don't feel like deleting the information;

• Paste Slack links from Shared Organizations. If you simply click them from a browser, they won't open;

• Preview how messages will look before sending to a broader audience, specially regarding formatting. Since they're editable forever, I can just keep editing, saving, editing again, etc, until I'm happy with it;

• … and anything else related to work that should remain private and I wanted to type somewhere.

I probably overuse this chat, but it does help me keep everything organized, centralized, and within a single search scope: Slack. Some people prefer Notion, Google Docs, Notes, a physical notebook, text files in your computer. I usually replace all those with this chat.

This feature is so popular that it’s also available in WhatsApp and Telegram. In Telegram, it evolved into a new section in the app called "Saved Messages".

3. 📬 Mark messages as unread

If you accidentally open a chat that you weren’t ready to read yet, you can mark it as unread:

This prevents you from forgetting to read that chat, even if you can’t read it right now (since the chat is automatically marked as read once you open it). You could also set a reminder too, but I prefer setting it as unread so that I know I shouldn’t continue engaging with that channel until I’ve read all the unread messages first.

4. 🎯 Don't multitask

Probably the top 1 reason why busy people (like executives) often misses messages — especially in threads — is because once they click a chat (e.g. a channel, a DM, a thread, or even the “Threads” view), all the messages in that chat are marked as read instantly. This is not a problem on its own, except if you get distracted and move away from that chat before you finish reading all the messages you just marked as read, you will most likely forget to go back to it. So, rule of thumb: don’t multitask while you’re catching up with your Slack channels. Instead, read all messages in a given chat in one go. This keeps you from getting distracted and changing between chats. If you ultimately need to change chats before finish reading the current one, mark the current one as unread at the last unread message (see previous section).

5. 🧹 Clean up your side bar

This is just a tip to get your workspace a bit more organized, probably. The way I like to view my Slack side bar is not the default one that Slack gives you. Instead, I customize it like this:

This results in a clean side menu with only channels that you explicitly star. I star people I chat with often and end up with a side bar that serves the purpose of showing whether that person is available or not, and nothing else:

If a chat receives a new message, it shows up in its respective section (e.g. Channels, Direct Messages). Once I read it, it’s gone from the menu. If I need to revisit it or open any channel, I press ⌘K (you’ll read more about keyboard shortcuts in the last section of this article 😊).

6. 🔍 Search

If you feel like Slack is a black hole, you can’t find anything in there, can’t remember which channel a message you read was posted — you’re not alone. If that’s your case, I strongly suggest using the its search engine! It’s powerful, fast, and reliable. You can use lots of different filters:

Or use special search syntax if you want to speed up the process even more 😎 Check out the full documentation here: Search in Slack

7. 🔕 Limit your surface area

A huge complaint from Slack users is either “there are too many channels” or “I get too many notifications every day”. To address these, ask yourself:

• Do I need to be instantly notified of messages in channel X?

  • If not, how about muting the channel? Slack offers lots of tools to limit the notifications you receive, on a per-channel basis:

• Do I need read any message at all in channel X?

  • If not, have you considered leaving the channel? You most likely don’t need to be part of it. If someone need your attention in that channel in the future, they will add you back in (Slack cleverly prompts the person to invite you back when needed).

Customizing notification settings on a per-channel basis, and leaving superfluous noisy channels help reduce the notifications you receive significantly, and also keep your “pool of channels” smaller. After all, it shouldn’t matter if your Slack organization have thousands of channels, if you’re only in 5 of them :)

8. ⌨️ Use your keyboard

When using Slack on desktop, become a power user by using keyboard shortcuts! The more you know and use them, the more productive you’ll be!

You can find a list of all the Slack keyboard shortcuts here, but these are my favorites:

• Jump to a conversation: ⌘K

  • This one is the most efficient shortcut I use. I use this to start new chats, to jump to channels, to open the chat with myself, etc. Even if you see the chat you want to open in your Slack sidebar, don’t use your mouse to click it — use your keyboard, type out the shortest string that would match that chat and hit enter to instantly open it. It’s multiple times faster than clicking it (specially if you’re a fast typer 😉).

• Navigate to previous/next conversation in navigation history by using the same trackpad shortcut you use in your browser go navigate back/forward. For instance, on my MacBook trackpad I swipe with 3 fingers left and right.

• Edit your previous message: ⬆ (arrow up) while the chat’s text box is selected. Note that this must be enabled in your Slack preferences, otherwise this same shortcut will simply highlight the previous message in the chat.

• Navigate up/down in the chat menu to select a different chat: option up/down. This one is not even in the Slack’s link above 😇

• If you have multiple workspaces in your desktop app: switch to a specific workspace via ⌘[number], e.g. ⌘2, ⌘3, ⌘4, etc.

Day-to-day operation

This is where I would explain how I operate Slack on a daily basis, but since this article is already too long, I decided to publish this in a separate article :)

Make sure you subscribe so you don’t miss it when it goes out!

Subscribe now

Conclusion

Following the tips and tricks shown in this article, you’re guaranteed to become more productive, miss less information when using Slack, and receive way less notifications too, contributing to a more serene Slack workplace. I hope you apply these tips to your daily life 🤗

Feel free to comment below if you do any of the tricks listed in this article, or if any of them helped you :) I’d love to hear your stories!

Leave a comment

Feeling overwhelmed and unproductive, I decided to change my status to “Away” and enable “Do Not Disturb” on my work’s Slack workspace.

After 2 months running this social experiment, here’s what I observed (in no particular order):

• Direct calls were made impossible, due to Slack’s DND policies. This obviously reduced unsolicited and unscheduled calls at random hours.

• The amount of tagging and DMs reduced considerably.

• Despite the number of tags and DMs received, the average number of messages sent (by me) didn’t change.

Something to consider is that I don’t have fixed working hours — sometimes you’ll find me working PST (GMT-8), sometimes CST (GMT+8), sometimes none of those, or something in-between. So letting people know when I’m actually “online” makes a difference, as opposed to someone that works 9–5 every day, for instance.

What changed after some time:

• Some people noticed. They asked why I changed my status on Slack. Multiple times.

• People adapted to my new normal, and started sending DMs regardless of my status. (This could be just a perception, though)

• Other people adopted the same behavior and switched their statuses to "Away" permanently.

• Some people that had access to other means of contact started using them to reach out to me when needed (such as Facebook Messenger and Telegram).

What didn’t change:

• Emergency calls still took place. Sometimes I’d initiate them when needed, sometimes a group call would be posted in a public channel.

• Scheduled calls still took place.

• No work emails were received.

• I still don’t get disturbed via my phone because my phone itself was on DND before and during the experiment. More about this can be explained in a separate post.

Goals

I had two goals with this experiment, and I can say they were achieved.

Eradicated unsolicited calls at random hours

Calls and other means of synchronous communication is one of productivity’s worst enemies and should be avoided whenever possible.

Reduced the number of DMs

Direct messages are often used as a synchronous mean of communication (in which the parties often expect replies in a timely manner). They also centralize information somewhere the rest of the team can’t access. When DMs are discouraged, the sender will see themselves posting the message in channels (ideally public ones), which is better for a number of reasons. For instance, if the intended receiver of the message can’t answer at that time, someone might pick up the discussion sooner, and if this conversation needs to be referenced later, it can be.

DM is a good way to catch up on a personal level. Discuss things unrelated to work, things that don’t concern other colleagues, or use it as a synchronous mean of communication when you can’t be bothered to call.

Conclusion

It was an interesting social experiment to run. I could’ve asked people to schedule calls ahead of time, or asked them to post in public channels instead of sending me DMs, but that wouldn’t be as fun as being able to document this experiment ;)

I’d say that it was more delightful to work with a little bit of extra calmness, but I’m ready to enable Slack notifications and show my online status back again. Things may be different now, from 2 months ago. We’ll see.

My blogging journey started with Medium, back in 2015. I was living in Japan back then and wrote an article reflecting on whether I should move back to Brazil.

Since then, I’ve been blogging occasionally (a few times a year only). I usually write either to express something I’m thinking, or to share knowledge about something I learned recently that I couldn’t find useful information online — often related to iOS development or other engineering topics.

A couple years back I decided to move away from Medium to gain full control and ownership over my content, so I implemented my own static website generator to publish my articles, which were written in Markdown. I used Sundell’s Publish static site generator to accomplish that. The problem with this approach is that the website didn’t look good and there was too much I had to implement on my own to make it look good. It would be a one-off effort only, but still, too much work to be done before I could just focus on just writing.

Today, I am moving away from that self-hosted static website, and joining a large group of bloggers that use Substack. I found the tools available in Substack to be great, such as creating a community of people that may want to subscribe to my articles.

For now, I don’t plan on changing my writing cadence. Some people like to set goals of publishing new articles twice a week, or every other week, but I don’t see myself having enough time and content to commit to a given cadence. Maybe in the future? Subscribe and be notified of the next articles :)

For the purposes of this article, I considered a project with local Swift Package dependencies, and not other types of local dependencies (like static libraries and frameworks, or Development Pods).

Why does this happen?

What I figured is that xcodebuild's iOS Simulator startup time is too slow, and this causes the tests to take significantly longer. For each dependency you have, it will launch a new iOS Simulator process, and this process takes anywhere from 4 to 10 minutes, dependending on the machine it's run - even when launching a "headless" simulator.

The solution: Test Plans

Xcode Test Plans, which debuted in Xcode 11, serve the purpose of bundling tests together. You may want to create different sets of tests such as "Nightly", "UI", "Performance", etc, or you may simply bundle them up all together in the same Test Plan.

What I realized is that when using Test Plans, I obtained test runs up to 93% faster than by running individual Swift Package tests (xcodebuild test <swift package>) for iOS targets (more on this later).

Show me the code!

Setting up your Test Plan

Test Plans can be created via Xcode by creating a new file (cmd + N) and choosing "Test Plan" - yes, that simple. However, if you're using local Swift Packages, there's a trick here: your .xcodeproj or .xcworkspace must have the Swift Packages targets you want to test in its folder hierarchy otherwise they won't show up to be added in your Test Plan.

Once you have a Test Plan file, open it an click the + at the bottom left of the window and add all the targets you'd like to test.

Next, you may want to convert your one of your schemes of your main project (one that consumes those dependencies) to use Test Plans, or not. The only difference is that if you convert it, you can simply run xcodebuild test -scheme <your_scheme>, and if not, then you'll have to specify the name of your Test Plan explicitly, like xcodebuild test -testPlan <test_plan_name>.

To convert your scheme, open its Edit window on Xcode, and select Convert to use Test Plans…:

Collecting code coverage

Every setup is different, but I like using Rake tasks to run tests and collect code coverage. You may be using fastlane, in which case the APIs used will be different but the concepts remain the same. Also, I'll be using Code Climate in my example as it's the code coverage service I usually use for Swift projects.

First, we have to kick off the code coverage program that Code Climate distributes:

# Path to your Code Climate test reporter binary. You may want to fetch this from remote and do a checksum check before running it.
test_reporter_bin = "path/to/your/cc-test-reporter"

# Invoke the before-build function required by Code Climate, before collecting your code coverage
sh("#{test_reporter_bin} before-build")

Then we build the Test

# This becomes your new Derived Data path, stored in your project directory (you can gitignore this new folder)
build_path = ".build"

xcodebuild = []
xcodebuild << "arch -x86_64" # Only required if your project only runs on Rosetta 2
xcodebuild << "xcodebuild test"
xcodebuild << "-workspace your-project.xcworkspace"
xcodebuild << "-scheme 'Your Scheme'"
xcodebuild << "-destination 'platform=iOS Simulator,name=iPhone 14 Pro'"
xcodebuild << "-enableCodeCoverage=YES"
xcodebuild << "-derivedDataPath '#{build_path}/your-project'"
xcodebuild << "-clonedSourcePackagesDirPath '#{build_path}/SourcePackages'"
xcodebuild << "-quiet" # Optionally silents all xcodebuild output
sh(xcodebuild.join(" "))

Since xcodebuild will collect code coverage for all the targets that it goes through, including 3rd party, we have to filter out which targets we're interested. Let's declare an array for this purpose, that will be used later:

# You may want to collect this array programmatically somehow via scripting, for instance by crawling your directory hierarchy and reading which packages have test targets. For simplicity sake here we're just declaring them statically. 
targets_to_keep = %w(
  foo
  bar
  baz
)

Then we must interpret the .xcresult file produced by xcodebuild, and convert it to a format that Code Climate can interpret:

# This is a special path where your xcresult (test results) will be stored, within the Derived Data path specified by you earlier.
most_recent_xcresult = Dir.glob("#{build_path}/your-project/Logs/Test/*.xcresult").max_by { |f| File.mtime(f) }

# Specify where we're going to store the code coverage reports. Feel free to gitignore these directories or clean them up after collection
xcodebuild_reports_directory = "coverage/xcodebuild_only_reports"
xccov_report = File.absolute_path("#{xcodebuild_reports_directory}/your-project-xccov-report.json")
output_file = File.expand_path("coverage/your-project-codeclimate.json")
FileUtils.mkdir_p(xcodebuild_reports_directory)

# Use `xccov` (a built-in tool from Xcode) to convert the .xcresult into a json file that uses the xccov format
sh("xcrun xccov view --report --json '#{most_recent_xcresult}' > #{xccov_report}")

# Invoke this function that will clean up the code coverage report from targets we're not interested in collecting data for
remove_all_targets_except(xccov_report, targets_to_keep)

# Finally, format the json report (that uses the xccov format) into another json format specific to Code Climate 
sh("#{test_reporter_bin} format-coverage '#{xccov_report}' --input-type xccov --output '#{output_file}'")

Note that this snippet makes use of a function you must declare in your Rakefile called remove_all_targets_except. More about it here: https://gist.github.com/rogerluan/aaba6694a45ed5381e7e6b2259abd9f7

Finally, submit the code coverage report to Code Climate:

sh("#{test_reporter_bin} upload-coverage --input '#{output_file}'")

Monorepo setup

If you repository has multiple projects in it, this means you'll probably have more than 1 TestPlans (one for each project). If that's your case, this means you'll still have to merge the code coverage reports of your multiple projects before uploading them to Code Climate, by using the sum-coverage --parts <number_of_parts> function of their code coverage reporter tool. Again, this is only for Code Climate, so your mileage may vary.

Conclusion

With the setup I described in this article, I was able to reduce build times from ~61mins to ~4mins (when running locally), and from ~90mins to ~20mins (when running on Jenkins). That's an improvement of 77-93%!

One caveat with Swift Packages specifically is that, if your package is capable of running on macOS target (e.g. has no iOS dependency like UIKit), then your fastest alternative will certainly be using swift test, because it usually takes under 1 second to run whatever test suite you may have (of course, as long as they're not time-dependent). Yes, really.

I hope this setup also helps you and your team to reduce build times significantly. And if you know other tricks to reduce test time, drop a note on my twitter @rogerluan_!