New to the lab
The IT Passport is the lab's guided course for setting up tools and practising safe IT tasks used in research. It selects the lessons needed for your work and remembers where you stopped on the computer in front of you. The steps name the application to use and the result to look for.
Already started on another computer? Install only missing tools below, then follow Continue On Another Computer to resume your existing Passport.
Already have Git and gh? Verify the tools and continue.
gh)The required tools are Git and GitHub CLI (gh). Keep working installations. Other software is introduced later, only when one of your lessons needs it.
You may see soheylm-passport-sandbox in links. This is the GitHub group that hosts the course software during the 2026 semester. Continue with your personal GitHub account; do not request membership in that group. Exercise submissions are public and must contain only the requested fictional information.
Before step 1
An application, or app, is a program you open, such as a web browser or PowerShell. A browser is the app used to open websites, such as Firefox, Chrome, Edge, or Safari. A file stores one item; a folder groups files. To download is to copy something from a website to this computer. To install is to add an application so this computer can run it.
A command is a line of text that tells a computer to do one task. You paste commands into a terminal, the text application used for commands. A shell is the part inside that application that reads the command. This guide uses PowerShell on Windows, zsh on macOS, and Bash on Linux. Open PowerShell or Terminal as shown here; that application starts its configured shell. Follow the shell named in the OS section. You do not need to find or install a separate Bash or zsh application.
Windows, macOS, and Linux are operating systems: the basic software that runs your computer. Choose the section matching the computer in front of you. Local means on that computer;remote means on another computer reached through a network.
PS C:\Users\Ada>, %, or $.C:\Users\Ada or /home/ada.PS C:\Users\Ada> git --version git version 2.51.0 PS C:\Users\Ada>
The page will show only the instructions for that operating system. You can change this choice later.
Press the Windows key, type PowerShell, and open the result named PowerShell. Use the window that appears. Windows Terminal is also suitable when its tab says PowerShell. Do not use Command Prompt, Git Bash, or WSL for a block labelled PowerShell. A ready prompt normally begins with PS.
Press Command+Space, type Terminal, and press Return. Terminal normally starts the zsh shell. If it uses another shell, type zsh and press Return for this session; do not search for a separate zsh app. A ready prompt normally ends with %.
Open the application named Terminal from the applications menu. Ubuntu normally starts the Bash shell. If Terminal uses another shell, type bash and press Enter for this session; do not search for a separate Bash app. A ready prompt normally ends with $.
30-second practice
This command only prints the words terminal-ready. It does not install, delete, or configure anything.
In the PowerShell window you just opened:
Write-Output "terminal-ready"In the Terminal window you just opened:
printf 'terminal-ready\n'In the Terminal window you just opened:
printf 'terminal-ready\n'Expected: the next line is terminal-ready, followed by the prompt again. Once you see it, use the same window for step 1.
Step 1
Use the terminal you opened above. Run each check separately:
git --versiongit version 2.51.0.gh --versiongh version.If a command is missing, select your operating system and follow its installation instructions. Then close the terminal, reopen it, and repeat both checks.
winget is Windows' built-in package installer. Use it to install Git, then GitHub CLI. Run one command at a time and accept only the named Git or GitHub package.
winget install --id Git.Git -e --source wingetwinget install --id GitHub.cli -e --source wingetExpected: both commands report a successful installation. Close the PowerShell window, open a new one, and repeat the two checks above.
Git installer whenwinget is unavailableGitHub CLI installer when winget is unavailableRunning git --version may open Apple's Command Line Tools installer. Complete that installer if prompted. Homebrew is an optional macOS package installer; if its brew command already works, install GitHub CLI with:
brew install ghIf Homebrew is absent, open the official releases page, expand Assets, download the file ending in macOS_universal.pkg, and open it with Installer. Do not download Source code. If macOS blocks the official package, stop rather than weakening Gatekeeper. Then open a new Terminal window and repeat both checks.
First identify the distribution. This command changes nothing:
cat /etc/os-releaseRead the line beginning with ID=. It names the Linux distribution. sudo runs the following installation command with administrator rights and may ask for this computer's password without showing characters as you type. If this is an ETH-managed computer and you do not normally use sudo, stop and request the two packages from its IT support.
Use this section only when ID=ubuntu or ID=debian. Run one command block at a time. The second block adds GitHub's official signed software source for gh.
(
set -eu
sudo apt update
sudo apt install --yes git wget
)(
set -eu
sudo mkdir -p -m 755 /etc/apt/keyrings
out=$(mktemp)
cleanup() { rm -f "$out"; }
trap cleanup EXIT HUP INT TERM
wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg
sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg < "$out" > /dev/null
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
sudo mkdir -p -m 755 /etc/apt/sources.list.d
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install --yes gh
)Expected: both installations finish without an APT signature error.
Do not run the Ubuntu/Debian block. Open both official pages below, select the section naming your distribution and package manager, and install git plus gh. Do not substitute a third-party install script.
Close this terminal, open a new one, and repeat both version checks above. The Passport is tested with GitHub's maintained Linux package or release binary, not the confined Snap package.
Write down the exact error without including a password, token, private path, or personal information. Do not change PowerShell policy, antivirus settings, SSH files, or system permissions.
Open troubleshootingStep 2
Run these commands in order. Continue only after you see the expected result.
Your GitHub username and exercise submissions will be public. Never submit passwords, tokens, private keys, ETH usernames, email addresses, student numbers, private paths, logs, screenshots, or research data.
Your computer / PowerShell. If you have no account, first create one free personal GitHub account; use an email you will keep, and add your ETH email later for Education. Run the status command first. If it already names the intended account, skip the login command. Otherwise run the login command, finish the browser approval, then repeat the status command.
gh auth status --active --hostname github.comgh auth login --hostname github.com --web --git-protocol httpsgh auth status --active --hostname github.comExpected: gh auth status says you are logged in and prints the GitHub username you intend to use.
If no account is logged in, repeat the login command and finish the browser sign-in. If the intended account is already stored but inactive, run gh auth switch --hostname github.com --user YOUR-GITHUB-USERNAME, replace the placeholder, and repeat the status check. Do not log out or continue under someone else's account.
Your computer / PowerShell. This installs the tested release v0.12.1. This command is required for the first installation. Later compatible updates appear as an Update and reopen button in your local Passport.
gh extension install soheylm-passport-sandbox/gh-passport --force --pin v0.12.1Expected: GitHub CLI confirms that the extension was installed or upgraded. Updates are never installed silently.
If the error names an older copy of this extension, run gh extension remove soheylm-passport-sandbox/gh-passport once, then repeat this step. For any other error, use troubleshooting.
Your computer / PowerShell. Choose your operating system and the work you expect to do in the browser.
gh passport startExpected: your browser opens an address beginning with http://127.0.0.1:. This address means the page is served only from your own computer. Keep the terminal open because the launcher in that terminal is running the page.
Run gh passport doctor and follow the recovery shown for the failed check. If the error remains, use troubleshooting. Keep the Passport folder.
Confirm the public-record notice, select your responsibilities, and open your first lesson. Keep the terminal running while the local page is open.
Open PowerShell or Terminal and run:
gh passport openThe launcher finds the managed Passport folder and opens the page where you stopped. Do not reinstall or clone again.
Your supervisor registers your GitHub username. If a submitted lesson has no result after 30 minutes, open one help request without including private information.
Optional preview
The preview shows the lessons selected for each type of work. It does not save progress.