02a-setup-codespace.md

Set Up a Codespace

🎯 What You'll Do

You'll launch a GitHub Codespace for this workshop, open the built-in terminal, and land in a ready-to-use environment for the next step.

Steps

Verify you are on the right path before continuing:

• You have a GitHub account with access to GitHub Codespaces
• You want a browser-based terminal and do not need to install tools locally

Important

On a phone? Creating a repository works in any browser, but the Codespace terminal requires a tablet or laptop. If you are on a phone, create your repository in the step below and then either switch devices or skip ahead to Write Your First Workflow — GitHub Copilot Path, which does not need a terminal. On a tablet or shared computer, the Codespace path is the easiest option — it runs entirely in your browser.

These steps take about 5 minutes. If you get stuck on any command, Side Quest: Terminal Basics is a 2-minute read.

New repository

1. Create your own public repository at github.com/new:
   • Choose yourself as owner.
   • Visibility Private, it's good to learn on our own. We can make it public later if we want to share our work.
   • Name it my-agentic-workflows.
   • Check Add a README file.
   • Click Create repository.

Open the Codespace

1. In your new repository, click the green Code button.
2. Click the Codespaces tab.
   • Leave main selected as the branch.
   • Click Create codespace on main.
   • Wait 30–60 seconds for GitHub to prepare the container.
3. The Codespace opens in a new browser tab showing a VS Code-style editor. Leave this tab open for the rest of the workshop.

Codespaces auto-save your work. If you close the tab, open github.com/codespaces to resume where you left off.

Codespace not appearing or taking too long?

• "Create codespace on main" is greyed out — your account may not have Codespaces enabled. Check your GitHub plan details or ask your organization admin.
• Spinner runs more than 3 minutes — refresh the browser tab. If still stuck, go to github.com/codespaces, find the pending Codespace, click ⋯ → Delete, and try again.
• "Codespace storage limit reached" — you may have existing Codespaces using your quota. Visit github.com/codespaces, delete any you no longer need, and retry.
• VS Code desktop opens instead of the browser — click Open in Browser in the dialog, or close VS Code desktop and return to the browser tab.

Open the Codespace terminal

1. When the Codespace editor loads, open the built-in terminal with Ctrl+` (or Cmd+Option+` on Mac).
2. Wait for the terminal prompt to appear.
3. Keep this terminal open. It is already inside your practice repository.

Tip

If the terminal in your Codespace shows a $ prompt, the container is ready. If you see a permission error when running gh auth status, try gh auth login to authenticate.

First time in a terminal?

Type your command after the $ prompt and press Enter. Output appears below; a new $ prompt means the command finished. See Side Quest: Terminal Basics for more.

Verify your Codespace is ready

The diagram below shows your Codespace connection to GitHub.

1. Run these commands in the Codespace terminal:

   gh --version
   gh auth status

2. Confirm gh --version shows gh version 2.40.0 or newer.

3. Confirm gh auth status shows you are logged in to github.com.

What success looks like:

gh version 2.40.0 (2024-01-01)
...
github.com
  ✓ Logged in to github.com as <your-username>

✅ Checkpoint

• You confirmed your GitHub plan includes Codespaces access (free tier includes 60 hours/month)
• The Codespace editor is open in your browser
• The built-in terminal is open in your Codespace
• gh --version returns version 2.40.0 or newer
• gh auth status confirms you are logged in to github.com
• The Codespace is attached to your my-agentic-workflows practice repository

Next: GitHub Actions Intro