Wen Ping

Posted on Oct 31 Edited on Oct 31 Originally published at anguskit.com

How to push code after you install your own Git server: set up SSH or HTTPS and finish the first push

#git #angusgit #ssh

This article explains how to push an existing local project to AngusGit for the first time after it is installed. After reading it, you can create an empty repository, finish git push with an SSH public key (port 2222) or an HTTPS access token, and see that commit on the code page in the browser.

An access token is a secret you create for Git over HTTPS. You type it where Git asks for a password. It can be limited to a few repositories and to read or write. It is not your console login password.

The steps below assume AngusGit is already installed and you can open its console in a browser. The check uses a real project on the AngusGit online instance: under the anguskit team on git.anguskit.com, create a repository named AngusKit, then push the local project. When you follow along, replace the domain and the owner with your own.

1. Pick one way to sign in

Both ways can push. They differ in where the credential is stored, and in whether your network can reach port 2222.

Way	When to use it, and what to prepare	What the address looks like
SSH	Your own computer, for ongoing use. Prepare an SSH key pair and register the public key in AngusGit	`ssh://git@git.anguskit.com:2222/anguskit/AngusKit.git`
HTTPS	A temporary machine, a company network that allows only ports 80 and 443, or a script. Prepare a `git:write` access token and use it as the password	`https://git.anguskit.com/anguskit/AngusKit.git`

The online instance has a certificate, so the HTTPS address starts with https://. If you installed with the first-run path and have not configured a certificate yet, the address from the HTTPS button on the page actually starts with http://. Copy the address from the page. Do not change http to https by hand, or you will connect to port 443, where nothing is listening.

When you are unsure, pick SSH. After you register the public key once, every repository on this computer can use it. You do not have to remember a password, and you do not have to rotate a token.

2. Create an empty repository

Open the form Click Repositories in the sidebar, then New repository at the top right. The title is Create a new repository.
Fill in the owner and the name Set Owner to your own account, or to a team you belong to. The example picks the team anguskit. That becomes the first part of the address. Repository name can use letters, numbers, hyphens, underscores, and dots. The example uses AngusKit. Together they are anguskit/AngusKit. When Visibility is Private, you choose who can see and commit to this repository.
Do not add the initial files When you are pushing a project that already exists locally, leave Add a README file, Add .gitignore, and Choose a license unselected. If you select any of them, the remote gets a commit first, and your first push is refused because the two histories do not match.
Create Click Create repository. The page opens on this repository. The subtitle is "This is an empty repository, ready to start your project!"

The empty repository page has Clone URL, and you can switch between HTTPS and SSH. Below that are three command blocks you can copy as a whole: Global Setup, Create a new repository on the command line, and Push an existing repository from the command line. Later steps use this page. Leave it open.

If this computer has never used Git, run the two Global Setup lines first and set your name and email. They decide who appears on the commit. They are not part of signing in:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

3. SSH: generate a key and register the public key

If you are using HTTPS, skip to section 4.

Generate a key on your own computer If you already have ~/.ssh/id_ed25519.pub, you can use it and skip this step. If you do not, run ssh-keygen -t ed25519 -C "you@example.com" and press Enter at the save path to keep the default.
Copy the public key The public key is the file that ends in .pub. Run cat ~/.ssh/id_ed25519.pub and copy the whole output line. It starts with ssh-ed25519 and ends with the email. The file without .pub is the private key. Leave it on this computer.
Register it in AngusGit On the empty repository page, click Configure next to SSH. Or, in the sidebar, open Settings → Profile (the page title is My Profile) and the SSH Keys tab. Click Add SSH Key. For Title, write a name you will recognize, for example "Work laptop". Paste the whole line into Key. Click Add Key.

Generate the key and show the public key with:

ssh-keygen -t ed25519 -C "you@example.com"
cat ~/.ssh/id_ed25519.pub

AngusGit SSH listens on port 2222 by default, not the usual SSH port 22. The SSH address on the page already includes the port, for example ssh://git@git.anguskit.com:2222/anguskit/AngusKit.git. The user name is always git, not your login name. AngusGit recognizes you from the public key.

Before you push, you can confirm that the public key is recognized:

git ls-remote ssh://git@git.anguskit.com:2222/anguskit/AngusKit.git

The first time you connect to this host, the terminal asks whether you trust its fingerprint. Type yes. If the command then ends with no error, authentication has passed. A repository you just created is empty and has no branch yet, so this command prints nothing. Run the same command against a repository that already has code, and that you are allowed to read, and it prints branches and commit ids. For example, anguskit/AngusGit:

git ls-remote ssh://git@git.anguskit.com:2222/anguskit/AngusGit.git

e21adb350173f2722a546939cdf4ee44004bc8d3    HEAD
e21adb350173f2722a546939cdf4ee44004bc8d3    refs/heads/main

The commit id changes as the repository is updated. Seeing refs/heads/main means the connection works. If you see Permission denied (publickey), use section 6.

4. HTTPS: create an access token

If you are using SSH, skip to section 5.

For an HTTPS push, the user name is your login name, and the password is an access token. The empty repository page says: "Account password also works for HTTPS; PAT is recommended for revocation and scoped access." PAT means the personal access token on this page. If a login password is stored in a credential cache or a script and then leaks, someone can sign in to the whole console. A token can be limited to a few repositories and to read or write, and you can revoke that one token if it leaks.

Open the token page On the empty repository page, click Configure next to HTTPS. Or, in the sidebar, open Settings → Profile (the page title is My Profile) and the Access Tokens tab. Click Generate New Token.
Fill in the name and the lifetime Fill in the token name, for example "Laptop push". Expiration can be 30 days, 60 days, 90 days, or 365 days. After it expires, this token stops working and you need to generate another one. Then enter your current login password, to confirm that you are the one doing this.
Choose the permission Under Scopes, select git:write. The description is "Allow push (git-receive-pack); implies git:read". git:read can only clone and fetch. A push with it is refused. Its description is "Allow clone / fetch (git-upload-pack)". Repository access can be All accessible repositories, or Selected repositories with WRITE only on anguskit/AngusKit. Click Generate Token.
Copy it immediately The token text is shown in full only this once. The page says "Please copy this token now. For security reasons, it will not be shown again." Copy it, store it in your password manager, and click I have saved this token. After that the list shows the name and not the token text.

So you do not have to paste the token on every push, you can let Git remember it. macOS has Keychain. The Git installer on Windows includes a credential manager. After the first entry, it is saved automatically. On Linux you can run:

git config --global credential.helper store

store writes the token in plain text into ~/.git-credentials. Use that only on a computer that is yours alone. When you later replace the token, delete the old line, or Git keeps trying the old token.

5. Push the local project

In the root of the local project, run these three lines. They match Push an existing repository from the command line on the empty repository page. Replace the address on the first line with the one you copied from the page.

git remote add origin ssh://git@git.anguskit.com:2222/anguskit/AngusKit.git
git branch -M main
git push -u origin main

For HTTPS, the first line uses https://git.anguskit.com/anguskit/AngusKit.git. When you run the third line, the terminal asks Username first. Enter your own login name (not the team name anguskit). It then asks Password. Paste the access token. Nothing appears on the screen while you paste. That is normal. Press Enter after you paste.

The second line renames the current branch to main. If the project's old main branch is called master, this line renames it to main, which matches the default branch on the page.

If the project already has a remote named origin (for example it was cloned from somewhere else), the first line reports error: remote origin already exists. Replace the first line with:

git remote set-url origin ssh://git@git.anguskit.com:2222/anguskit/AngusKit.git

When the push succeeds, the last lines include * [new branch] main -> main and branch 'main' set up to track 'origin/main'. Go back to the browser and refresh the repository page. The empty-repository notice is gone, and you can see the project files and the commit you just made. The first push is done.

When a colleague needs this code later, they click the green Code button on the code page, copy the address in the Clone panel, and run git clone. They also need to register their own public key, or generate their own token.

6. When the push does not go through

Find the sentence in the terminal that matches the first column, then follow that row.

What you see	Why	What to do
`Permission denied (publickey)`	AngusGit did not recognize your public key. The usual cases are that the public key was not registered, the paste was cut short, or this computer is using a different private key	Under Settings → Profile, on the SSH Keys tab, confirm that this key is in the list and that you pasted the whole line. If this computer has several keys, see the `~/.ssh/config` example later in this section
`Connection refused`, or it hangs and then `Connection timed out`	The client is connecting to port 22, or the server firewall does not allow 2222	Use the `ssh://` address from the page, the one with `:2222`. If it still cannot connect, ask an administrator to confirm that 2222 is allowed
`Authentication failed for 'https://git.anguskit.com/anguskit/AngusKit.git/'`	The token has expired or been revoked; the user name is not the login name of the token's owner; or the system still has an old token cached	Under Settings → Profile, on the Access Tokens tab, see whether the token is still inside its lifetime, and generate a new one if you need to. The user name is your own login name. If an old token was cached, delete that entry in Keychain or the credential manager, then push again
An HTTPS push is refused, and clone works	The token's scope is `git:read`, or Selected repositories did not grant this repository WRITE	Generate a `git:write` token, and confirm that it covers this repository
`! [rejected] main -> main (fetch first)`	The remote already has commits your local copy does not have. The usual cause is that README was selected when the repository was created	Run `git pull --rebase origin main` to place that remote commit before your local commits, then push. If you do not need that remote README, you can delete this repository and create an empty one again, as in section 2
`Branch 'main' is protected: direct push is not allowed, please open a pull request`	`main` on this repository already has branch protection and does not accept a direct push	Push to a new branch, then open a pull request on the website. See the branch protection article linked at the end

If this computer has several SSH keys, or you do not want to write the port in the address every time, add this block to ~/.ssh/config. After that, ssh and git connections to git.anguskit.com use port 2222 and the private key you name:

Host git.anguskit.com
  Port 2222
  User git
  IdentityFile ~/.ssh/id_ed25519

Frequently asked questions

Can SSH and HTTPS be used at the same time?

Yes. The same account can have a registered public key and hold a token. Which way one repository uses locally depends on whether the address in git remote -v starts with ssh:// or http.

Why use a token instead of the login password?

A login password written into a script or a credential cache lets someone sign in to the whole console if it leaks. A token can be limited to a few repositories and to read or write, it expires on its own, and you can revoke that one token if it leaks, without affecting your login. Changing the login password does not stop a Git push that is already configured.

The token expired. Do I have to change the login password?

No. Generate another one under Settings → Profile, on the Access Tokens tab, and replace the old token in the credential cache.

What if I change computers?

Generate a new key pair on the new computer, and register the new public key. One key per computer. If one computer is lost later, delete only that key.

A CI machine needs to pull the code. Does it have to use my personal public key?

No. Settings → Deploy Keys on the repository can register a read-only or read/write public key for the machine. The labels are Read-only and Read/Write. It applies only to this one repository, and it is not tied to anyone's personal account.

Summary

A first push needs three things done correctly. When you create the repository, do not select the initial files. SSH uses port 2222 and the user name git. For HTTPS, the password is an access token. Copy the remote address from the page. After the push, the usual next step is to protect main, so later changes go through a pull request and a review before they merge.

Conclusion: To push an existing local project, create the repository without selecting README. Use SSH (register the public key under Settings → Profile, on the SSH Keys tab; the address includes :2222) or HTTPS (the password is a git:write token from the Access Tokens tab on the same page) and run git push -u origin main.

DEV Community