diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/README b/README new file mode 100644 index 0000000..53604a8 --- /dev/null +++ b/README @@ -0,0 +1,124 @@ +pushmail +======== + +Monitor commits to a GitHub repository, and send notification emails +when commits are pushed directly to a ref rather than through a +Pull Request. + +pushmail is designed to be resilient. Most failure modes, including +sudden power loss, should result in pushmail simply carrying on from +where it left off next time it is run. In the worst case, a single +notification message per failure will be dropped. It will never +double-send a notification on its own. + + +Installation +------------ + +Build dependencies: + - Cargo + - rustc + - pkg-config + +Runtime dependencies: + - Git + - OpenSSL + - a `sendmail' program + +In most cases, installation should be as simple as + + make install + + +Usage +----- + +The `pushmail' program should be run either on a timer, or in response +to a GitHub webhook. + +The program must be supplied with a local checkout of the monitored +git repository, the full repository name on GitHub (i.e. owner/repo), +a GitHub API token, and a mailbox to deliver notification messages to. + +It is also possible to configure the From address in notification +messages, and the git ref to be monitored. + +For example: + + pushmail \ + --from "Nixpkgs Direct Pushes <pushmail@atuin.qyliss.net>" \ + --ref "staging" \ + /var/lib/pushmail/nixpkgs.git \ + NixOS/nixpkgs \ + "Alyssa Ross <hi@alyssa.is>" \ + < /var/lib/pushmail/token + + +Further information on available command line arguments can be +obtained with + + pushmail --help + +The first time it is run, pushmail will set its cursor (which is a +branch in the local git checkout) to the commit currently pointed to +by the monitored ref. In subsequent runs, pushmail will advance +forwards through the history from the current cursor, checking for +directly-pushed commits, and sending notifications as appropriate. +The cursor is updated after every checked commit to limit the amount +of work that needs to be redone in the event of a crash. + + +Development +----------- + +The upstream git repository for pushmail is available at +<https://git.qyliss.net/pushmail/>. + +Bugs and patches can be sent to the author, +Alyssa Ross <hi@alyssa.is>. + +For information about how to use git to send a patch email, see +<https://git-send-email.io/>. + + +License +------- + +Copyright 2020 Alyssa Ross. + +pushmail is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +pushmail is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with pushmail; if not, write to the Free Software Foundation, +Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +Linking pushmail statically or dynamically with other modules is +making a combined work based on pushmail. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +In addition, as a special exception, the copyright holders of +pushmail give you permission to combine pushmail with free software +programs or libraries that are released under the GNU LGPL and with +code included in the standard release of OpenSSL under the OpenSSL +License or the Original SSLeay License (or modified versions of +such code, with unchanged license). You may copy and distribute +such a system following the terms of the GNU GPL for pushmail and +the licenses of the other code concerned, provided that you include +the source code of that other code when and as the GNU GPL requires +distribution of source code. + +Note that people who make modified versions of pushmail are not +obligated to grant this special exception for their modified +versions; it is their choice whether to do so. The GNU General +Public License gives permission to release a modified version +without this exception; this exception also makes it possible to +release a modified version which carries forward this exception. |