diff options
author | Ben Hutchings <ben.hutchings@codethink.co.uk> | 2020-05-18 16:06:38 +0100 |
---|---|---|
committer | Ben Hutchings <ben.hutchings@codethink.co.uk> | 2020-06-09 17:37:13 +0100 |
commit | e2d0d9d360a031910111e5f03d8e2f6c5faa5bd2 (patch) | |
tree | 364448478bb04a55479b21b4976dcb64e875c0b4 | |
parent | a45370880becf3a034fa8078fea029c957429e62 (diff) | |
download | lorry-controller-e2d0d9d360a031910111e5f03d8e2f6c5faa5bd2.tar.gz |
INSTALL: Document how to integrate Lorry/LC with each Downstream Host type
Document how to configure Gerrit, Gitea, and GitLab for use with
Lorry and Lorry Controller, and vice versa.
For Gitano/Trove, refer to the Baserock documentation.
Relates to #2.
-rw-r--r-- | INSTALL | 140 |
1 files changed, 140 insertions, 0 deletions
@@ -62,3 +62,143 @@ Controller on the host where they will run. Create an SSH key pair for Lorry, and install the *private* key in `.ssh` in Lorry's home directory. + +## Configuring the Downstream Host + +### Gerrit + +These instructions were written for Gerrit 3.1. + +1. Create a user for Lorry in Gerrit's authentication provider. + Add Lorry's SSH *public* key to the Gerrit user account. + +2. Create a group in Gerrit, or add the user to a group, that will be + permitted to create repositories and push changes to them. The + Lorry user should be a member but not an owner of this group. + +3. (Optional but strongly recommended) Create a parent project for + the mirror repositories and make this group the owner. + + Use the `gerrit create-project` command with the + `--permissions-only` option. Alternately, in the web UI, create + a new project and fill out the form as follows: + + * Set 'Repository name' as you wish. This is independent of the + names of repositories that Lorry will create. + * Leave 'Rights inherit' blank + * Set Owner to the group + * Set 'Create initial empty commit' to 'False' + * Set 'Only server as parent for other repositories' to 'True' + +4. Give the group permission to create repositories, + [bypass review](https://gerrit-review.googlesource.com/Documentation/user-upload.html#bypass_review), + [skip validation](https://gerrit-review.googlesource.com/Documentation/user-upload.html#skip_validation), + and push tags that aren't on a branch: + + * In 'All-Projects', give the group 'Create Project' permission. + In the web UI this is in the Global Capabilities section. + * In the parent project (or 'All-Projects'), give the group 'Forge + Author Identity', 'Forge Committer Identity', 'Forge Server + Identity', 'Push', and 'Push Merge Commit' permissions over + `refs/*` + * If you *did not* create a parent project, then in 'All-Projects' + also give the group 'Create Reference', 'Create Signed Tag', and + 'Create Annotated Tag' permissions over `refs/*` + +5. In `lorry.conf`: + + * Set `mirror-base-url-{fetch,push}` to + `git+ssh://`*username*`@`*hostname*`:29418` + * Set `push-option = skip-validation` + +6. In `webapp.conf`: + + * Set `downstream-host-type = gerrit` + * Set `downstream-ssh-url = ssh://`*username*`@`*hostname*`:29418` + * Set `gerrit-parent-project =` *parent-project* + +7. Add Gerrit's SSH host public key to `.ssh/known_hosts` in Lorry's + home directory. + +### Gitano + +Gitano and Lorry Controller would normally be deployed together as +part of a Trove: <http://wiki.baserock.org/Trove/reference/>. + +### Gitea + +These instructions were written for Gitea 1.11. + +1. Create a user for Lorry in Gitea (or its authentication provider). + Log in as the user and add Lorry's SSH *public* key to the user + account. Generate an access token for the user. + +2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to + `git+ssh://git@`*hostname* + +3. In `webapp.conf`: + + * Set `downstream-host-type = gitea` + * Set `downstream-visibility` to the desired visibility of + repositories: `private`, `internal`, or `public` + * Set `downstream-http-url` to the HTTPS or HTTP (not recommended) + URL of the Gitea server. + * Set `gitea-access-token =` *access-token* + +4. Add Gitea's SSH host public key to `.ssh/known_hosts` in Lorry's + home directory. + +Gitea requires all repositories to be organised under a user or +organisation, and organisations cannot contain other organisations. +You must therefore ensure that the CONFGIT specifies repository paths +with exactly two path components. + +Lorry Controller will attempt to create organisations as needed to +contain repositories. If your Gitea configuration does not allow +users to do this, you will need to create organisations in advance and +give the Lorry user permission to create repositories under them. + +### GitLab + +These instructions were written for GitLab CE 12.10. + +1. Create a user for Lorry in GitLab (or its authentication provider). + Add Lorry's SSH *public* key to the user account. Generate an + impersonation token for the user. + +2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to + `git+ssh://git@`*hostname* + +3. In `webapp.conf`: + + * Set `downstream-host-type = gitlab` + * Set `downstream-visibility` to the desired visibility of + repositories: `private`, `internal`, or `public` + * Set `downstream-http-url` to the HTTPS or HTTP (not recommended) + URL of the GitLab server. + * Set `gitlab-private-token =` *impersonation-token* + +4. Add GitLab's SSH host public key to `.ssh/known_hosts` in Lorry's + home directory. + +GitLab requires all projects to be organised under a user or group. +You must therefore ensure that the CONFGIT specifies repository paths +with at least two path components. + +Lorry Controller will attempt to create groups as needed to contain +projects. If your GitLab configuration does not allow users to do +this, you will need to create top-level groups in advance and give the +Lorry user permission to create subgroups and projects under them. + +### Local filesystem + +1. Create a directory to contain the repositories, writable by + the Lorry user. + +2. Set `mirror-base-url-{fetch,push}` in `lorry.conf` to the directory + name. + +3. In `webapp.conf`: + + * Set `downstream-host-type = local` + * Set `local-base-directory =` *directory* |