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 private key id_rsa (associated with haskell-pushbot's
  27    account).  This upload contains its own .travis.yml (customized
  28    for the particular build matrix configuration), and some special
  29    JSON metadata in the commit message.
  30
  31 3. Triggered by the push to cabal-binaries, Travis on haskell-pushbot
  32    will run the tests.  After this finishes, it will invoke a webhook
  33    that invokes sake-bot (https://github.com/ezyang/sake-bot, currently
  34    installed at https://sake-bot.herokuapp.com/) which will post
  35    back the GitHub status result to the upstream Cabal repository.
  36
  37 ## Who maintains this setup
  38
  39 Unfortunately, there are some infrastructural permissions which
  40 don't coincide with the GitHub permissions for the Cabal project.
  41 Here are the relevant bits:
  42
  43 * The GitHub account haskell-pushbot is owned by @ezyang (along
  44   with the associated Travis account.)
  45
  46 * The Heroku instance https://sake-bot.herokuapp.com/ is maintained by @ezyang.
  47   It has a private key for a GitHub integration on the Haskell
  48   GitHub organization (which gives it permissions to update
  49   statuses on the Cabal project).
  50
  51 Fortunately, if @ezyang ever gets run over a bus, all of these
  52 infrastructural bits can be reconfigured.  Here is what you
  53 would need to do:
  54
  55 * Create a new GitHub account to replace haskell-pushbot
  56
  57 * Generate a new private key, associate it with the GH account, and
  58   replace id_rsa and id_rsa.pub with the new account
  59
  60 * Create a new binaries repository, modify the invocation of
  61   "git remote add" in upload.sh to point to the new location.
  62   Enable Travis for this repository.
  63
  64 * Create a new Heroku instance of https://github.com/ezyang/sake-bot
  65   (use the "Deploy with Heroku" button.)  Follow the instructions
  66   there; you'll need a private key for an integration associated
  67   with the Haskell organization; talk to one of the admins there
  68   to get the key.
  69
  70 That's it!
  71
  72 ## Limitations
  73
  74 If you push to your local account and run Travis, the builds will
  75 still take place in the shared cabal-binaries Travis instance, and
  76 you won't get status updates (because sake-bot doesn't have permissions
  77 to update the status update on any repository besides its own.)
  78 In principle, it should be possible for upload.sh to autodetect if you
  79 have a cabal-binaries repository setup on your local account, and use
  80 that instead, but as the sake-bot integration can only be installed
  81 on the same account it was created for, getting sake-bot setup would
  82 be annoyingly fiddly.  Shout if you need this to work.