Github Mail Delivery Agent

This directory contains a python script that acts like a Mail Delivery Agent (MDA) that can be used in fetchmail.

Github Enterprise (GHE) supports replying by email to post comments on pull requests, issues, commit comments etc. But it requires that port 25 (SMTP) is directly exposed to the internet so external mail servers can relay messages to it. Depending on the security policies of your environment this might not be possible to do.

Github Enterprise sends out notification emails with the reply-to address set to reply+NN..NN@reply.[hostname]. Here [hostname] is the FQDN of the GHE instance. E.g: github.priv.mycompany.net.

• Create DNS records for reply.github.priv.mycompany.net with your DNS provider.
  • You will at the minimum need MX records for this sub-domain.
• Set up email delivery to reply.github.priv.mycompany.net with an external email provider (Google Apps, Zoho, Exchange Online or roll your own)
• Use fetchmail to retrieve messages
• When fetchmail downloads new emails it forwards them to a custom MDA. The MDA then filters messages that have a TO address of the form reply+NN..NN@reply.[hostname] and delivers them to the SMTP server on the GHE instance.

In a separate VM

• Install fetchmail

• Copy the etc/fetchmailrc to /etc on the target machine.

  • Replace imap.gmail.com to point to the right mail server
  • Replace [email protected] with the right username & domain for your mail server.
  • Replace INSERT PASSWORD with the password for the account
  • Replace the protocol IMAP with whatever mail download protocol you enable for this account.

• Copy the script github_mda.py to some location on the target machine. e.g. /home/joe/github-fetchmail and update the mda line in /etc/fetchmailrc

  • Update the constants REPLY_SUBDOMAIN to the right reply subdomain for your GHE instance
  • Update SMTP_HOST to the hostname for your GHE instance

• Create directory /var/github-fetchmail and change its owner to fetchmail

• Edit /etc/default/fetchmail and set START_DAEMON to 'yes'

• Enable fetchmail to start on boot

  # Ubuntu
  sudo updated-rc.d fetchmail enable
  
  # debian 8 / Arch
  sudo systemctl enable fetchmail
  

• Start fetchmail

  # Ubuntu
  sudo /etc/init.d/fetchmail start
  
  # debian 8 / Arch
  sudo systemctl start fetchmail
  

• See LICENSE