In my previous post on Xcode Server, I discussed the Xcode Server feature to send issue notification and summary email messages, and how to configure email triggers as part of integration configuration. In this post, I’ll discuss how to configure a MacOS Xcode Server machine to actually route email messages to the development team.
The Documented Way to Configure Xcode Server
As of this writing, the Xcode 10 documentation provides a single — and sparse — manual page on configuring Xcode Server to send email via SMTP:
This seems very straightforward. You should add your outgoing SMTP server information and send from info — and Xcode server will send email. It should just work, right?
There’s only one problem with this procedure…for many people — including me — this doesn’t work.
Most likely this simple configuration can work in some environments, but Apple provides no information in the documentation regarding prerequisites and what type of SMTP environment this configuration is designed for.
No worries, though — next I’ll cover how to configure your Xcode server to work with any type of SMTP-based email infrastructure.
Note: if you know how to get the default Xcode configuration to work with authenticated, TLS-based email back-ends, please let me know in the comments!
Configuring Xcode Server to Send Email via Postfix
If you’ve installed Xcode 10 on macOS Mojave (and probably previous versions of both — though I’m only covering Xcode 10 here), your Xcode server hardware should already have a dormant installation of Postfix pre-installed. We’ll use that existing install of Postfix to get email delivery going with Xcode server.
Note: I use SMTP2GO as my SMTP provider for Xcode server, so the following instructions are specific to that service. This same procedure can work with other providers like Gmail, Office 365, and other services that provide SMTP with or without an encrypted SMTP connection. Adapt the settings below as required to match the requirements of your SMTP provider.
#1 Don’t configure Xcode’s email options
First, don’t configure Xcode’s email settings at all — just leave them blank. On your Xcode server, open Xcode Server configuration and ensure all fields are left blank, as in the documentation image above.
#2 Add your SMTP server credentials to the Postfix password file
Next configure your Xcode server Postfix installation with the username/password needed to authenticate with your SMTP server when sending e-mail.
Create or modify the /etc/postfix/sasl_passwd file using your favorite editor, for example:
$sudo nano /etc/postfix/sasl_passwd
Add a line that provides a valid username/password combination and corresponding server/port, with your own SMTP authentication credentials, similar to the following:
#3 Run Postmap agains the password file
sudo postmap /etc/postfix/sasl_passwd
#4 Add Configurations to Postfix
Open the Postfix configuration file with your favorite text editor, for example nano:
$ sudo nano /etc/postfix/main.cf
Add correct configuration lines as required by your email provider. For smtptogo, I use the following:
relayhost = mail.smtp2go.com:2525 smtp_sasl_auth_enable=yes smtp_sasl_password_maps=hash:/etc/postfix/sasl_passwd smtp_use_tls=yes smtp_tls_security_level=encrypt
Note that the relayhost in main.cf should match the url:port in the previous password file exactly.
It’s OK to add these configurations to the bottom of the main.cf file, but search the file and comment out any existing settings that would duplicate what you add.
#5 Start Postfix server on the Xcode Server machine
$ sudo postfix start
#6 Set Postfix to Auto-Start on the Xcode Server machine
Edit the postfix service configuration file using your favorite text editor, e.g. nano:
$ sudo nano com.apple.postfix.master.plist
When Postfix is running, and your security configurations are correct — and the Xcode server mail settings are left blank — Xcode server will successfully send email when your email triggers are fired in Xcode integrations!