Setting Up Xcode Server Email Notifications on a Repurposed Household Mac So They Send From Your GSuite Account

I recently repurposed a family computer to play a new role: Xcode build server. Setting up the bot wasn't too bad overall, but there was one really big hurdle: getting post-integration email notifications to actually send. Despite the (relative) user-friendliness of the UI, the email notification feature is very unforgiving. It expects to be running on a mac that is hosting (or sitting behind) a domain that's also running it's own SMTP service. A repurposed family computer is not going to have such a setup. Outbound mail is going to either not send at all or else likely get bounced by spam filtering.

I do have a GSuite account for small business stuff. I host my website at Media Temple, but the email service is run by Gmail, with DNS records configured to route mail traffic to Gmail. What I want is for my Xcode bot to send email notifications from one of my GSuite accounts. The following are some scattered notes and observations as I figured out how to set up an SMTP relay through GSuite and use it from an Xcode bot post-integration notification.

The gist

This job is really two things, one big and one small:

Big job: relaying local outbound email through your GSuite account
Small job: getting Xcode out of the way so that the relay works

The steps to establish the GSuite Gmail relay entail:

Configure postfix
Enable SMTP relay in GSuite
Obtain an app-specific password for Gmail
Configure a SASL email/password usable by postfix
Reload postfix
Send a test email from the CLI

The Big Job: SMTP Relay

Configure postfix

All, or at least almost all, of the following require sudo:

cd /etc/postfix
touch main.cf unless it’s already there
vi main.cf and page down to the bottom of the document

Then append the following at the end of the main.cf file:

# Gmail SMTP Relay Settings
relayhost = smtp-relay.gmail.com:587
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options =
smtp_sasl_local_domain = localhost
broken_sasl_auth_clients = yes
smtpd_pw_server_security_options = noanonymous
smtp_use_tls = yes
smtp_tls_security_level = encrypt
tls_random_source = dev:/dev/urandom
smtp_sasl_mechanism_filter = plain
smtpd_banner = YOUR_DOMAIN_HERE.COM

Enable SMTP Relay in GSuite

Log into your GSuite account (any account with admin privileges) and enable an SMTP relay with the following settings:

Allowed senders: Unless the machine running Xcode is behind your GSuite domain, you’ll need to allow any senders because the sending address will be [email protected] which would otherwise be blocked.
Only accept mail from specified IP addresses: Yes.
Allowed IP Addresses: Find your public IP via any of a plethora of websites, and get the CIDR range for it, entering that text for the allowed IP address range.
Require SMTP Auth: Yes
Require TLS encryption: Yes

Obtain an App-Specific Password

Log into the GSuite account you want to send Xcode notifications from and create an app-specific password for it (links abound if you can’t find this feature on your own). I’m including this step by default because I know you’re not using GSuite without two-factor auth, you savvy user, you.

Configure SASL Email/Password for Postfix

Next, create a sasl_password file (you’re still in the /etc/postfix/ directory), and add the following:

smtp-relay.gmail.com:587 YOUR_EMAIL:APP_SPECIFIC_PASSWORD

Save the changes, then update the database by running:

sudo postmap hash:/etc/postfix/sasl_passwd

Reload Postfix

Now that everything’s configured, apply your changes by reloading postfix:

sudo postfix reload

Send a test email from the CLI

Verify that all the above is working by sending yourself a test email:

echo ‘Test email body.’ | mail -s 'Test Email Subject’ <RECIPIENT_EMAIL>

Check your recipient email account to see if it was delivered. If not, read below for some debugging tips.

Debugging Tips

Run mailq in the CLI after reloading postfix to see your queue, may show some helpful errors
Run log stream --predicate '(process == "smtpd") || (process == "smtp")' --info in the CLI to see a live view of the SMTP logs. This is where you’ll find the most helpful information about the errors in your setup.
Also look at your local mail inbox via cat /var/mail/USERNAME as you might be getting bounced messages with more helpful information

The Small Job: Xcode Setup

Finish up in Xcode by doing the following:

Create the bot (links galore online)
Create the bot integration with your project (links galore online)
In the bot settings in Xcode prefs, do not put anything in the “Mail” configuration text boxes (leave them all blank)
In the post-integration notification settings, set whatever your heart desires for the sender name, etc.

Helpful Links

Open Problems and Questions

Despite the wording of the support guide, messages bounced with both SMTP Auth and TLS enabled. I also had to whitelist my public IP to get messages to relay. I don't understand what was wrong: the docs or my setup.
Messages still show that they're sent from [email protected] and not the email used to configure the SMTP auth relay. I would prefer they be from the auth-ed account.

jaredsinclair/xcode-gsuite-email-notifs.md