Xcode Server Bot Email Triggers

Xcode server is typically run on a dedicated machine, e.g. a Mac Mini or cloud-based Mac server, so configuring the Xcode server to communicate the outcome of automations to the development team is critical to keeping forward progress on the development project.

In a previous post, I introduced Xcode Server bots and mentioned that an integration can fire an email trigger — for example to notify team members of successful integration completion or of exceptions encountered as the integration ran.

In that previous post I presented this diagram to illustrate an Xcode server automation that builds an app after a git branch is pushed to a remote repository on GitHub. Note the step in the bottom-right corner, which sends an email to the development team to communicate the outcome of the automation, or the overall status of the project.

Xcode Server automation example

What Do Email Triggers do for me?

Xcode server is typically run on a dedicated machine, e.g. a Mac Mini or cloud-based Mac server, so configuring the Xcode server to communicate the outcome of automations to the development team is critical to keeping forward progress on the development project.

An obvious choice to send status reports from Xcode server to development, QA and product teams is email, and Xcode server supports email reporting triggers out-of-the box.

Xcode Server provides two built-in email notification trigger types:

  1. New Issue Email. An email is sent when new issues are found. The intended recipient(s) for this type of trigger are the team members that introduced issues via source code contributions to the git repository.
  2. Periodic Email report. A summary of current project progress, intended to be sent to the broader team responsible for product development.

Configuring an automation email trigger

Configuring a trigger is really easy. While on the last tab of the integration configuration screen:

  1. Tap the plus (+) button to create a new trigger.
  2. Select either New Issue Email or Periodic Email Report.
  3. Select the types of issues that should trigger a new -mail each committer who introduced and issue.

In the case of a Periodic Email Report:

4. Select how frequently the summary report should be sent: after each integration, daily or weekly.

5. Since the trigger is a period report, the report can be sent to a broader audience, so you can add a list of email addresses/distribution lists in a way similar to sending an email from a standard mail client.

What do I get out of this?

After the bot is configured and saved (which sends it to the Xcode server for scheduling), Xcode Server will send emails according to the configuration steps made above.

Email will be delivered to your email box, and the delivered email will look similar to the following example of a compile error summary:

Example Xcode Server email report

Configuring your Xcode server to send email

The above discussion is focused on configuring bots with triggers that send email. But you do need to configure Xcode server so it has an authorized path to send the mail it’s configured to. I’ll discuss how to do this in the next post in this series: Configuring Xcode Server to send email.

Related to This Post

Configuring Xcode Server to Send Email

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:

Xcode Server Email Configuration Documentation (as of Xcode 10)

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:

mail.smtp2go.com:2525 user@domain.com:password

#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

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!

Related to This Post