On this page
- Authenticating with SSH Keys
- Private Key
- Public Key
- Generating your keys
- Adding your public key to Drupal.org
- Testing that your SSH keys work
- Cloning over HTTPS
- Authenticating for pushing over HTTPS
- Troubleshooting
- Double check SSH keys
- Verify which SSH keys your Git client is using
- WARNING: POSSIBLE DNS SPOOFING DETECTED! and/or WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
- Changes for March 2019 migration of git.drupalcode.org to GitLab
- Changing Git remotes
- Sandbox projects
- The git:// protocol
Git Authentication for Drupal.org Projects
Authenticating with SSH Keys
The most common way to authenticate is using SSH keys. Although SSH keys are slightly more work to set up initially, they are far less hassle on a day-to-day basis, and far more secure than using even very long passwords in the same scenarios. An SSH key is a pair of cryptographic keys consisting of a private key and a public key.
Note that these instructions assume that Git access has been setup in the user profile. You must set up your Git user name and agree to the Git access agreement before any of the following instructions will lead to success.
Private Key
The private key must be kept strictly confidential. You keep it to yourself and never send it by email, etc. You need a private key on every computer/account where you will use Git.
Drupal.org allows you to use as many key pairs as you like. Thus, you can create a public/private key pair for each computer you use. But if you prefer using only one key pair for all of your computers, you can copy your private key to each of them.
Public Key
You share the public key on code repositories such as GitHub, Drupal.org, or any other SSH server you use. When you try to connect to the repository, the SSH system checks if your (local) private key corresponds with any of the (remote) public keys Drupal.org has. If there is a match, access is granted. You can share your public key with anyone at any time without compromising security.
Generating your keys
If you do not already have a public/private SSH key pair, you will need to generate a pair of keys (if you are using Windows, do this in from a terminal window in your User folder). After generating a key pair, the public key can be found in the id_rsa.pub file that is generated.
Adding your public key to Drupal.org
- Go to https://git.drupalcode.org/-/profile/keys
- Paste the public key you generated in the section above.
- Click Add key.
Testing that your SSH keys work
You can test that your ssh keys work by running the following command:
ssh -T git@git.drupal.org
When it works the response should be something like: "Welcome to GitLab, @username!" Where the @username is your username.
Cloning over HTTPS
For simply cloning a repository, use HTTPS. For example, here’s the command for cloning the Drupal core repository:
$ git clone https://git.drupal.org/project/drupal.git
HTTPS should be used when you will only be reading from a repository.
Authenticating for pushing over HTTPS
If SSH is blocked or otherwise not usable for you, you can git push
over an HTTPS connection. You will need to generate a personal access token which will be used as a password:
- Go to https://git.drupalcode.org/-/user_settings/personal_access_tokens
- Name your token and select an expiration date in the next year
- Check “read_repository” & “write_repository”
- Copy your new personal access token, this will be used as a password when using Git clients
Troubleshooting
Double check SSH keys
Make sure key fingerprints match up.
- Go to https://git.drupalcode.org/-/profile/keys
- Review the keys and note the fingerprints.
- The fingerprint should match up with the keys on your computer:
$ ssh-keygen -l -E md5 -f ~/.ssh/id_rsa 2048 MD5:76:d2:c7:… $ ssh-keygen -l -E md5 -f ~/.ssh/id_rsa.pub 2048 MD5:76:d2:c7:…
The filenames
id_rsa
andid_rsa.pub
are likely to be different for you. - Delete any keys on Drupal.org with fingerprints you can’t match up. Add any keys needed, creating new keys if needed.
Verify which SSH keys your Git client is using
Prefix Git commands with GIT_SSH_COMMAND='ssh -vvv'
to check that your Git client is using the SSH keys you expect. For example, GIT_SSH_COMMAND='ssh -v' git pull
You should see lines like debug1: Will attempt key: …
WARNING: POSSIBLE DNS SPOOFING DETECTED! and/or WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
If your receive error messages that the git.drupal.org remote host key has changed you may need to remove the old key from your hosts file.
You can do so with the command below, or by manually editing your ~/.ssh/known_hosts
to remove the line for git.drupal.org
$ ssh-keygen -R git.drupal.org
To validate that you are receiving the correct key, you can check it against the key fingerprints recorded here.
Changes for March 2019 migration of git.drupalcode.org to GitLab
Authentication methods for Drupal.org’s Git repositories changed March 2019. In particular:
- Git remotes have changed
- SSH keys are now recommended for all authentication needs
- Password authentication for SSH connections has been deprecated
- HTTPS clones are unchanged
- A new HTTPS personal access token authentication method is available for pushes when SSH is inaccessible
- For sandbox projects, both Git and HTTPS urls are changing
- Note that only SSH and HTTPS protocols are supported.
- The git:// protocol may have worked in the past, but is an unsupported method and will not work with the transition to GitLab!
- The git.drupal.org ssh host key has changed.
Changing Git remotes
If you are a maintainer who has an established Git remote in the format <username>@git.drupal.org:project/<yourproject>.git
, the format should be changed to git@git.drupal.org:project/<yourproject>.git
.
You can check your current Git remotes by using:
$ cd /your/local/repository/directory
$ git remote -v
You can use $ git remote set-url origin
to make this change for existing repositories you have cloned. If your Git remote is called something other than 'origin' use that name instead.
For example:
$ cd /your/local/repository/directory
$ git remote set-url origin git@git.drupal.org:project/<yourproject>.git
Sandbox projects
HTTP clones for sandbox projects changed from: https://git.drupal.org/sandbox/<author-username>/<project-node-id>.git
to: https://git.drupal.org/sandbox/<author-username>-<project-node-id>.git
Git urls for sandboxes changed from the format <username>@>git.drupal.org:sandbox/<author-username>/<project-node-id>.git
, the format should be changed to: git@git.drupal.org:sandbox/<author-username>-<project-node-id>.git
The git:// protocol
Drupal.org supports the HTTPS and SSH protocols for git, but does not support the git:// protocol. The git:// protocol may have worked in our older Git environment, but will not work under GitLab. If you are using this protocol please update to the https or ssh methods above.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion