To make it easy for users to respond quickly to activity on GitHub Enterprise, you can configure your instance to send email notifications on issue, pull request, and commit comments, as well as additional settings to allow inbound email replies. Notification emails are sent if there is activity on a repository a user is watching, if there is activity in a pull request or issue they are participating in, or if the user or team they're a member of are @mentioned in a comment.

Tips:

  • Enabling email through the Management Console will enable both outbound and inbound email. Inbound email will only work if you also configure your DNS settings, as described below.
  • Unless you select the Send from author checkbox in a repository’s Services email webhook, outbound email will send from the addresses configured either in the No reply or Support email address fields of the Management Console.

Configuring SMTP

  1. Access the Management Console.

  2. At the top of the page, click Settings. Settings tab

  3. In the left sidebar, click Email. Email tab
  4. If you'd like to support both inbound and outbound email, select Enable email. Enable outbound email
  5. Fill in your email server settings:
  6. In the Server address field, type the address of your SMTP server.
  7. In the Port field, type the port that your SMTP server uses to send email.
  8. In the Domain field, type the domain name that your SMTP server will send with a HELO response, if any.
  9. In the Authentication dropdown, choose the type of encryption used by your SMTP server.
  10. In the No-reply email address field, type the email address to use in the From and To fields for all notification emails.

  11. To send a test email, click Test email settings.

  12. Under Support, choose a type of link to offer additional support to your users:

    • Email: An internal email address.
    • URL: A link to an internal support site. You must include either http:// or https://. Support email or URL
Inbound Email

To allow email replies to notifications:

  1. Ensure that port 25 on the instance is accessible to your SMTP server.
  2. Create an MX record for reply.<hostname> so that emails to that domain are routed to the instance.

Configuring DNS settings

You must configure your DNS settings before you are able to test whether GitHub Enterprise can receive inbound emails.

  1. Create an A record that points to reply.[hostname]. Depending on your DNS provider and instance host configuration, you may be able to instead create a single A record that points to *.[hostname].
  2. Create an MX record that points to reply.[hostname].

With your DNS configuration setup, you can now test whether the setup works.

Testing email delivery

  1. At the top of the Email section, click Test email settings. Test email settings
  2. In the Send test email to field, type an address to send the test email to. Test email address
  3. Click Send test email. Send test email
  4. If the test email fails, troubleshoot your email settings.
  5. When the test email succeeds, at the bottom of the page, click Save settings. Save settings button
  6. Wait for the configuration run to complete. Configuring your instance

If you encounter any SMTP errors sending a test email while configuring your email settings—such as an immediate delivery failure or an outgoing mail configuration error—you will see them on the Test email settings dialog box.

A failed test

Troubleshooting email delivery

Create a Support Bundle

If you cannot determine what is wrong from the displayed error message, you can download a Support Bundle containing the entire SMTP conversation between your mail server and GitHub Enterprise. Once you've downloaded and extracted the bundle, check the entries in enterprise-manage-logs/unicorn.log for the entire SMTP conversation log and any related errors.

The unicorn log should show a transaction similar to the following:

This is a test email generated from https://10.0.0.68/setup/settings
Connection opened: smtp.yourdomain.com:587
-> "220 smtp.yourdomain.com ESMTP nt3sm2942435pbc.14\r\n"
 "250-smtp.yourdomain.com at your service, [1.2.3.4]\r\n"
-> "250-SIZE 35882577\r\n"
-> "250-8BITMIME\r\n"
-> "250-STARTTLS\r\n"
-> "250-ENHANCEDSTATUSCODES\r\n"
-> "250 PIPELINING\r\n"
 "220 2.0.0 Ready to start TLS\r\n"
TLS connection started
 "250-smtp.yourdomain.com at your service, [1.2.3.4]\r\n"
-> "250-SIZE 35882577\r\n"
-> "250-8BITMIME\r\n"
-> "250-AUTH LOGIN PLAIN XOAUTH\r\n"
-> "250-ENHANCEDSTATUSCODES\r\n"
-> "250 PIPELINING\r\n"
 "334 VXNlcm5hbWU6\r\n"
 "334 UGFzc3dvcmQ6\r\n"
 "535-5.7.1 Username and Password not accepted. Learn more at\r\n"
-> "535 5.7.1 http://support.yourdomain.com/smtp/auth-not-accepted nt3sm2942435pbc.14\r\n"

This log shows that the appliance:

  • Opened a connection with the SMTP server (Connection opened: smtp.yourdomain.com:587).
  • Successfully made a connection and chose to use TLS (TLS connection started).
  • The login authentication type was performed (<- "AUTH LOGIN\r\n").
  • The SMTP Server rejected the authentication as invalid (-> "535-5.7.1 Username and Password not accepted.).

Check your GitHub Enterprise instance logs

If you need to verify that your inbound email is functioning, there are two logfiles that you can examine on your instance: To verify that /var/log/mail.log and /var/log/mail-replies/metroplex.log.

/var/log/mail.log verifies that messages are reaching your server. Here's an example of a successful email reply:

Oct 30 00:47:18 54-171-144-1 postfix/smtpd[13210]: connect from st11p06mm-asmtp002.mac.com[17.172.124.250]
Oct 30 00:47:19 54-171-144-1 postfix/smtpd[13210]: 51DC9163323: client=st11p06mm-asmtp002.mac.com[17.172.124.250]
Oct 30 00:47:19 54-171-144-1 postfix/cleanup[13216]: 51DC9163323: message-id=<b2b9c260-4aaa-4a93-acbb-0b2ddda68579@me.com>
Oct 30 00:47:19 54-171-144-1 postfix/qmgr[17250]: 51DC9163323: from=<tcook@icloud.com>, size=5048, nrcpt=1 (queue active)
Oct 30 00:47:19 54-171-144-1 postfix/virtual[13217]: 51DC9163323: to=<reply+i-1-1801beb4df676a79250d1e61e54ab763822c207d-5@reply.ghe.tjl2.co.ie>, relay=virtual, delay=0.12, delays=0.11/0/0/0, dsn=2.0.0, status=sent (delivered to maildir)
Oct 30 00:47:19 54-171-144-1 postfix/qmgr[17250]: 51DC9163323: removed
Oct 30 00:47:19 54-171-144-1 postfix/smtpd[13210]: disconnect from st11p06mm-asmtp002.mac.com[17.172.124.250]

Note that the client first connects; then, the queue becomes active. Then, the message is delivered, the client is removed from the queue, and the session disconnects.

/var/log/mail-replies/metroplex.log shows whether inbound emails are being processed to add to issues and pull requests as replies. Here's an example of a successful message:

[2014-10-30T00:47:23.306 INFO (5284) #] metroplex: processing <b2b9c260-4aaa-4a93-acbb-0b2ddda68579@me.com>
[2014-10-30T00:47:23.333 DEBUG (5284) #] Matched /data/user/mail/reply/new/1414630039.Vfc00I12000eM445784.ghe-tjl2-co-ie
[2014-10-30T00:47:23.334 DEBUG (5284) #] Moving /data/user/mail/reply/new/1414630039.Vfc00I12000eM445784.ghe-tjl2-co-ie => /data/user/incoming-mail/success

You'll notice that metroplex catches the inbound message, processes it, then moves the file over to /data/user/incoming-mail/success.

Verify your DNS settings

In order to properly process inbound emails, you must configure a valid A Record (or CNAME), as well as an MX Record.

Check firewall or AWS Security Group settings

If your GitHub Enterprise instance is behind a firewall or is being served through an AWS Security Group, make sure port 25 is open to all mail servers that send emails to reply@reply.[hostname].

Contact support

If you're still unable to resolve the problem, contact GitHub Enterprise Support to ask for help. Please attach the output file from http(s)://[hostname]/setup/diagnostics to your email to help us troubleshoot your problem.