<NME> walkthrough.md
<BEF> # SSH Deploy Keys Walkthrough

If the instructions in [Authentication: SSH Deploy Keys](@ref) did not work for you (for example,
`ssh-keygen` is not installed), don't worry! This walkthrough will guide you through the
process. There are three main steps:

1. [Generating an SSH Key](@ref)
2. [Adding the Public Key to GitHub](@ref)
3. [Adding the Private Key to Travis](@ref)

## Generating an SSH Key

The first step is to generate an SSH key. An SSH key is made up of two components: a
*public* key, which can be shared publicly, and a *private* key, which you should ensure is
**never** shared publicly.

The public key usually looks something like this

```
ssh-rsa [base64-encoded-key] [optional-comment]
```

And the private key usually look something like this

```
-----BEGIN RSA PRIVATE KEY-----
 ... base64-encoded key over several lines ...
-----END RSA PRIVATE KEY-----
```

### If you have `ssh-keygen` installed

If you have `ssh-keygen` installed, but `Travis.genkeys()` didn't work, you can generate an
SSH key as follows. First, generate a key using `ssh-keygen` and save it to the file
`privatekey`:

```julia
shell> ssh-keygen -N "" -f privatekey
```

Next, we need to encode the private key in Base64. Run the following command:

```julia
julia> using Base64

julia> read("privatekey", String) |> base64encode |>  println
```

Copy and paste the output somewhere. This is your *private key* and is required for the step
[Adding the Private Key to Travis](@ref).

Now we need to get the public key. Run the following command:

```julia
julia> read("privatekey.pub", String) |> println
```

Copy and paste the output somewhere. This is your *public key* and is required for the step
[Adding the Public Key to GitHub or Gitea such as Codeberg](@ref).

### If you do not have `ssh-keygen`

If you're using Windows, you probably don't have `ssh-keygen` installed. Instead, we're
going to use a program called PuTTY. The first step in the process to generate a new SSH key
is to download PuTTY:

* Download and install [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/)

PuTTY is actually a collection of a few different programs. We need to use PuTTYgen. Open
it, and you should get a window that looks like:

![](puttygen.png)

Now we need to generate a key.

* Click the "Generate" button, then follow the instructions and move the mouse around to
  create randomness.

Once you've moved the mouse enough, the window should look like:

![](puttygen-generated.png)

Now we need to save the public key somewhere.

* Copy the text in the box titled "Public key for pasting into OpenSSH authorized_keys file"
  and paste it somewhere for later. This is your *public key* and is required for the step
  [Adding the Public Key to GitHub or Gitea such as Codeberg](@ref)

Finally, we need to save the private key somewhere.

* Click the "Conversions" tab, and then click "Export OpenSSH key". Save that file
  somewhere. That file is your *private key* and is required for the [Adding the Private Key
  to Travis](@ref) step.

  ![](puttygen-export-private-key.png)

  !!! note

      Don't save your key via the "Save private key" button as this will save the key in the
      wrong format.

If you made it this far, congratulations! You now have the private and public keys needed to
set up automatic deployment of your documentation. The next steps are to add the keys to
GitHub and Travis.


## Adding the Public Key to GitHub or Gitea such as Codeberg

In this section, we explain how to upload a public SSH key to GitHub and Gitea such as Codeberg. By this point
, you should have generated a public key and saved it to a file. If you haven't done this, go read
[Generating an SSH Key](@ref).

Go to `https://github.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys` for GitHub and `https://somegiteaname.org/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys` and click "Add
deploy key". You should get to a page that looks like,:

**GitHub**

![github-add-deploy-key](github-add-deploy-key.png)

**Gitea**

![gitea-codeberg-add-deploy-key](gitea-codeberg-add-deploy-key.png)
3. Make sure that the "Allow write access" box is checked.

Once you're done, click "Add key". Congratulations! You've added the public key
to GitHub. The next step is to add the private key to Travis.


## Adding the Private Key to Travis

In this section, we explain how to upload a private SSH key to Travis. By this point, you
should have generated a private key and saved it to a file. If you haven't done this, go
read [Generating an SSH Key](@ref).


In this section, we explain how to upload a private SSH key to Travis. By this point, you
should have generated a private key and saved it to a file. If you haven't done this, go
read [Generating an SSH Key](@ref).

First, we need to Base64 encode the private key. Open Julia, and run the command


Copy the resulting output.

Next, go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
to the "Environment Variables" section. It should look like this:

![](travis-variables.png)
```bash
$ openssl enc -base64 -in path/to/your/private/key -out path/to/your/base/64/encoded/key
$ # We need to truncate the newlines
$ cat path/to/your/base/64/encoded/key | tr -d "\n"
```

Copy the resulting output.

Go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
to the "Environment Variables" section. It should look like this:

![](travis-variables.png)

    expose this variable in your tests, nor merge any code that does. You can read more
    about Travis environment variables in [Travis User Documentation](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).

---

**Final Remarks**
    about Travis environment variables in [Travis User Documentation](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).

---

**Final Remarks**

You should now be able to continue on with the [Hosting Documentation](@ref).

<MSG> Update docs for new DocumenterTools.genkeys function. (#1156)


<DFF> @@ -6,7 +6,7 @@ process. There are three main steps:
 
 1. [Generating an SSH Key](@ref)
 2. [Adding the Public Key to GitHub](@ref)
-3. [Adding the Private Key to Travis](@ref)
+3. [Adding the Private Key](@ref)
 
 ## Generating an SSH Key
 
@@ -30,7 +30,7 @@ And the private key usually look something like this
 
 ### If you have `ssh-keygen` installed
 
-If you have `ssh-keygen` installed, but `Travis.genkeys()` didn't work, you can generate an
+If you have `ssh-keygen` installed, but `DocumenterTools.genkeys()` didn't work, you can generate an
 SSH key as follows. First, generate a key using `ssh-keygen` and save it to the file
 `privatekey`:
 
@@ -46,8 +46,7 @@ julia> using Base64
 julia> read("privatekey", String) |> base64encode |>  println
 ```
 
-Copy and paste the output somewhere. This is your *private key* and is required for the step
-[Adding the Private Key to Travis](@ref).
+Copy and paste the output somewhere. This is your *private key* and is required for the last step.
 
 Now we need to get the public key. Run the following command:
 
@@ -89,8 +88,7 @@ Now we need to save the public key somewhere.
 Finally, we need to save the private key somewhere.
 
 * Click the "Conversions" tab, and then click "Export OpenSSH key". Save that file
-  somewhere. That file is your *private key* and is required for the [Adding the Private Key
-  to Travis](@ref) step.
+  somewhere. That file is your *private key* and is required for the last step.
 
   ![](puttygen-export-private-key.png)
 
@@ -123,12 +121,13 @@ Now we need to fill in three pieces of information.
 3. Make sure that the "Allow write access" box is checked.
 
 Once you're done, click "Add key". Congratulations! You've added the public key
-to GitHub. The next step is to add the private key to Travis.
+to GitHub. The next step is to add the private key to Travis or GitHub Secrets.
 
 
-## Adding the Private Key to Travis
+## Adding the Private Key
 
-In this section, we explain how to upload a private SSH key to Travis. By this point, you
+In this section, we explain how to upload a private SSH key to Travis or GitHub Actions,
+depending on which service you will use for deploying your documentation. By this point, you
 should have generated a private key and saved it to a file. If you haven't done this, go
 read [Generating an SSH Key](@ref).
 
@@ -142,7 +141,9 @@ julia> read("path/to/private/key", String) |> base64encode |> println
 
 Copy the resulting output.
 
-Next, go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
+### Adding the Private Key to Travis
+
+Go to `https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings`. Scroll down
 to the "Environment Variables" section. It should look like this:
 
 ![](travis-variables.png)
@@ -162,6 +163,13 @@ Congratulations! You've added the private key to Travis.
     expose this variable in your tests, nor merge any code that does. You can read more
     about Travis environment variables in [Travis User Documentation](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).
 
+
+### Adding the Private Key to GitHub Secrets
+
+Go to `https://github.com/USER/REPO/settings/secrets` and press `Add new secret`.
+Use `DOCUMENTER_KEY` for the name, and the Base64 encoded key from the previous section
+as the value.
+
 ---
 
 **Final Remarks**

Update docs for new DocumenterTools.genkeys function. (#1156)