Configurations and Credentials
If you have not yet, you will need to get a GitHub account and to install Git on your local device. This document was constructed from Atlassian’s How to install Git tutorial and Git-SCM’s download pages 1–4.
This workshop is designed to be compatible with Bash command-line interfaces, which is the default setting for macOS with Terminal and many Linux distributions. Windows users will need to ensure their command-line interface is Bash compatible, as not all commands will work in other environments.
Sign Up for GitHub Account
To sign up for a GitHub account, navigate to github.com/ and click the Sign up button in the top right-hand corner. Fill in the required fields with your email, password, username, and country/region.
Your GitHub username must consist of alphanumeric characters or single hyphens and cannot begin or end with a hyphen. It’s important to carefully consider your username choice, especially if you plan to share it with professional collaborators or include it in your professional portfolio. Below are some suggestions to consider from the Happy Git and GitHub for the useR 5:
- Include your name.
- Keep it short and lowercase.
- Keep it consistent with other accounts you want associated with your work.
- Appropriate for sharing with an employer.
- Avoid highlighting temporary affiliations, such as the current university you attend.
- Ensure it’s unique and doesn’t have a special meaning in programming (e.g., avoid terms like
NA).
GitHub offers materials and short courses to help new users learn their interface: GitHub Skills, Repositories documentation, and About GitHub Command-Line Interface (CLI) 6–8.
Install Git
For all systems, you can confirm Git installation in the command-line interface:
Command-Line Application
git --versionCommand-Line Output
git version 2.49.0 # For Mac's
git version 2.51.0.windows.1 # For PC'sIf you do not get this output, you will need to install Git. In the following pages, we provide commonly applicable instructions for macOS, Windows, and the Debian/Ubuntu and Fedora Linux distributions.
Windows
Windows, by default, provides the PowerShell command-line interface, which does not support Bash commands. To emulate a Linux command-line interface, you have several options. The simplest option is to install Git for Windows, which provides both Git and Git Bash, a Bash shell environment 9.
Alternatively, you can emulate Linux command-line interfaces through other methods, or search for alternative commands compatible with the command-line interface you are using. If the option you are choosing does not include Git, it can be installed directly from: Git-SCM 3,10.
After you download Git for Windows, open the installer and follow the prompts. For this workshop, you can accept all default settings, but you may adjust them as desired. Below are some specific settings to consider as you go through the installer prompts.
The legacy Git system refers to the primary branch containing your files as “master.” During installation, you can prompt Git to label this branch as “main” instead.
SSH stands for “Secure Shell”, and it is the preferred secure transfer protocol used to communicate between your local device and the GitHub remote repository. You will want to ensure that OpenSSH is installed. The Git installer will provide you with the option to install OpenSSH during the setup process, and we recommend that you select this option.
Later in this workshop, we will discuss what Git is doing with the action. It is recommended that beginners select “Fast-Forward or Merge” by default, as rebasing is not beginner-friendly.
The Git credential Mmanager will cache your authentication information, making it easier to interact with remote repositories 11.
Mac
If XCode is installed in your Applications folder, Git is already available. However, you might not have the the osxkeychain credential manager, git-credential-osxkeychain, installed. If you plan to use HTTPS transfer protocols instead of SSH Keys, you might want to install this as it caches your authentication information in the macOS keychain, avoiding the need to re-enter them each time. You can skip to the directions for adding this capability if needed.
If XCode is not installed, you can install Git with the osxkeychain credential manager through either Homebrew or MacPorts 12,13. Assuming you have one of these already installed:
Command-Line Application
# With Homebrew
brew install git
# With MacPorts
sudo port install git +bash_completion +credential_osxkeychain +docInstalling Git using Homebrew or MacPorts will automatically include the osxkeychain credential manager. You can confirm its installation by running the following command 14:
Command-Line Application
git credential-osxkeychainCommand-Line Output
usage: git credential-osxkeychain <get|store|erase>If you do not get this output, run the following:
Command-Line Application
# 1. Install. Linebreak does NOT denote a space in the URL.
curl -O http://github-media-downloads.s3.amazonaws.com/osx/git-credential -osxkeychain
# 2. Relocate to ~/bin/.
sudo mv git-credential-osxkeychain /usr/local/bin/
# 3. Change file permissions to make it executable.
chmod u+x /usr/local/bin/git-credential-osxkeychain
# 4. Configure Git to use the osxkeychain credential manager.
git config --global credential.helper osxkeychainIf your OS X version is El Capitan (OS X 10.11) or earlier, you will need to download the tarball and build Git directly from the source.
Command-Line Application
# 1. If you do not have XCode Command Line Tools, install it.
xcode-select --install
# 2. Install openssl with Homebrew.
brew install openssl
# 3. Change file permissions to make it executable.
git clone https://github.com/git/git.git
# 4. Build Git from the source and adding flags.
NO_GETTEXT=1 make CFLAGS="-I/usr/local/opt/openssl/include" LDFLAGS="-L/usr/local/opt/openssl/lib"Linux and Unix
Git recommends using the preferred package manager for your distribution to install Git. However, if you prefer to download and build Git from a tarball, you can follow the instructions provided by Atlassian under the section Build Git from source on Linux.
Below, we have included instructions for several distributions. For information on additional systems, please visit the Git-SCM download page.
Command-Line Application
# Stable deployment of Debian/Ubuntu
apt-get install git
# Ubuntu Personal Package Archive (PPA)
add-apt-repository ppa:git-core/ppa
apt update
apt install git
# Fedora
yum install git # Up to Fedora 21
dnf install git # Fedora 22 and laterOnce you have Git installed and a GitHub account set up, you need to configure them to securely and accurately transfer information between your local devices and your remote repository on GitHub.
Configure Git
Git associates a username and email address with the project versions you create. You have the option to configure these settings globally, applying one user profile to all repositories, or locally, applying a user profile to a specific repository. A local setting will override the global setting 10,15.
Let’s begin by checking the current configurations on your system. Using --list --show-origin instead will display the file location for all configurations 16.
Command-Line Application
git config --listCommand-Line Output - Mac
gpg.format=ssh # SSH keys used for signing
commit.gpgsign=true # Sign all GitHub actions
filter.lfs.clean=git-lfs clean -- %f # Cleanly stores large files
filter.lfs.smudge=git-lfs smudge -- %f # Retrieves the large files
filter.lfs.process=git-lfs filter-process # Seamlessly manage large files
filter.lfs.required=true # List files in .gitattributes
init.defaultbranch=main # Default branch name is "main"
credential.helper=osxkeychain # Store credentials in Keychain
user.name=Shelby Golden # Username for commits
user.email=shelby.golden@yale.edu # Email for commits
pack.packsizelimit=50M # Sets size limit for pac filesCommand-Line Output - PC
http.sslbackend=schannel # SSL backend for HTTPS
diff.astexplain.texconv=astextplain # Diffs as "astextplain"
filter.lfs.clean=git-lfs clean -- %f # Cleanly stores large files
filter.lfs.smudge=git-lfs smudge -- %f # Retrieves the large files
filter.lfs.process=git-lfs filter-process # Seamlessly manage large files
filter.lfs.required=true # List files in .gitattributes
core.autocrlf=true # Standardize line ends
core.fscache=true # Enable filesystem caching
core.symlinks=false # Disables symbolic links
pull.rebase=false # Use merge when pulling
credential.helper=manager # Credential manager for PC
credential.https://dev.azure.com.usehttppath=true
init.defaultbranch=main # Default branch name is "main"
user.name=Shelby Golden # Username for commits
user.email=shelby.golden@yale.edu # Email for commitsThe results above are examples of potential configurations you might see on your system. In this example, the user.name and user.email settings are already configured.
If you do not see these configurations in your results, you will need to set them up on your system. We suggest you start by setting the global credential configurations. Use --local instead if you wish to apply the configurations to the currently open directory in your command-line interface.
Command-Line Application
git config --global user.name "Your Name Here"
git config --global user.email "your@email.com"If you make a mistake, you can use the --unset command to remove the configurations through the terminal, or you can modify the .gitconfig file directly 17.
Command-Line Application
git config --global --unset user.name
git config --global --unset user.emailIt is possible to automatically manage multiple credentials without needing to override the global settings in each folder. This is discussed in the Appendix.
Transfer Protocols
GitHub supports two types of authentication and file transfer protocols: Hypertext Transfer Protocol Secure (HTTPS) and Secure Shell (SSH) Keys. These protocols are used to securely and accurately communicate project access levels, rules, and, most importantly, to transfer files between your local device and the remote repository 18.
Below is a list of pros and cons for both 19–22:
| Criteria | SSH | HTTPS |
|---|---|---|
| Setup | More involved. | Easier for beginners. |
| Ease of Use | Low maintenance. | Requires username and PAT with each interaction. |
| Security | More secure. | Vulnerable to brute force attacks. |
| Permissions Control | Fine- and coarse-grained options. | Coarser permissions for PAT set by GitHub. |
| Signing | SSH Keys and GNU Privacy Guard (GPG) | GPG and S/MIME |
| Other | Additional security with Hardware Keys 23. | Never blocked by firewalls and proxies 18. |
Previously, GitHub allowed authentication with a username and password, but in 2021 the password requirement was replaced with PATs. Credential managers were adjusted to accommodate this change and should store the PAT accordingly.
We provide basic instructions to configure your Git and GitHub for both methods. Advanced settings are not covered here, but relevant links are sometimes provided to help with these setups. Users are encouraged to explore these resources as needed for their individual projects.
HTTPS
These directions were provided in the Managing your personal access tokens article provided on docs.github.com 22.
- Go to your GitHub account settings page.
- At the end of the left sidebar, click on “
Developer Settings”. - In the left sidebar open the “
Personal access tokens” drop-down menu and click on “Tokens (classic)”. - In the center of the window, there is a drop-down menu. Select “Generate new token (classic)”.
- Add a note describing what the PAT is for and set its expiration time-frame.
You have the option to select “No expiration,” but this option is strongly discouraged for security purposes.
- In the “Select scopes” section, check “repo” for full control of private repositories.
We do not cover the different ways repository access can be fine-tuned. If you wish to learn more about the access permission levels possible through GitHub, you can read the article provided on docs.github.com 26.
- At the bottom of the page, click Generate token.
- Copy the generated PAT and save it somewhere secure for later use, as you will not be able to access it again after you exit the window.
Every time you interact with GitHub, you will enter your PAT instead of your account password. For example:
Command-Line Application
git clone https://github.com/USERNAME/REPO.git
Username: YOUR-USERNAME
Password: YOUR-PERSONAL-ACCESS-TOKENSSH Keys
SSH Keys work by creating a private and public key pair. When interacting with the remote repository, the keys are compared to determine access permissions. We will use the command-line interface to generate these keys, and you will upload your public key to GitHub to complete the process 21,27,28.
It is best practice to review your system for any existing private/public key pairs.
Command-Line Application
ls –al ~/.ssh # List all elements in the .ssh directoryCommand-Line Output - SSH Keys Exist
. # Unix-like reference to current directory
.. # Unix-like reference to parent directory
.DS_Store # MacOS folder custom attributes metadata
config # SSH Key configurations
id_ed25519 # SSH authentication local key
id_ed25519.pub # SSH authentication public key
id_ed25519_signing # SSH signing local key
id_ed25519_signing.pub # SSH signing public key
known_hosts # GitHub's SSH Key fingerprintsCommand-Line Output - No Previous Keys Available
ls: cannot access `/c/Users/userID/.ssh`: No such file or directoryIn this example, you can see that I have two SSH key pairs: one for authentication and one for signing. They are configured to use the Edwards-curve Digital Signature Algorithm (id_ed25519), a type of public-key cryptography algorithm. You might also see Rivest-Shamir-Adleman (id_rsa) or Elliptic Curve Digital Signature Algorithm (id_ecdsa) 29,30.
While RSA is widely used and is compatible with SHA-1 and SHA-2 hash algorithms, ED25519 is considered to be more efficient, faster, and more secure because of its elliptic curve design. It is also a more modern method for cryptography compared to RSA 30.
We will show you how to generate an id_ed25519 or id_rsa SSH key. Consider the points provided below when choosing an algorithm.
As of March 15, 2022, GitHub no longer supports the ssh-dss algorithm. If your setup uses this algorithm, you will need to delete those keys and replace them with either id_rsa or id_ed25519 21.
SSH keys generated using the RSA algorithm after November 2, 2021, must be specified to use the SHA-2 hash algorithm length. RSA keys with a valid_after date set before this date can use either SHA-1 or SHA-2 21,29.
You can verify the key length with ssh-keygen -l -f ~/.ssh/id_rsa.pub, changing the file name as needed. If the length is 2048, the key is using SHA-1. If the length is 4096, it is using SHA-2 29.
We suggest replacing any SHA-1 configured keys with SHA-2 configured keys.
GitHub requires different SSH Keys for account authentication and signing, which verify the authenticity and integrity of GitHub actions 31. At a minimum, you will need keys for authentication, while signing is optional. The same setup is applied for both options, except when specifying the purpose of the key to GitHub.
The astute student might have observed that my system is set to automatically sign all actions in GitHub with commit.gpgsign=true in the .gitconfig file. If you choose to create a pair of SSH keys for signing, it is recommended that you add this to your configuration with: git config commit.gpgsign true.
The GPG Suite for macOS and Gpg4win for Windows will allow you to configure the GPG agent and save your signing credentials. You can learn more about signing commits in the About commit signature verification and Signing commits articles provided on docs.github.com 31–33.
Now that you have chosen an SSH algorithm from ED25519 or RSA, we can generate the public and private key pair.
Command-Line Application
# Ed25519
ssh-keygen -t ed25519 -C "your@email.com"
# RSA with SHA-2
ssh-keygen -t rsa -b 4096 -C "your@email.com"Command-Line Output - ED25519
Generating public/private ed25519 key pair.
Enter a file in which to save the key (/Users/userID/.ssh/id_ed25519): Command-Line Output - RSA
Generating public/private rsa key pair.
Enter a file in which to save the key (/Users/userID/.ssh/id_rsa): After the keys have been created, you are given the option to specify where they will be stored, and you can modify the key name if desired. It is easier to keep the SSH key pairs stored in the ~/.ssh directory, avoiding additional configuration settings.
If you want to change the key name, you must keep the id_ed25519 or id_rsa prefix, as this tells your system which algorithm to use. For example:
Command-Line Output - ED25519
# Hit enter to accept the default location and file name
Enter a file in which to save the key (/Users/userID/.ssh/id_ed25519):
# Specify a new file name, keeping the default location
Enter a file in which to save the key (/Users/userID/.ssh/id_ed25519): /Users/userID/.ssh/id_ed25519_modify_nameContinuing with the ED25519 example, as the steps will be the same for RSA going forward, you will be given the option to add a password to your key. We highly suggest that you use a strong password and save it somewhere secure for later use. If needed, you can change the password down the line, but you will not be able to recover it if you lose it 27
Command-Line Output - ED25519
Enter passphrase for "/Users/userID/.ssh/id_ed25519" (empty for no passphrase):
Enter same passphrase again:Command-Line Output - ED25519
Your identification has been saved in /Users/userID/.ssh/id_ed25519
Your public key has been saved in /Users/userID/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:nmQLX/8Tew2X1ju3sOb4wSNK+HIycT0LKEsPzYfN+Ms shelby.golden@yale.edu
The key's randomart image is:
+--[ED25519 256]--+
| |
| |
| |
| |
| + S o o|
| + &.X +. ooo|
| . =.X...+=.=o|
| . =+o..ooBo+|
| =E..++.++|
+----[SHA256]-----+When you have successfully created your keys, you will see the final output shown above. It is not necessary to save the fingerprint or randomart (visual representation of the fingerprint), but I personally save them in the notes section of my password manager.
Similarly to HTTPS, it is possible to cache your SSH key password using agent forwarding. While we won’t cover the setup process here, you can learn more about it and find detailed instructions in the Using SSH agent forwarding and Generating a new SSH key and adding it to the ssh-agent articles on docs.github.com 34,35.
With our public and private SSH key pairs created, we are ready to add the public one to our GitHub account. Start by copying the recently created public key.
Command-Line Application - ED25519
pbcopy < ~/.ssh/id_ed25519.pubGo to your GitHub account settings page.
In the “Access” section of the left sidebar, click on “
SSH and GPG Keys”. Click the New SSH key button in the top right.
Add a title explaining the use of the key (e.g., Personal laptop).
Select “Authentication key” as the key type.
In the “Key” field, paste the public key you copied above.
Click Add SSH key and follow the prompts.
To ensure a valid connection with GitHub, you will need to open the ~/.ssh/known_hosts file and copy-and-paste GitHub’s SSH key fingerprints 36.
You can confirm that the keys are correctly configured with the following test. If you get the expected output shown below, then you are all set!
Command-Line Application
ssh -T git@github.comCommand-Line Output
Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.Advanced Configurations
Multiple Git Configurations
Suppose you use two or more GitHub accounts and need different emails or usernames associated with Git commits made to those remote repositories. Reconfiguring every project directory for this purpose would be tedious.
Instead, you can use an automatically expanded local setting to override the global configurations using “Conditional Includes”. This feature has been available since Git version 2.13 37–39.
In this framework, you need to organize your project directories such that those with an alternate configuration are in the same parent directory. We will refer to this parent directory as “Alternate.” The directions given here assume that you have already set up the global Git configurations.
We start by locating and opening the .gitconfig file.
Command-Line Application
git config --list --show-originCommand-Line Abbreviated Output
:
file:/Users/userID/.gitconfig user.email=shelby.golden@yale.edu
file:/Users/userID/.gitconfig user.name=Shelby Golden
:When you open .gitconfig with Finder/File Explorer, you will see something like this:
~/Users/userID/.gitconfig
[user]
email = shelby.golden@yale.edu
name = Shelby Golden
signingkey = /Users/userID/.ssh/id_ed25519_jhu_signing.pub
[gpg]
format = ssh
[commit]
gpgsign = true
[init]
defaultBranch = main
[filter “lfs”]
required = true
clean = git-lfs clean – %f
smudge = git-lfs smudge – %f
process = git-lfs filter-process
[pack]
packSizeLimit = 50M
After the [user] section, add the conditional include statement. The order of the sections does not matter, but the indentation is important to keep consistent.
~/Users/userID/.gitconfig
[user]
email = shelby.golden@yale.edu
name = Shelby Golden
signingkey = /Users/userID/.ssh/id_ed25519_jhu_signing.pub
[includeIf “gitdir:/Users/userID/Desktop/…/Alternate/”]
path = /Users/userID/Desktop/DSDE/…/Alternate/.gitconfig
:
Now we need to create the Git configuration file applicable to all projects stored in ~/Alternate.
Command-Line Application
# 1. Navigate to the alternative account parent directory.
cd "/FILE_PATH/Alternate"
# 2. Create a new configuration file.
touch .gitconfigOpen the ~/Alternate/.gitconfig file, either using the vim in the command-line interface or by opening it with Finder/File Explorer, and add the relevant Git configurations you want applied to this account.
~/Alternate/.gitconfig
[user]
email = shelby.golden@gmail.com
signingkey = /Users/userID/.ssh/id_ed25519_personal_signing.pub
[gpg]
formal = ssh
[commit]
gpgsign = true
:
Configuring SSH Keys to Different Hosts
Suppose you want to use SSH Keys to interact with remote repositories stored on different domains, such as GitHub and GitLab. You will need to create a new document called config in the ~/.ssh directory.
Command-Line Application
# 1. Navigate to the .ssh directory.
cd /Users/userID/.ssh
# 2. Create a new configuration file.
touch configOpen the ~/.ssh/config file, either using vim in the command-line interface or by opening it with Finder/File Explorer, and add the relevant SSH configurations necessary to coordinate file transfers between different remote account locations.
For example, my configuration document looks like this:
~/.ssh/config
Host github.com
User git
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519_github
Host gitlab.com
User git
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519_gitlab