From First Commit to Verified

GitHub becomes much easier to understand once you see the whole workflow as a short loop: copy a repository to your computer, change a file, record that change with Git, and send the new commit back to GitHub.

This guide walks through that loop from the beginning. Once it works, we will add GPG signing so GitHub can verify that future commits were made with a key you control.

What You Will Do

By the end, you will have:

1. Created a repository on GitHub.
2. Cloned it to your computer.
3. Made and pushed your first commit.
4. Created a GPG key.
5. Added its public half to GitHub.
6. Configured Git to sign your commits.

The Git portion is the essential workflow. GPG signing is an optional security layer you can add after you are comfortable making ordinary commits.

Before You Begin

You need a GitHub account and Git installed on your computer. On Windows, Git for Windows (opens in a new tab) includes Git Bash, which provides a convenient terminal for the commands below. On macOS or Linux, you can use your usual terminal.

Confirm that Git is available:

git --version

You will also need GPG for the signing section. Check for it with:

gpg --version

If gpg is missing, install GnuPG through your operating system’s package manager or the official GnuPG download page (opens in a new tab).

If you only want to learn the basic GitHub workflow today, you can stop after the first push and return to the signing section later.

Create a Repository

Sign in to GitHub, open your repositories, and choose New repository. Give it a short, descriptive name; lowercase words separated by hyphens are easy to read in URLs.

You can also add a description, a README, a .gitignore, and a license. A README gives us a simple file to edit, so initialize the repository with one for this walkthrough. Choose a .gitignore that matches your language or editor if the project needs one, and only add a license if you know how you want others to use the work.

After creating the repository, open its Code menu and copy the HTTPS URL.

Clone It to Your Computer

In your terminal, move to the directory where you keep projects and clone the repository:

git clone REPOSITORY_URL_HERE
cd REPOSITORY_NAME

Replace the uppercase placeholders with the repository URL you copied and the folder name Git creates. In later examples, placeholders such as FILE_NAME and LONG_KEY_ID should also be replaced with your own values.

Cloning downloads the project files and a hidden .git directory containing the repository history and configuration.

Run this command to confirm that you are inside the repository and that Git can see its state:

git status

Set Your Git Identity

Git records a name and email address in every commit. If this is your first time using Git on this computer, configure both:

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

The name does not have to match your GitHub username. The email should be verified on your GitHub account if you want GitHub to connect the commit to your profile. If you keep your email private, use the noreply address provided in your GitHub email settings.

Make Your First Commit

Open README.md, add a line such as Hello world!, and save the file. Then inspect the change:

git status
git diff

git status shows which files changed. git diff shows the actual edits before you record them.

Next, stage the README and create a commit:

git add README.md
git commit -m "Add hello message to README"

Staging lets you choose exactly what belongs in the next commit. Naming the file explicitly is a useful habit because it avoids accidentally including unrelated changes.

The commit is saved in the repository on your computer; it is not on GitHub yet. You can make commits without an internet connection. Pushing sends your local commits to GitHub.

Now send the commit to GitHub:

git push

GitHub may ask you to authenticate the first time. GitHub does not accept your account password for Git operations over HTTPS. A credential manager may open a browser for you to sign in; if Git asks for a password in the terminal, use a personal access token (opens in a new tab) instead, or configure SSH authentication.

When the push finishes, refresh the repository page. The new commit message and updated README should be visible. You have now completed the basic Git loop: edit, inspect, stage, commit, and push.

What Commit Signing Adds

A normal commit contains an author name and email, but those fields alone do not prove who created it. A signed commit also includes a cryptographic signature made with your private key.

GPG uses a key pair:

• The private key stays on your computer and creates signatures. Protect it and never share it.
• The public key can be shared with GitHub so it can check those signatures.

When the signature is valid and the key identity meets GitHub’s requirements, GitHub marks the commit as verified. Signing establishes that the holder of the private key made the signature; it does not guarantee that the code itself is safe or correct.

GitHub also supports SSH and S/MIME signatures. This guide uses GPG because it is widely supported and gives you a portable signing identity.

Generate a GPG Key

Start the guided key generator:

gpg --full-generate-key

The current GnuPG defaults are generally suitable. Decide whether the key should expire. An expiration date limits the lifetime of an abandoned key, but it also means you must renew or replace it later.

Use the same email address shown by git config --global user.email, make sure it is verified on GitHub, and protect the private key with a strong, memorable passphrase.

List your secret keys in long-ID format:

gpg --list-secret-keys --keyid-format=long

Look for a line similar to this:

sec   rsa4096/LONG_KEY_ID YYYY-MM-DD [SC]

The value after the slash is the key ID used in the next commands. You can also use the full fingerprint shown in the output; it is more precise than a shortened ID.

Add the Public Key to GitHub

Export the public key in ASCII-armored form:

gpg --armor --export LONG_KEY_ID

Copy everything from BEGIN PGP PUBLIC KEY BLOCK through END PGP PUBLIC KEY BLOCK. This is the public half of the key, so it is safe to share. Do not export or paste your private key.

In GitHub, open Settings, go to SSH and GPG keys, choose New GPG key, and paste the complete public-key block. Give the key a label that identifies the computer where you use it. Upload only the public key—never your private key or its passphrase.

Configure Git to Sign Commits

Tell Git which key to use:

git config --global user.signingkey LONG_KEY_ID

You can sign an individual commit with -S:

git commit -S -m "Describe the signed change"

Or sign every commit by default:

git config --global commit.gpgsign true

After making a signed commit, verify it locally:

git log --show-signature -1

Then push it:

git push

Open the commit on GitHub and look for its verification status. If it is not verified, check that the commit email matches an email on the GPG key, that email is verified on GitHub, the correct public key is uploaded, and Git is using the intended signing key.

Keep the Key Safe

Your private key is now part of your development identity. Keep its passphrase private and store a secure backup if losing the key would be disruptive. Create and safely store a revocation certificate so you can invalidate the key if it is lost or compromised.

If you retire a key, remove it from GitHub and revoke it when appropriate. Removing it prevents the key from verifying new activity, but commits GitHub previously verified retain their recorded verification status.

The Workflow from Here

For everyday work, the process remains small:

git pull
git status
git diff
git add FILE_NAME
git diff --staged
git commit -m "Explain the change"
git push

Start with git pull so your local copy includes changes already sent to GitHub, especially when other people contribute or you use more than one computer. Check git status throughout the process whenever you are unsure what Git sees. Before committing, git diff --staged shows exactly what you staged.

If automatic signing is enabled, Git adds the signature during the commit step. That means the security layer becomes part of the same beginner workflow instead of a separate ritual.

What to Learn Next

Once this basic loop feels familiar, these commands are useful next steps:

git log --oneline
git restore --staged FILE_NAME

git log --oneline gives you a compact view of the project history. If you stage the wrong file, git restore --staged FILE_NAME removes it from the next commit without deleting your edits. Keep using git status before and after unfamiliar commands so you can see what changed.

After those basics feel comfortable, learn about branches and pull requests. Branches let you develop a change separately, while a pull request gives you a place on GitHub to review it before merging it into the main project history.

Start with clear commits and a reliable push cycle. Add signing when you are ready to manage the key responsibly. Together, those habits give you a project history that is both useful to read and easier to trust.