post-receive hook

Two files of importance, post-receive and deploy.

  • post-receive
    It contains the logic common to all repositories. It loads the deploy file.
    Located elsewhere. There is a symlink to it in the hooks directory of every repository.
  • deploy
    It contains the logic specific to a repository.
    It is not a script. It is a collection of bash functions and environmental variables.
    It is located in the hooks directory. If it is absent, post-receive will do nothing.

deploy

The variables which be can defined are flags, chkoutdir, hubrepo. The functions are check, pre_chkout, and post_chkout. There are a few other variables and utility functions, repod, chkoutbranch, oldc, newc, branch, msg, act, and err.

flags

flags is an array. A flag is of just two values, enabled and disabled, and is used to control whether certain tasks are performed or not.

To enable a flag, just list it in the array. To disable a flag, put a '!' at the start of the name, e.g. '!foo'.

Flags are tested in the code using [[ -n ]].

NameDefault ValueDescription
awbotenabledcall awbot to announce changes on IRC
GitHubdisabledpush –mirror to GitHub
chkoutenabledas easy way to disable checkouts without making a check()

chkoutdir

The directory to checkout into. The default location is ${HOME}/worktrees/${GL_REPO}.wrk.

hubrepo

The repository on GitHub to push –mirror to. The default is 'archwomen/reponame.git'.

check

Is a function which returns an exit code of zero if deployment can be done and any other number otherwise.

check can do a variety of tasks before checkout. For example it can ensure the directory to checkout in exists. If the directory can not be made or can not be written to, check can block deployment.

This function (and subsequent deployment) are run once for every ref pushed. (Though it is not currently needed, one can have each ref deployed to a different location.)

The default is to deploy if changes are to branch master and if the checkout directory exists with write permissions.

pre_chkout and post_chkout

Functions to perform tasks before and after checkout.

Examples,

  • change permissions of some directories so that they are writable by the web server
  • check if files not tracked by git were accidentally deleted during checkout and if so, alert the user
  • systemctl reload some_daemon.service

Note The difference between check and pre_chkout functions is a subtle one. If a task requires canceling deployment on failure, put it in the check function. Otherwise put it in pre_chkout.

chkoutbranch

The ref name used in checkout. The code is something like checkout -f $chkoutbranch. Can change it to something else only if absolutely needed.

oldc, newc, and branch

These are respectively, the last commit before the push, the latest commit pushed, and the branch being pushed. Use them in check and {pre,post}_chkout functions but do not overwrite them.

msg, act, and err

Functions to send messages to the user. The messages are colored.

FunctionColorDescription
msgyellowsimple message
actblueinform user that some manual work is required (may need shell access so would have to ping an admin)
errredHalp! something error happened ;_;

repod

The root of the bare repository. Set as ${GL_REPO_BASE}/${GL_REPO}.git and cd'd to before calling check.

Algorithm

This overview of the process followed by post-receive is not exact. Check the code for specifics.

  • source hooks/deploy
  • define functions and defaults
  • parse flags
  • for each ref/branch pushed
    • cd the root of bare repo - important
    • run check
    • if check returns zero and chkout flag set, deploy
      • run pre_chkout
      • do checkout -f
      • run post_chkout
    • if awbot flag is set, call awbot
  • push –mirror to GitHub

aw-tech/deployment.txt · Last modified: 2014/03/13 21:45 by fsckd