grgit-authentication
Description
|
JSCH authentication (and its agent proxy) are not supported in Grgit 3.x. If you’re using Grgit 2.x, see the documentation for that version. |
Grgit communicates with remote repositories in one of three ways:
-
HTTP(S) protocol with basic auth credentials (i.e. username/password).
Where possible, use of HTTPS urls is preferred over the SSH options. It has far simpler behavior than the SSH options. -
SSH protocol using
sshorplinkdirectly. This approach should work as long as you can push/pull on your machine.You should be using an SSH agent to have your key loaded before Grgit runs.
HTTP BasicAuth Credentials
These are presented in precedence order (direct parameter in code, system properties, environment variables).
Parameter to Grgit operations
Some Grgit operations, such as grgit-clone allow you to provide credentials programmatically.
import org.ajoberstar.grgit.Grgit
import org.ajoberstar.grgit.Credentials
def grgit = Grgit.clone(dir: '...', url: '...', credentials: new Credentials(username, password))System Properties
- org.ajoberstar.grgit.auth.username
-
Username to provide when basic authentication credentials are needed. Username can be specified without a password (e.g. using a GitHub auth token as the user and providing no password).
- org.ajoberstar.grgit.auth.password
-
Password to provide when basic authentication credentials are needed.
Environment Variables
- GRGIT_USER
-
Username to provide when basic authentication credentials are needed. Username can be specified without a password (e.g. using a GitHub auth token as the user and providing no password).
- GRGIT_PASS
-
Password to provide when basic authentication credentials are needed.
SSH
If the GIT_SSH environment variable is set, that command will be used. If not, Grgit will scan your PATH for an ssh (preferred) or plink command.
Any keys your ssh or plink can natively pick up will be used. This should include keys in default locations (e.g. ~/) and any compatible SSH agent or OS keychain.
|
Grgit cannot provide credentials to the system |
Examples
This is a non-exhaustive list of examples of how to configure authentication in common scenarios.
Using a GitHub auth token with HTTPS URLs
Set the environment variable GRGIT_USER to your authentication token from GitHub.
Using a Username and Password with HTTPS URLs
Set the system properties:
groovy -Dorg.ajoberstar.grgit.auth.username=someone -Dorg.ajoberstar.grgit.auth.password=mysecretpassword myscript.groovy