travis/README.md

   1 # Continuous integration on Travis
   2
   3 This folder contains scripts for running CI on Travis.
   4
   5 The most unusual thing about our Travis setup is that, after we finish
   6 building our project, we upload the build products to Git (via the
   7 haskell-pushbot account) to a separate repository to do testing.
   8 There are two reasons we do this:
   9
  10 1. On our slowest configuration (GHC 8 on Mac OS X), the time to
  11    build and run tests was easily bumping up against the Travis time
  12    limit.  By uploading our build products to a separate account,
  13    we get twice as much time to run our builds.
  14
  15 2. Travis parallelism is limited on a per-account basis; if we
  16    upload build products to another account, we get more parallelism!
  17    (Travis, let us know if you don't like this :)
  18
  19 Here is the general lifecycle of a Travis run:
  20
  21 1. For each build matrix configuration, we run ../travis-script.sh
  22    to build Cabal, cabal-install, and all of the test suites.
  23
  24 2. Once the build is successful, we invoke upload.sh to upload
  25    the build products to the cabal-binaries repository.  This is done
  26    using the ROT-13'ed private key id_rsa.rot13 (associated with
  27    haskell-pushbot's account).  This upload contains its own .travis.yml
  28    (customized for the particular build matrix configuration), and some
  29    special JSON metadata in the commit message.  ROT-13 is used to
  30    prevent GitHub from deciding the private key is compromised.
  31
  32 3. Triggered by the push to cabal-binaries, Travis on haskell-pushbot
  33    will run the tests.  After this finishes, it will invoke a webhook
  34    that invokes sake-bot (https://github.com/ezyang/sake-bot, currently
  35    installed at https://sake-bot.herokuapp.com/) which will post
  36    back the GitHub status result to the upstream Cabal repository.
  37
  38 ## Who maintains this setup
  39
  40 Unfortunately, there are some infrastructural permissions which
  41 don't coincide with the GitHub permissions for the Cabal project.
  42 Here are the relevant bits:
  43
  44 * The GitHub account haskell-pushbot is owned by @ezyang (along
  45   with the associated Travis account.)
  46
  47 * The Heroku instance https://sake-bot.herokuapp.com/ is maintained by @ezyang.
  48   It has a private key for a GitHub integration on the Haskell
  49   GitHub organization (which gives it permissions to update
  50   statuses on the Cabal project).
  51
  52 Fortunately, if @ezyang ever gets run over a bus, all of these
  53 infrastructural bits can be reconfigured.  Here is what you
  54 would need to do:
  55
  56 * Create a new GitHub account to replace haskell-pushbot
  57
  58 * Generate a new private key, associate it with the GH account, and
  59   replace id_rsa.rot13 and id_rsa.pub with the ROT-13'ed private
  60   key and the public key.
  61
  62 * Create a new binaries repository, modify the invocation of
  63   "git remote add" in upload.sh to point to the new location.
  64   Enable Travis for this repository.
  65
  66 * Create a new Heroku instance of https://github.com/ezyang/sake-bot
  67   (use the "Deploy with Heroku" button.)  Follow the instructions
  68   there; you'll need a private key for an integration associated
  69   with the Haskell organization; talk to one of the admins there
  70   to get the key.
  71
  72 That's it!
  73
  74 ## Limitations
  75
  76 If you push to your local account and run Travis, the builds will
  77 still take place in the shared cabal-binaries Travis instance, and
  78 you won't get status updates (because sake-bot doesn't have permissions
  79 to update the status update on any repository besides its own.)
  80 In principle, it should be possible for upload.sh to autodetect if you
  81 have a cabal-binaries repository setup on your local account, and use
  82 that instead, but as the sake-bot integration can only be installed
  83 on the same account it was created for, getting sake-bot setup would
  84 be annoyingly fiddly.  Shout if you need this to work.