How to Link a Spring Boot Project to a GitHub Repository

You can link an existing Spring Boot project to GitHub by checking what will be committed, initializing Git, creating an empty GitHub repository, adding it as origin, and pushing your local branch. The important safety step comes first: exclude credentials, local configuration and generated build output before you run git add.

Before you publish anything

Open a terminal in the project root—the directory containing pom.xml or build.gradle—and inspect the files:

pwd
git status

If git status says this is not a Git repository, that is expected for a new local project. Before initializing it, create or review .gitignore. A typical Spring Boot project should not commit Maven’s target/, Gradle’s build/, IDE metadata, logs or machine-local environment files:

target/
build/
.gradle/
.idea/
*.iml
.vscode/
*.log
.env
application-local.properties
application-local.yml

This is only a starting point. Keep shared configuration—such as safe defaults in application.properties—but inject passwords, tokens and private keys through environment variables or an approved secret store. GitHub’s security guidance says not to push unencrypted credentials even to a private repository. If a secret has already been committed, revoke or rotate it first; adding the filename to .gitignore does not remove it from Git history. See GitHub’s guides to keeping credentials secure and removing sensitive data.

Review the exact files Git will include:

git init
git status --short
git add .
git diff --cached --stat
git diff --cached

Do not commit until that diff contains only files you intend to publish.

Create the first local commit

Configure your author identity if Git asks for it, then commit:

git commit -m "Initial Spring Boot project"
git branch -M main

Run the project’s tests before the first push so the repository begins from a reproducible state:

# Maven wrapper
./mvnw test

# Or Gradle wrapper
./gradlew test

Commit the Maven or Gradle wrapper files if the project generated them. They make the expected build tool available without requiring every contributor to install the same version manually.

Create an empty GitHub repository

On GitHub, choose New repository, select the owner, name and visibility, then create it. Because the local project already has a commit, leave the README, .gitignore and license initialization options unselected. GitHub explicitly warns that pre-populating those files while importing existing code can introduce a merge conflict. The current steps are documented in Creating a new repository.

Public means anyone can read the code. Choose private if the source, assignment rules, client material or licenses do not permit publication. Repository visibility is not a substitute for secret handling.

Add and verify the remote

Copy the repository’s HTTPS or SSH URL. Then add it as the conventional origin remote:

git remote add origin https://github.com/YOUR-USER/YOUR-REPOSITORY.git
git remote -v

Check both fetch and push URLs in the output before sending code. If origin already exists, inspect it rather than blindly replacing it:

git remote get-url origin

Only if it points to the wrong repository should you update it:

git remote set-url origin https://github.com/YOUR-USER/YOUR-REPOSITORY.git

Authenticate and push

GitHub no longer accepts an account password for Git operations over HTTPS. Use GitHub CLI, a credential manager, a personal access token with only the permissions and repositories it needs, or SSH. GitHub documents the options in About authentication to GitHub and explains HTTPS token authentication.

Never put a token into the remote URL or paste it into a command that will remain in shell history. Once authentication is configured, push:

git push -u origin main

The -u option records origin/main as the upstream, so later git push and git pull commands know which remote branch to use.

Refresh the GitHub repository and verify the expected files are present—and .env, credentials and build directories are absent.

Common errors

remote origin already exists

Run git remote -v. Keep the existing remote if it is correct; otherwise use git remote set-url origin ....

Push rejected because the remote has work you do not have

This often happens when the GitHub repository was initialized with a README or license. Do not force-push over unknown work. Fetch and inspect it:

git fetch origin
git log --oneline --graph --all --decorate

If both histories are intentional, integrate them carefully. For a beginner exercise, it is usually clearer to create a new empty remote than to guess which history should win.

Authentication failed

An account password will not work for HTTPS Git operations. Confirm the remote type, then configure GitHub CLI, a credential manager, a suitably scoped token or an SSH key. Do not share or commit the credential while troubleshooting.

Move from storage to collaboration

After the first push, avoid doing every change directly on main. Learn the relationship among repositories, branches and pull requests, then practise the full GitHub repository and pull-request workflow. When a repository becomes shared or important, add branch protection or a ruleset.

These delivery habits also support the project-facing work covered in the Forward-Deployed Engineer program.