How to config SSH settings

Important Notes

  • This post is based on Gogs
  • If you want to disable SSH feature, simply set [server] DISABLE_SSH = true, and skip the rest of post.

There are two cases when setting up SSH for Gogs.

1. Use standalone service like OpenSSH server

Config options:

  • [server] SSH_DOMAIN: defines which domain to be exposed in clone URL, you can leave it blank to use the same value as your web server domain ([server] DOMAIN).
  • [server] SSH_PORT: defines which port the SSH service is listening on, this port number is used to be exposed in clone URL. The default value is 22, and in most of the cases, you don’t need to change it.

Common Mistakes

Gogs needs to generate special commands along with your public keys to the ~/.ssh/authorized_keys file:

command="/path/to/gogs serv key-1 --config='/path/to/custom/conf/app.ini'",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-dss AAAAB3NzaC1kc3M...

This is why you have to add your public key through Gogs web UI, and want to make sure same public key only exists once in the file, which is generated by Gogs.

In case that your SSH service does not use ~/.ssh/authorized_keys file to store public keys, you can config [server] SSH_ROOT_PATH to be the directory which contains authorized_keys file.

:anger: If you messed up the authorized_keys file, don’t panic, go to /admin and execute operation Rewrite '.ssh/authorized_keys' file.

While using standalone SSH service, you’re not able to login remote shell with the same public key anymore, that’s why we recommend you create a separate user specifically for Gogs.

Another way to get around with this to generate a separate public key only for the purpose of Gogs, such as ~/.ssh/ on your local computer. Then config your ~/.ssh/config file in the following way (adjust your settings):

Host gogs
    IdentityFile ~/.ssh/id_rsa_gogs
    IdentitiesOnly Yes

Special Settings

There are some config settings you typically do not need to care about, but just in case you encounter some problem:

  • SSH_KEY_TEST_PATH: the directory where to generate the temporary public key file to verify with ssh-keygen. The default is the system temporary directory.
  • SSH_KEYGEN_PATH: indicate which ssh-keygen problem you want to use. The default is ssh-keygen and lets shell find out which one to use.
  • MINIMUM_KEY_SIZE_CHECK: indicate whether to check the minimum size of public keys. The default value is false.
  • [ssh.minimum_key_sizes] section: this section define what are the minimum sizes of public keys, -1 means a particular key is disabled.

2. Use built-in SSH server

To use built-in SSH server, you need to config [server] START_SSH_SERVER = true. It shares the same config options to compose clone URL.

By default, it listens on the same port as exposed in the clone URL, you can change the listening port through config option [server] SSH_LISTEN_PORT to 2222 or whatever.

Built-in SSH server does not rely on authorized_keys file because it directly searches the database.

To confirm the built-in SSH server actually starts, check your Gogs console logs with the following line:

2016/02/25 00:21:50 [I] SSH server started on :2222


Use SQLite3 as database

If you’re using SQLite3 as your database backend, it is recommended that you put the absolute path for config option [database] PATH.

Verify settings

You can go to admin dashboard (/admin/config) to verify if your settings are taking effect:

:speech_balloon: Please leave comments if you have any questions or concerns about this post.

Add to troubleshooting that a non root user need to use ports from 1025+

EDIT: wrong place: see Clone a repo using ssh

I have a follow-up question here.

I have never used SSH much when using Github so I don’t have a ton of experience with it (I’ve used the HTTPS method mostly), but I think the rough idea with the SSH option is that you generate your Public Key locally and then add that into the website (in this case, our Gogs instance) and then I should be able to connect right?

It took me a while simply to get SSH running, because the ssh-keygen program wasn’t in the PATH (I needed to add an additional folder that was part of Git for Windows added to the PATH in order to allow Gogs to start up properly after enabling the built-in SSH server).

Now that it’s up and running though, I have a few more issues.

First off, in the UI of Gogs for one of my Repos it’s generating the following URL:

[email protected]:omar.ramos/joomla-blackboard-php-sync.git

If I try and run a git clone using the URL above it provides me the following error:

ssh: Could not resolve hostname Name or service not known
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

If I correct the URL slightly (by removing the dollar symbol at the end of the computer name at the front before the at sign) one of the errors goes away but it still can’t do much:

fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Keep in mind this is after I’ve added my Public Key into my account for our Gogs instance so I’m assuming if the URL is correct it should work at this point, but I’m not sure how to troubleshoot it further. And I don’t have a way of fixing the computer name that gets prepended to the front of the URL to remove that dollar sign since there doesn’t seem to be a configuration option to customize how that works right now.

Also, if I run the SSH test command from Git Bash on my Windows machine with the hostname it just seems to hang there and not do anything until I cancel out of that command (though this might be expected behavior since we’re using the built-in SSH server in Gogs):

$ ssh -T

Any help would be appreciated.

Thank you!

Hi @orware,

  1. If the URL Gogs gives for SSH feels wrong, because you set the wrong DOMAIN value.

though this might be expected behavior since we’re using the built-in SSH server in Gogs

Did you set to use builtin SSH server?

Hi @Unknwon,

Yes I did use the built-in SSH server.

The domain should be correct (it’s not the actual server name, which would be, but since that DNS hostname is not accessible from the outside and isn’t the one I want to use, I’ve set it to which will be friendlier name everyone will use to refer to the server).

I feel like part of the issue has to do with the IT903S-CODE$ portion that is being added at the front of the SSH URL though (which is the computer/system account used in Windows for this server), since by default it appears that the $ is causing an issue right off the bat with the URL when used at the command line in Git Bash since it’s re-interpreting the URL incorrectly and causing that initial error “Could not resolve hostname” I had received.

One thing I was thinking I could attempt would be trying to switch everything to use a specific user account (rather than the computer’s system account), but I haven’t tried that yet, and am not sure if that would fix the issue right away, or if there is still something else that would need to be fixed after that’s worked around.

Thank you for the response!

This is the user name which must be included for an SSH URL, maybe the $ sign is the problem?

Hi @Unknwon,

That’s what I’ve been trying to explain. I know under Windows the Computer System Account has the $ symbol at the end of it and that seems to be causing an issue.

However, I don’t know enough regarding the mechanism by which the SSH functionality is supposed to work to know what my next steps would be to troubleshoot things (or make adjustments) to try and get things working.

Does the SSH URL have to be tied to that exact same system account user? Or is there a way that a different user can be specified specifically for the SSH functionality?

Any additional insight you might be able to provide on how Git and SSH works (end-to-end) might give me some clues (unless this is a bug that needs to be fixed in Gogs itself) :-).

Which user name to use is basically based on the SSH server you’re using. In the case of builtin SSH server, as long as you can reach the server (ex, connect to port 2222), user name does not matter I think.

Hi @Unknwon,

A quick update with my additional tests.

It definitely appears to be an issue with the username and the built-in SSH server.

Here is the test that I ran:

  • Changed RUN_USER from IT903S-CODE$ to git (after I had created a local administrator account on this Windows Server named “git”).
  • Logged into the git account on the server.
  • Started Gogs manually from a CMD prompt to test
  • It started up fine, and SSH URL was changed on the page to: [email protected]:imperialvalleycollege/sql-library.git
  • Opened up Git Bash from my desktop and tried doing a git clone using the SSH URL.
  • It worked!
  • Updated Service (I’m using the version of Gogs with the built-in Windows Service functionality) to use the local account, which in the service manager shows up at the end of the process as “.\git”
  • Started up the service.
  • Service starts just fine and Gogs web interface is accessible
  • I then try cloning the repository again and now it doesn’t anymore and is giving me the same error I was running into before:
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

I then repeated this by using a domain account but it results in a similar issue (since the service runs under the account with the full email address shown, whereas the app.ini file only needs the username portion).

So it seems like this mismatch issue with the username results in the SSH issue I’m experiencing.

The next thing I’m going to go ahead and try is use NSSM for Gogs (so I have to go and download the other binary for Windows to do that) and see if that results in better luck for me. Hopefully NSSM can more closely simulate how it works/runs when I start things manually from the command line with the new local git user account I created a few minutes ago (which was the scenario that seemed to work correctly).

OK, just went through the process of switching out the Gogs binary for the non-Windows service version and then used NSSM to setup a new service for the binary.

This one seems to be working correctly :-)!

During the configuration of NSSM, I didn’t do anything special…just provided the path and arguments like normal and specified the username/password normally (e.g. “git” for the username, and then the password I had specified when creating the account).

In the Windows Service manager, it doesn’t really appear to be any different (it still shows the .\git username as it did before), but something must be different in how NSSM starts it up because it’s no longer complaining when I try and do a clone with the SSH URL.

And that is awesome / what I wanted :-).

Now SSH seems to be working as expected for me.

Hopefully these tips help someone else trying to get SSH going on Windows using the built-in SSH server!

1 Like

ssh-keygen must be in PATH for built-in server. Or SSH_KEYGEN_PATH should be used.

My gogs is in

I’m using openssh server using a non 22 port.
My ssh domain that I use for my server management is so I have set SSH_DOMAIN = and SSH_PORT to my openssh port.

I have checked and my key is in .authorized_keys in /var/lib/gogs/.ssh/ as I have defined.

When I try to push a branch I get this error:

nologin: invalid option -- 'c'
Try 'nologin --help' for more information.
fatal: Não foi possível ler do repositório remoto.
(was not possible to read remote repository)

Certifica-se que tem os direitos de acesso corretos
e que o repositório existe.
(check if you have the correct permission and that the repo exists)

To install Gogs I have followed the archlinux gogs wiki page except the part of “SSH Port” (since I believe it is for users that want to use to built-in server)

Just needed to do:
sudo usermod -s /bin/bash gogs

1 Like