diff --git a/docs/docs/firmware/dev-setup.md b/docs/docs/firmware/dev-setup.md index 745a55b69..9c7dd3fdc 100644 --- a/docs/docs/firmware/dev-setup.md +++ b/docs/docs/firmware/dev-setup.md @@ -7,6 +7,93 @@ Follow these steps to begin developing in `racecar/firmware`. echo "Copy Me --->" +## Create an SSH Key + +=== "Windows" + + In an admin PowerShell terminal, enter the following command: + + ```text + ssh-keygen -t ed25519 -C "your_github_email@example.com" + ``` + + Save to the default location `c:/Users/YOU/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub. + + Continue with the following commands: + + ```text + type c:/Users/YOU/.ssh/id_ed25519 | clip + Get-Service -Name ssh-agent | Set-Service -StartupType Manual + Start-Service ssh-agent + ssh-add c:/Users/YOU/.ssh/id_ed25519 + ``` + +=== "Linux/Mac" + + In a terminal window, enter the following command: + + ```text + ssh-keygen -t ed25519 -C "your_github_email@example.com" + ``` + + Save to the default location `~/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub. + + Continue with the following commands: + + ```text + pbcopy < ~/.ssh/id_ed25519.pub + eval "$(ssh-agent -s)" + ssh-add ~/.ssh/id_ed25519 + ``` + +To add the key to your GitHub account, go to . + +- Name your key something descriptive. +- Select "Authentication Key" as the key type. +- Paste the contents of `id_ed25519.pub` into the "Key" box. +- Click "Add SSH Key". + +Open another terminal to test your connection to GitHub by entering the following command: + +```text +ssh -T git@github.com +``` + +Type "yes" when it asks if you want to continue connecting. +You should see a message like "Hi username! You've successfully authenticated, but GitHub does not provide shell access." + +Additional GitHub documentation can be found [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection). + +## Enable Commit Signing + +!!! warning + You must have a verified email address on GitHub to sign commits. + +To add a signing key to your GitHub account, go to . + +- Name your key something descriptive. +- Select "Signing Key" as the key type. +- Paste the contents of `id_ed25519.pub` into the "Key" box. +- Click "Add SSH Key". + +Update your git configuration to automatically sign commits with your key: + +=== "Windows" + ```text + git config --global user.signingkey c:/Users/YOU/.ssh/id_ed25519 + git config --global gpg.format=ssh + git config --global commit.gpgsign true + ``` + +=== "Linux/Mac" + ```text + git config --global user.signingkey ~/.ssh/id_ed25519 + git config --global gpg.format=ssh + git config --global commit.gpgsign true + ``` + +Additional GitHub documentation can be found [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key). + ## Dependencies === "Windows"