doc/git-interface.txt

   1 The aurweb Git and SSH interface
   2 ================================
   3
   4 Git storage
   5 -----------
   6
   7 Since release 4.0.0, aurweb uses Git repositories to store packages. Git
   8 namespaces (see gitnamespaces(7)) are used to share the object database, such
   9 that delta compression can be applied across package base boundaries.
  10
  11 Internally, all packages are stored in a single Git repository. Special refs,
  12 so-called namespaced branches, are used to refer to the commits corresponding
  13 to the actual package bases. For convenience, we also create a branch for each
  14 package repository that carries the name of the corresponding package base,
  15 such that one can easily access the history of a given package base by running
  16 `git log <pkgbase>`. To the end-user, the individual namespaced branches are
  17 presented as separate Git repositories.
  18
  19 Authentication: git-auth
  20 ------------------------
  21
  22 Pushing to package repositories is possible via SSH. In order to access the SSH
  23 interface, users first need to add an SSH public key to their account using the
  24 web interface. Authentication is performed by the git-auth
  25 AuthorizedKeysCommand script (see sshd_config(5) for details) which looks up
  26 the public key in the AUR user table. Using this concept of "virtual users",
  27 there is no need to create separate UNIX accounts for each registered AUR user.
  28
  29 If the public key is found, the corresponding authorized_keys line is printed
  30 to stdout. If the public key does not exist, the login is denied. The
  31 authorized_keys line also contains a forced command such that authenticated
  32 users cannot access anything on the server except for the aurweb SSH interface.
  33 The forced command can be configured in the aurweb configuration file and it
  34 usually points to the git-serve program.
  35
  36 If SSH has been configured to pass on the AUR_OVERWRITE environment variable
  37 (via SendEnv, see ssh_config(5) for details) and the user's account is a
  38 registered Trusted User or Developer, this will be passed on to the git-update
  39 program in order to enable a non-fast-forward push.
  40
  41 The INSTALL file in the top-level directory contains detailed instructions on
  42 how to configure sshd(8) to use git-auth for authentication.
  43
  44 The Shell: git-serve
  45 --------------------
  46
  47 The git-serve command, the "aurweb shell", provides different subcommands:
  48
  49 * The adopt/disown commands can be used to change ownership of a package base.
  50 * The flag/unflag commands can be used to flag/unflag a package.
  51 * The help command shows a list of available commands.
  52 * The list-repos command lists all repositories of the authenticated user.
  53 * The restore command can be used to restore a deleted package base.
  54 * The set-comaintainers command modifies the co-maintainers of a package base.
  55 * The set-keywords command modifies the keywords assigned to a package base.
  56 * The setup-repo command can be used to create a new repository.
  57 * The vote/unvote command can be used to vote/unvote for a package base.
  58 * The git-{receive,upload}-pack commands are redirected to git-shell(1).
  59
  60 The command is extracted from the SSH_ORIGINAL_COMMAND environment variable
  61 which is usually set by the SSH daemon. If no command is specified, git-serve
  62 displays a message stating that aurweb does not provide an interactive shell.
  63
  64 When invoking git-shell(1), the git-serve command also redirects all paths to
  65 the shared Git repository and sets up the GIT_NAMESPACE environment variable
  66 such that Git updates the correct namespaced branch.
  67
  68 The Update Hook: git-update
  69 ---------------------------
  70
  71 The Git update hook, called git-update, performs several subtasks:
  72
  73 * Prevent from creating branches or tags other than master.
  74 * Deny non-fast-forwards, except for Trusted Users and Developers.
  75 * Deny blacklisted packages, except for Trusted Users and Developers.
  76 * Verify each new commit (validate meta data, impose file size limits, ...)
  77 * Update package base information and package information in the database.
  78 * Update the named branch and the namespaced HEAD ref of the package.
  79
  80 It needs to be added to the shared Git repository, see INSTALL in the top-level
  81 directory for further information.
  82
  83 Accessing Git repositories via HTTP
  84 -----------------------------------
  85
  86 Git repositories can also be accessed via HTTP by configuring the web server to
  87 forward specific requests to git-http-backend(1). Note that, since Git
  88 namespaces are used internally, the web server needs to rewrite URIs and setup
  89 the GIT_NAMESPACE environment variable accordingly before forwarding a request.
  90
  91 An example configuration for nginx and fcgiwrap can be found in the INSTALL
  92 instructions in the top-level directory.
  93
  94 Further Configuration and Administration
  95 ----------------------------------------
  96
  97 When using Git namespaces, Git advertises refs outside the current namespace as
  98 so-called "have" lines. This is normally used to reduce traffic but it has the
  99 opposite effect in the case of aurweb: Most of the refs transferred to the
 100 client during `git push` operations belong to branches of other package bases
 101 and are essentially useless.
 102
 103 In order to omit these advertisements, one can add the strings "^refs/",
 104 "!refs/" and "!HEAD" to the transfer.hideRefs configuration setting. Note that
 105 the order of these patterns is important ("^refs/" must come first) and that
 106 Git 2.7 or newer is required for them to work.
 107
 108 Since garbage collection always affects all objects (from all namespaces), it
 109 is also recommended to disable automatic garbage collection by setting
 110 receive.autogc to false. Remember to periodically run `git gc` manually or
 111 setup a maintenance script which initiates the garbage collection if you follow
 112 this advice. For gc.pruneExpire, we recommend "3.months.ago", such that commits
 113 that became unreachable by TU intervention are kept for a while.