diff --git a/docs/docs/firmware/dev-setup.md b/docs/docs/firmware/dev-setup.md index 9c7dd3fdc..745a55b69 100644 --- a/docs/docs/firmware/dev-setup.md +++ b/docs/docs/firmware/dev-setup.md @@ -7,93 +7,6 @@ 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" diff --git a/docs/docs/tutorials/ssh-signing.md b/docs/docs/tutorials/ssh-signing.md new file mode 100644 index 000000000..4fe4ff0cd --- /dev/null +++ b/docs/docs/tutorials/ssh-signing.md @@ -0,0 +1,91 @@ +# :material-key: SSH and Commit Signing + +This tutorial will guide you through setting up SSH keys and commit signing for GitHub. SSH keys are a more secure way to connect to GitHub, rather than other protocols like HTTPS. Commit signing is used to verify that commits are coming from you and have not been tampered with. + +!!! warning + You must have a verified email address on GitHub to add SSH keys and sign commits. + +## 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 SSH 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 + +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 in your terminal 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 commit signing GitHub documentation can be found [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key). + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e01b35c63..5494a0d69 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -119,6 +119,7 @@ nav: - tutorials/site-dev.md - tutorials/wsl-can/index.md - tutorials/hw-debug.md + - tutorials/ssh-signing.md - Firmware: - firmware/index.md - firmware/dev-setup.md