Git Authentication for Drupal.org Projects

Last updated on
1 March 2024

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

  1. Go to https://git.drupalcode.org/-/profile/keys
  2. Paste the public key you generated in the section above.
  3. 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:

  1. Go to https://git.drupalcode.org/-/user_settings/personal_access_tokens
  2. Name your token and select an expiration date in the next year
  3. Check “read_repository” & “write_repository”
  4. 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.

  1. Go to https://git.drupalcode.org/-/profile/keys
  2. Review the keys and note the fingerprints.
  3. 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 and id_rsa.pub are likely to be different for you.

  4. 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.

Tags

Help improve this page

Page status: No known problems

You can: