Setting Up a Git and GitHub Workflow on elementary OS

A reliable Git and GitHub setup turns elementary OS into a comfortable development workstation, whether you are maintaining a small website, contributing to open-source software, or building a project for a Sydney startup. The graphical desktop keeps everyday work uncluttered, while the terminal provides the precise tools developers need for version control, automation and collaboration.

This workflow covers Git installation, identity settings, SSH authentication, GitHub’s command-line tools and a practical branch routine. It also explains how to protect your code, avoid common permission problems and make the setup fit Australian working habits, including distributed teams spread across Melbourne, Brisbane and Perth.

Install Git and the supporting tools

Open Terminal from Applications and refresh the package information before installing Git:

sudo apt update
sudo apt install git curl openssh-client

The git package provides version control, while curl is useful for installing GitHub CLI and working with web APIs. The OpenSSH client allows your computer to authenticate with GitHub without repeatedly entering a password. On elementary OS, system packages are generally managed through apt, so this approach is preferable to downloading an unrelated installer from a random website.

Check that Git is available:

git --version
ssh -V

The exact version will vary with the elementary OS release and its Ubuntu base. That is normal. GitHub supports a broad range of current Git versions, and a recent distribution package is usually sufficient for everyday commits, branches and pull requests.

You may also want a few useful command-line utilities:

sudo apt install build-essential unzip tree

build-essential supplies compilers and common development tools, unzip handles downloaded archives, and tree gives you a quick view of a project’s directory structure. Install only what you need; a lean system is easier to maintain, particularly on an older laptop used for coding at a coworking space in Melbourne or a home office in Adelaide.

Set your Git identity and defaults

Git records an author name and email address in every commit. Configure them globally so new repositories use the same identity:

git config --global user.name "Alex Taylor"
git config --global user.email "alex.taylor@example.com"

Use the email address associated with your GitHub account, or a GitHub-provided private noreply address if you prefer not to expose your personal address in public commits. You can review the settings with:

git config --global --list

Set a sensible default branch name and choose a friendly display style:

git config --global init.defaultBranch main
git config --global core.editor "nano"
git config --global color.ui auto

If you use a graphical editor, replace nano with its command. For example, developers using Visual Studio Code can set code --wait, provided the code command is available in the terminal. Elementary OS users who prefer a lightweight setup can keep Nano for simple commit messages and use their regular editor for source files.

A global Git ignore file prevents operating-system clutter from entering repositories. Create it with:

mkdir -p ~/.config/git
nano ~/.config/git/ignore

Add entries such as:

.DS_Store
Thumbs.db
*.swp
.env

Register the file:

git config --global core.excludesfile ~/.config/git/ignore

The .env entry is especially important because environment files often contain API keys, database passwords or payment credentials. Ignoring a file does not remove it if it has already been committed, so check git status before every first commit.

Create an SSH key for GitHub

SSH is a convenient and secure way to connect to GitHub. Generate an Ed25519 key with a descriptive comment:

ssh-keygen -t ed25519 -C "alex.taylor@example.com"

Press Enter to accept the suggested location, then create a passphrase. A passphrase protects the private key if your laptop is lost on a train from Parramatta to Central. Never upload the private key, usually stored as ~/.ssh/id_ed25519, to GitHub or include it in a project archive.

Start the SSH agent and add the key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Display the public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire single line, including the ssh-ed25519 prefix and the email comment. In GitHub, open your profile settings, choose SSH and GPG keys, select New SSH key, give it a name such as “elementary laptop”, and paste the key into the form.

Test the connection:

ssh -T git@github.com

The first connection may ask you to verify GitHub’s host fingerprint. After accepting it, a successful response confirms that authentication works. GitHub does not provide shell access, so a message saying authentication succeeded but shell access is unavailable is expected.

If you use several machines, create a separate key for each one. A desktop in Canberra, a work laptop in Perth and a home computer should not share one private key. Individual keys make it possible to revoke access to one device without disrupting the others.

Add GitHub CLI to the desktop workflow

GitHub CLI, usually called gh, brings pull requests, issues, releases and repository management into Terminal. First check whether the package is already available:

sudo apt update
sudo apt install gh

If your elementary OS release does not provide it, use the official GitHub CLI installation instructions for your Ubuntu base rather than mixing packages from unrelated repositories. After installation, confirm it:

gh --version

Authenticate with GitHub:

gh auth login

Choose GitHub.com, SSH for Git operations, and the browser-based login method when prompted. The browser route is straightforward on elementary OS: gh supplies a short code, opens or directs you to GitHub, and connects the account after approval.

Useful commands include:

gh repo clone username/project
gh repo create
gh repo view --web
gh pr create
gh issue list

For example, gh repo clone downloads a repository using its SSH address and configures the remote automatically. gh repo view --web opens the project in your browser, which is useful when you want to inspect Actions results, documentation or code review discussions without remembering a long URL.

Keep authentication tokens and SSH keys private. Do not paste them into a public issue, a support forum post or a build log. If you are working for an Australian agency or consultancy, confirm whether the organisation requires single sign-on, two-factor authentication or approved GitHub organisations before creating private repositories.

Start a repository with a repeatable routine

For a new local project, create a directory and initialise Git:

mkdir weather-dashboard
cd weather-dashboard
git init
printf "# Weather Dashboard\n" > README.md
git add README.md
git commit -m "Initialise project"

Create a matching GitHub repository with the CLI:

gh repo create weather-dashboard --private --source=. --remote=origin --push

Use --public only when the code, commit history and documentation are ready for everyone to see. A private repository is safer for prototypes, client work and experiments involving commercial ideas. GitHub’s free plans may cover many private projects, but organisation features and Actions usage can vary, so check current pricing before committing a business workflow.

For an existing GitHub repository, clone it rather than running git init inside an empty folder:

gh repo clone username/weather-dashboard
cd weather-dashboard

A simple daily cycle keeps changes understandable:

git status
git pull --ff-only
git switch -c feature/add-rainfall-chart

Make a focused change, inspect it, and commit:

git diff
git add path/to/changed-file
git commit -m "Add rainfall chart"
git push --set-upstream origin feature/add-rainfall-chart

The --ff-only option prevents Git from creating an unexpected merge commit during a pull. If it reports that local and remote histories have diverged, stop and inspect the situation rather than guessing. A short, specific commit message is easier for teammates to review across Australian time zones, especially when a colleague in Perth starts work several hours after someone in Sydney.

Work with branches, pull requests and reviews

Keep main in a usable state and develop features on separate branches. Names such as feature/login-form, fix/sidebar-spacing and docs/install-guide make the purpose visible in GitHub’s branch list. Avoid giant branches that combine a user-interface redesign, dependency upgrades and unrelated spelling fixes.

When the branch is ready, open a pull request:

gh pr create --base main --head feature/add-rainfall-chart \
  --title "Add rainfall chart" \
  --body "Displays daily rainfall data and includes a loading state."

A pull request should explain what changed, how it was tested and whether anything needs special review. Include screenshots for visual changes. This is helpful for a distributed team, and it gives a reviewer in Brisbane enough context to assess the work without arranging a meeting during another state’s lunch break.

Review your own diff before requesting approval:

git diff main...HEAD
git status

After a pull request is merged, remove the local branch:

git switch main
git pull --ff-only
git branch -d feature/add-rainfall-chart
git fetch --prune

Use GitHub Issues for bugs and planned work rather than hiding tasks in commit messages. Labels such as bug, documentation and good first issue help a community project stay approachable. If your repository is public, write issue templates and contribution guidelines so new contributors understand supported versions, coding standards and the expected test process.

Protect secrets and keep the workspace healthy

A Git repository is a history, not just a current folder. Deleting a password from a file does not remove it from earlier commits. Use environment variables for local secrets and provide a safe example file:

cp .env.example .env
chmod 600 .env

Keep .env ignored and document required variable names in .env.example without real values. If a secret has been committed, revoke or rotate it immediately, then use an appropriate history-cleaning tool if the repository must be sanitised. Treat an exposed cloud key as compromised even if the commit was quickly deleted.

Check the repository before pushing:

git status
git diff --cached
git log --oneline --decorate -5

A pre-commit tool can run formatters, linters and secret checks automatically, but start with commands you understand. Git hooks are local by default and are not transferred when someone clones a repository, so place important checks in GitHub Actions as well.

Back up important projects separately from GitHub. Remote hosting is valuable, but it is not a complete backup strategy for every account, branch or asset. Keep a second copy on an encrypted external drive or a trusted backup service, particularly if your NBN connection is unreliable or you regularly work while travelling through regional New South Wales.

For larger repositories, avoid committing generated files, build directories and dependency caches. A clean .gitignore makes reviews faster and keeps clones small. Run git status --ignored occasionally to see whether an ignore rule is hiding something unexpectedly.

Troubleshoot common elementary OS problems

If sudo apt update fails, inspect the repository error before attempting random fixes. A third-party source may no longer support the Ubuntu base used by your elementary OS version. Disable an obsolete source, update the system, and use official or well-maintained package channels wherever possible.

A “Permission denied (publickey)” error usually means GitHub cannot find the correct public key or your SSH agent has not loaded the private key. Check the remote:

git remote -v

It should use an SSH address such as git@github.com:username/project.git. Test the key again with ssh -T git@github.com, then run ssh-add -l to see whether the agent has a loaded identity. If the repository belongs to an organisation, confirm that your GitHub account has access and that any single sign-on authorisation has been completed.

If Git asks for a username and password over HTTPS, either switch the remote to SSH or authenticate with GitHub CLI and an approved credential manager. GitHub no longer accepts an account password for ordinary Git operations over HTTPS. Switch an existing remote like this:

git remote set-url origin git@github.com:username/project.git

A merge conflict is a request for a decision, not a failed repository. Open each conflicted file, choose the intended content, remove the conflict markers, then run:

git add path/to/resolved-file
git commit

If the conflict becomes confusing, save any useful work and ask a teammate or use a discussion thread in the elementary OS community forums. A clear error message and the output of git status are far more useful than a screenshot of an entire terminal window.

With Git, SSH authentication and GitHub CLI configured, create a small private test repository, make one branch, push one commit and open one pull request today.