From 407d3ae5ab84804f75700b2401ed8a9db6f5de70 Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Mon, 29 Mar 2021 00:04:40 +0300 Subject: add docs/ --- docs/auth.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/auth.md diff --git a/docs/auth.md b/docs/auth.md new file mode 100644 index 0000000..3b64fd9 --- /dev/null +++ b/docs/auth.md @@ -0,0 +1,29 @@ +In order to access private repositories hosted on a third-party platform like +GitHub or Bitbucket, cgitize needs to pass authentication on the hosting +server. Authentication in Git is done either via HTTPS, or via SSH. + +When using SSH, there're multiple methods to give cgitize access to SSH keys. + +1. Use SSH keys (possibly passwordless) directly. This is stupid, since it + would require storing SSH keys and the passwords to them on the cgitize + server. Plus, I don't think either GitHub or Bitbucket support read-only + SSH keys. + +2. Give cgitize access to a ssh-agent. This is less stupid, but would require + a cumbersome setup. The host ssh-agent can be used (including when cgitize + is run in a Docker container), but in my experience, this is somewhat + inconvenient (you have to add keys manually to the ssh-agent every time you + reboot, etc.). + +When using HTTPS, there're multiple options to access the private repositories. + +1. Pass the account password in the URL. Doesn't work with 2FA, incredibly + insecure. + +2. Use OAuth. I thought this was too complicated to implement quickly. + +3. Use per-application passwords. This option is pretty cool. Both GitHub (in + the form of "personal access tokens") and Bitbucket (calls them "app + passwords") support creating one-purpose passwords that are supposed to be + used by a single app only. They allow to bypass the 2FA also. cgitize will + support this option. -- cgit v1.2.3