Skip to content

[skill-activity] Trim environment reference side quest to reduce cognitive load #4074

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
github-actions wants to merge 1 commit into from
Closed

[skill-activity] Trim environment reference side quest to reduce cognitive load #4074

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 39 additions & 59 deletions workshop/side-quest-01-02-environment-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,30 @@
<!-- page-adventure: side-quest -->
# Side Quest: Environment Reference

> _Optional: use this quick glossary and visual reference to understand the environments and AI tools used throughout the workshop._
> _Optional: a quick glossary and visual reference for the environments and AI tools used in this workshop._

**What you'll learn:** By the end of this page you can name each tool and environment used in the workshop, match it to its role, and know when you'll use it.
**What you'll learn:** name each tool and environment, match it to its role, and know when you'll use it.

## :clipboard: Before You Start

This is a reference page — you can read it any time. Come back here whenever the workshop uses a term you want to clarify. No terminal required to read this page.

When you're ready to verify your tools are working, see the [Checkpoint](#white_check_mark-checkpoint) section at the bottom.
Read this page any time you want to clarify a term. No terminal required — jump to the [Checkpoint](#white_check_mark-checkpoint) when ready to verify your tools.

## Environment and tool glossary

Knowing which name maps to which role helps you follow workshop instructions without stopping to wonder what "the terminal" or "Codespaces" means in context.

| Term | What it means in this workshop | When you use it | Official documentation |
|------|------|------|------|
| **GitHub Codespaces** | Your cloud development environment when you choose the browser-based setup path. Pre-launched in golden-ticket workshops. | Steps 2–14: writing, compiling, and running workflows | [GitHub Codespaces docs](https://docs.github.com/en/codespaces) |
| **Visual Studio Code (VS Code)** | The editor experience inside Codespaces (and optionally on your local machine). | Editing workflow files and reading output | [Visual Studio Code docs](https://code.visualstudio.com/docs) |
| **Terminal (command line)** | The shell where you run workshop commands (`gh`, `gh aw`, `git`, and more). | Any step that shows a `bash` code block | [GitHub CLI manual](https://cli.github.com/manual/) |
| **GitHub CLI (`gh`)** | GitHub's official CLI, required for this workshop. Pre-installed in the Codespace. | Starting at Step 6 (install the extension) | [GitHub CLI docs](https://cli.github.com/manual/) |
| **`gh-aw` CLI extension** | The GitHub Agentic Workflows extension you install and use in the terminal to compile workflow files. | Step 6 onward | [Install `gh-aw`](https://github.com/github/gh-aw#readme) |
| **GitHub Copilot CLI** | Copilot in the terminal for AI-assisted command and development help. The primary AI surface in this workshop. | Any step that shows a `prompt` code block | [GitHub Copilot CLI docs](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) |
| **GitHub Copilot app** | The GitHub Copilot desktop and web application where you can open repositories, start agent sessions, steer coding tasks, and manage pull requests. | Optional; side quests cover this surface | [GitHub Copilot app](https://github.com/features/ai/github-app) |
| **Claude** | Anthropic's AI model family available in some GitHub Copilot and agentic workflow contexts. | Steps that use a non-default model | [Claude documentation](https://docs.anthropic.com/) |
| **OpenAI Codex** | OpenAI coding model family that can be used in coding and agent workflows. | Steps that use a non-default model | [OpenAI Codex CLI repository](https://github.com/openai/codex#readme) |
| **GitHub Codespaces** | Your cloud dev environment for the browser-based setup path. | Steps 2–14 | [Docs](https://docs.github.com/en/codespaces) |
| **Visual Studio Code (VS Code)** | The editor inside Codespaces (or your local machine). | Editing and reading output | [Docs](https://code.visualstudio.com/docs) |
| **Terminal (command line)** | The shell running `gh`, `gh aw`, `git`, and more. | Any `bash` code block | [GitHub CLI manual](https://cli.github.com/manual/) |
| **GitHub CLI (`gh`)** | GitHub's official CLI, pre-installed in the Codespace. | Starting at Step 6 | [Docs](https://cli.github.com/manual/) |
| **`gh-aw` CLI extension** | The Agentic Workflows extension you use to compile workflow files. | Step 6 onward | [Install `gh-aw`](https://github.com/github/gh-aw#readme) |
| **GitHub Copilot CLI** | Copilot in the terminal; the primary AI surface in this workshop. | Any `prompt` code block | [Docs](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) |
| **GitHub Copilot app** | Desktop/web app for repository sessions and pull requests. | Optional; side quests | [GitHub Copilot app](https://github.com/features/ai/github-app) |
| **Claude** | Anthropic's model family, available in some contexts. | Non-default-model steps | [Docs](https://docs.anthropic.com/) |
| **OpenAI Codex** | OpenAI's coding model family. | Non-default-model steps | [Codex CLI repo](https://github.com/openai/codex#readme) |

> [!NOTE]
> **GitHub Enterprise (GHES/GHEC) users**: the same tools and commands apply in enterprise environments. Your Codespace URL and GitHub URLs will use your enterprise hostname instead of `github.com`. If your enterprise uses a self-hosted runner, the `gh aw compile` command still runs locally in your Codespace — see [Step 6](06-install-gh-aw.md) for any environment-specific install notes.
> **Enterprise (GHES/GHEC):** same tools and commands apply — Codespace and GitHub URLs use your enterprise hostname instead of `github.com`. See [Step 6](06-install-gh-aw.md) for runner-specific install notes.

### :white_check_mark: Verify your tools are ready

Expand All @@ -40,116 +36,100 @@ gh --version
git --version
```

Both commands should print a version number. If either fails, see [Set Up a Codespace](02a-setup-codespace.md).
Both should print a version number. If either fails, see [Set Up a Codespace](02a-setup-codespace.md).

> [!NOTE]
> `gh aw --version` only works after you complete [Install the gh-aw CLI Extension](06-install-gh-aw.md). Skip that check until you reach Step 6.
> `gh aw --version` only works after [Step 6](06-install-gh-aw.md). Skip it until then.

After you complete Step 6, also run:
After Step 6, also run:

```bash
gh aw --version
```

## Conceptual screenshots

Recognizing what each environment looks like on screen helps you orient yourself quickly when workshop instructions say "open a terminal" or "use the Copilot app."

These visuals are simplified mental models, not literal product screenshots. Use them to recognize what each name refers to when it appears in later steps.
Simplified mental models, not literal screenshots — use them to recognize each name later. Captions are short since the table above covers the role.

### Development environments

#### GitHub Codespaces

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-github-codespaces-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-github-codespaces-light.svg">
<img alt="Conceptual screenshot of GitHub Codespaces showing a browser-based editor, repository explorer, and integrated terminal" src="images/side-quest-01-02-github-codespaces-light.svg">
<img alt="Conceptual screenshot of GitHub Codespaces with an editor, file explorer, and terminal" src="images/side-quest-01-02-github-codespaces-light.svg">
</picture>

You use Codespaces when you want a ready-to-go development environment in your browser.

#### Visual Studio Code (VS Code)
**GitHub Codespaces** — your browser-based dev environment.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-vscode-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-vscode-light.svg">
<img alt="Conceptual screenshot of Visual Studio Code showing the Explorer, open editor tabs, and integrated terminal" src="images/side-quest-01-02-vscode-light.svg">
<img alt="Conceptual screenshot of VS Code with the Explorer, editor tabs, and terminal" src="images/side-quest-01-02-vscode-light.svg">
</picture>

You use VS Code to browse files, edit workflows, and keep a terminal open beside your work.

#### Terminal (command line)
**VS Code** — the editor inside Codespaces.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-terminal-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-terminal-light.svg">
<img alt="Conceptual screenshot of a terminal showing a prompt, commands, and command output" src="images/side-quest-01-02-terminal-light.svg">
<img alt="Conceptual screenshot of a terminal with a prompt and command output" src="images/side-quest-01-02-terminal-light.svg">
</picture>

You use the terminal whenever the workshop asks you to run `gh`, `gh aw`, or `git` commands.
**Terminal** — where you run `gh`, `gh aw`, and `git` commands.

### Workshop tools and model options

#### GitHub CLI (`gh`)

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-gh-cli-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-gh-cli-light.svg">
<img alt="Conceptual screenshot of GitHub CLI showing authentication, repository, and workflow commands in a terminal" src="images/side-quest-01-02-gh-cli-light.svg">
<img alt="Conceptual screenshot of GitHub CLI commands in a terminal" src="images/side-quest-01-02-gh-cli-light.svg">
</picture>

You use `gh` for GitHub-specific terminal tasks like authentication checks, repository shortcuts, and workflow commands.

#### `gh-aw` CLI extension
**`gh`** — GitHub's CLI for auth, repo, and workflow commands.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-gh-aw-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-gh-aw-light.svg">
<img alt="Conceptual screenshot of the gh-aw CLI extension showing compile commands for an agentic workflow" src="images/side-quest-01-02-gh-aw-light.svg">
<img alt="Conceptual screenshot of gh-aw compile commands in a terminal" src="images/side-quest-01-02-gh-aw-light.svg">
</picture>

You use `gh aw` to compile agentic workflow files.

#### GitHub Copilot CLI
**`gh aw`** — the extension that compiles agentic workflow files.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-copilot-cli-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-copilot-cli-light.svg">
<img alt="Conceptual screenshot of GitHub Copilot CLI showing a terminal prompt alongside AI-assisted command help" src="images/side-quest-01-02-copilot-cli-light.svg">
<img alt="Conceptual screenshot of GitHub Copilot CLI giving AI help in a terminal" src="images/side-quest-01-02-copilot-cli-light.svg">
</picture>

You use GitHub Copilot CLI when you want AI help inside the terminal.

#### GitHub Copilot app
**GitHub Copilot CLI** — AI help inside the terminal.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-copilot-app-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-copilot-app-light.svg">
<img alt="Conceptual screenshot of the GitHub Copilot app showing a repository session, agent chat, and pull request view" src="images/side-quest-01-02-copilot-app-light.svg">
<img alt="Conceptual screenshot of the GitHub Copilot app with a session, chat, and pull request view" src="images/side-quest-01-02-copilot-app-light.svg">
</picture>

You use the GitHub Copilot app when you want to start and steer repository sessions, manage coding tasks, and review pull requests from a Copilot workspace.

#### Claude
**GitHub Copilot app** — start sessions and review pull requests from a Copilot workspace.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-claude-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-claude-light.svg">
<img alt="Conceptual screenshot of a Claude-style workspace showing a prompt, reasoning path, and structured response" src="images/side-quest-01-02-claude-light.svg">
<img alt="Conceptual screenshot of a Claude-style workspace with a prompt and response" src="images/side-quest-01-02-claude-light.svg">
</picture>

You may see Claude as one of the AI model options that can read a brief, reason through a task, and produce an output.

#### OpenAI Codex
**Claude** — an alternate AI model option for some steps.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/side-quest-01-02-openai-codex-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="images/side-quest-01-02-openai-codex-light.svg">
<img alt="Conceptual screenshot of an OpenAI Codex-style coding workspace showing repository files and a suggested patch" src="images/side-quest-01-02-openai-codex-light.svg">
<img alt="Conceptual screenshot of an OpenAI Codex-style workspace with files and a suggested patch" src="images/side-quest-01-02-openai-codex-light.svg">
</picture>

You may see OpenAI Codex as a coding-focused model option that reads files and suggests edits.
**OpenAI Codex** — another alternate AI model option for some steps.

### Quick self-check

Before moving on, cover the table above and try to answer: which tool do you use to *compile* a workflow file, and which do you use to *run* `git` commands? (Answers: `gh aw`; the terminal.)

<!-- journey: all -->
## :white_check_mark: Checkpoint
Expand Down