[Summary view] [Print] [Text view]

   1  @title Diffusion User Guide: Repository Updates
   2  @group userguide
   3  
   4  Explains how Diffusion updates repositories to discover new changes.
   5  
   6  Overview
   7  ========
   8  
   9  When Phabricator is configured to import repositories which are hosted
  10  elsewhere, it needs to poll those repositories for changes. If it polls too
  11  frequently, it can create too much load locally and on remote services. If it
  12  polls too rarely, it may take a long time for commits to show up in the web
  13  interface.
  14  
  15  This document describes the rules around polling and how to understand and
  16  adjust the behavior. In general:
  17  
  18    - Phabricator chooses a default poll interval based on repository
  19      activity. These intervals range from every 15 seconds (for active
  20      repositories) to every 6 hours (for repositories with no commits in two
  21      months).
  22    - If you use `arc` to push commits, or you host repositories on Phabricator,
  23      repositories automatically update after changes are pushed.
  24    - If you don't use `arc` and your repository is hosted elsewhere, this
  25      document describes ways you can make polling more responsive.
  26  
  27  
  28  Default Behavior
  29  ================
  30  
  31  By default, Phabricator determines how frequently to poll repositories by
  32  examining how long it has been since the last commit. In most cases this is
  33  fairly accurate and produces good behavior. In particular, it automatically
  34  reduces the polling frequency for rarely-used repositories. This dramatically
  35  reduces load for installs with a large number of inactive repositories, which
  36  is common.
  37  
  38  For repositories with activity in the last 3 days, we wait 1 second for every
  39  10 minutes without activity. The table below has some examples.
  40  
  41  | Time Since Commit | Poll Interval    |
  42  |-------------------|------------------|
  43  | //Minimum//       | 15 seconds       |
  44  | 6h                | about 30 seconds |
  45  | 12h               | about 1 minute   |
  46  | 1 day             | about 2 minutes  |
  47  | 2 days            | about 5 minutes  |
  48  | 3 days            | about 7 minutes  |
  49  
  50  This means that you may need to wait about 2 minutes for the first commit to
  51  be imported in the morning, and about 5 minutes after a long weekend, but other
  52  commits to active repositories should usually be recognized in 30 seconds or
  53  less.
  54  
  55  For repositories with no activity in the last 3 days, we wait longer between
  56  updates (1 second for every 4 minutes without activity). The table below has
  57  some examples.
  58  
  59  | Time Since Commit | Poll Interval    |
  60  |-------------------|------------------|
  61  | 4 days            | about 30 minutes |
  62  | 7 days            | about 45 minutes |
  63  | 10 days           | about 1 hour     |
  64  | 20 days           | about 2 hours    |
  65  | 30 days           | about 3 hours    |
  66  | //Maximum//       | 6 hours          |
  67  
  68  You can find the exact default poll frequency of a repository in
  69  Diffusion > (Choose a Repository) > Edit Repository, under "Update Frequency".
  70  You can also see the time when the repository was last updated in this
  71  interface.
  72  
  73  Repositories that are currently importing are always updated at the minimum
  74  update frequency so the import finishes as quickly as possible.
  75  
  76  
  77  Triggering Repository Updates
  78  =============================
  79  
  80  If you want Phabricator to update a repository more quickly than the default
  81  update frequency (for example, because you just pushed a commit to it), you can
  82  tell Phabricator that it should schedule an update as soon as possible.
  83  
  84  There are several ways to do this:
  85  
  86    - If you push changes with `arc land` or `arc commit`, this will be done
  87      for you automatically. These commits should normally be recognized within
  88      a few seconds.
  89    - If your repository is hosted on Phabricator, this will also be done for you
  90      automatically.
  91    - You can schedule an update from the web interface, in Diffusion >
  92      (Choose a Repository) > Edit Repository > Update Now.
  93    - You can make a call to the Conduit API method `diffusion.looksoon`. This
  94      hints to Phabricator that it should poll a repository as soon as it can.
  95      All of the other mechanisms do this under the hood.
  96  
  97  In particular, you may be able to add a commit hook to your external repository
  98  which calls `diffusion.looksoon`. This should make an external repository about
  99  as responsive as a hosted repository.
 100  
 101  If a repository has an update scheduled, the Diffusion > (Choose a
 102  Repository) > Edit Repository interface will show that the the repository is
 103  prioritized and will be updated soon.
 104  
 105  
 106  Troubleshooting Updates
 107  =======================
 108  
 109  You can manually run a repository update from the command line to troubleshoot
 110  issues, using the `--trace` flag to get full details:
 111  
 112    phabricator/ $ ./bin/repository update --trace <callsign>
 113  
 114  To catch potential issues with permissions, run this command as the same user
 115  that the daemons run as.