GitHub Desktop Setup Guide

Why This Matters

When Claude Code or GitHub Copilot generates a Dataverse schema, a flow, or a Canvas app, the output is code — pa.yaml, JSON, Liquid, YAML. Code belongs in version control, for three reasons that matter especially for AI-generated work:

• Diffable — you can see exactly what the AI changed between versions.
• Attributable — who changed what, when, and why.
• Reversible — roll back to any previous version if a generated change breaks something.

GitHub Desktop gives you all of that through a graphical app — no git commands to memorise.

Before You Start

1. Install and Sign In

1. Download GitHub Desktop from desktop.github.com and run the installer.
2. Launch it. On the welcome screen, click Sign in to GitHub.com.
3. A browser tab opens — authorise GitHub Desktop, then return to the app.
4. Confirm your name and email when prompted (this stamps your commits). Click Finish.

2. Create or Clone a Repository

A repository ("repo") is the tracked folder for one project. You have two starting points.

Start a new repo from your solution folder

1. File → New repository (or Add → Create new repository).
2. Name: e.g. contoso-field-service.
3. Local path: point it at (or near) your unpacked solution folder.
4. Tick Initialize this repository with a README, and set Git ignore to Node if your project has a Code App or Power Pages site (keeps node_modules out).
5. Click Create repository.

Or clone an existing one

If a repo already exists on GitHub: File → Clone repository, pick it from the list, choose a local path, and click Clone.

Tip — keep your PAC CLI export target inside the repo folder. Then every pac solution export + unpack shows up as tracked changes you can review and commit.

3. Set Up Your Repo for Power Platform

Before your first commit, do two things that will save real pain later: write a .gitignore for Power Platform files, and lay out the folders the AI tools will write into. Five minutes now, every future commit is cleaner.

3a. A .gitignore for Power Platform

Without one, your first commit will sweep in node_modules, build output, and — worst case — secrets from .env files or flow JSON exports that contain connection strings. None of that belongs in a public (or even private) repo.

Create a file called .gitignore in the root of your repo with this content:

# ── Secrets — never commit these ────────────────────────
.env
.env.*
!.env.example
*.pem
*.key
auth.json
.pac-auth

# ── Node / web (Code Apps, Power Pages Code Sites) ──────
node_modules/
dist/
build/
.next/
.astro/
.vite/
*.tsbuildinfo

# ── Packed solution outputs (keep the unpacked source) ──
*.zip
/releases/
/out/
/bin/
/obj/

# ── Editor / OS noise ───────────────────────────────────
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
!.vscode/mcp.json
.idea/
.DS_Store
Thumbs.db

# ── Logs & local state ─────────────────────────────────
*.log
.cache/
.tmp/

The pattern !.env.example says "ignore .env files except .env.example" — that's how you commit a safe template for teammates without leaking real values.

Critical: never commit raw exported flow JSON if it contains a hard-coded API key, secret, or connection string. Use environment variables and connection references — and let the .gitignore rules above catch the obvious mistakes.

3b. Recommended folder structure

One layout that works for a typical PP solution with multiple asset types:

contoso-field-service/
├── CLAUDE.md                       ← project memory for Claude Code
├── .github/
│   ├── copilot-instructions.md     ← project memory for GitHub Copilot
│   └── prompts/                    ← reusable prompt files (optional)
├── .vscode/
│   └── mcp.json                    ← Dataverse MCP for Copilot Chat
├── solutions/
│   └── ContosoFieldService/
│       ├── src/                    ← unpacked solution (pa.yaml etc.)
│       └── pack.cmd                ← your "pac solution pack" wrapper
├── flows/                          ← exported flow JSON
├── canvas-apps/                    ← .pa.yaml files per app
├── code-apps/                      ← React/Vite Code App projects
├── power-pages/                    ← Code Site or classic portal files
├── scripts/                        ← PAC CLI scripts (Dataverse schema, deploy)
└── docs/                           ← decisions, runbooks, diagrams

Why this matters: when Claude Code or Copilot generates an asset, they need a predictable place to put it. With this layout, /dv-metadata writes scripts under scripts/, /create-code-app scaffolds into code-apps/, and your pa.yaml from pac canvas unpack lands under canvas-apps/ — every time, the same way.

4. Make Your First Commit

A commit is a saved snapshot. After you (or Claude Code) add or change files in the repo folder:

1. Open GitHub Desktop. The Changes tab (left) lists every modified file, with a line-by-line diff on the right.
2. Review the diff. Tick the files you want to include (all are ticked by default).
3. At the bottom-left, write a Summary — short and specific, e.g. Add fs_workorder table + status choices.
4. Click Commit to main.

That snapshot is now saved locally. Good commit summaries are how "what did the AI change last Tuesday" becomes answerable.

5. Push to GitHub

Committing saves locally; pushing uploads to GitHub so it's backed up and shareable.

1. Click Publish branch (first time) or Push origin (after that), top-right.
2. If it's a brand-new repo, you'll choose whether it's public or private. For client work, choose Private.

Refresh your GitHub.com profile — the repo and your files are there.

6. Work on a Branch

Branches let you make changes in isolation without touching main until they're reviewed. This is exactly where AI-generated changes should land first.

1. Click the Current Branch dropdown (top) → New Branch.
2. Name it for the change, e.g. add-notify-technician-flow.
3. Click Create Branch. You're now working on it — commits go here, not to main.
4. Let Claude Code generate the flow, review the diff in the Changes tab, commit, and Publish branch.

7. Open a Pull Request

A pull request (PR) proposes merging your branch into main — the moment a human (or Copilot) reviews what the AI built before it becomes the source of truth.

1. After pushing your branch, GitHub Desktop shows Preview Pull Request / Create Pull Request.
2. Click it — your browser opens GitHub with the diff pre-filled.
3. Add a title and description (what changed and why), then Create pull request.
4. Review the diff on GitHub. When it's approved, click Merge pull request. The change is now on main.

This is the loop your AI-assisted work should run through every time: branch → AI generates → review the diff → PR → merge. Generation gets faster; the review gate is what keeps quality high.

8. The Daily Rhythm

Once it's set up, the day-to-day is just four buttons:

• Fetch origin — pull down anything new before you start.
• Changes tab — review what you or the AI changed.
• Commit — snapshot it with a clear summary.
• Push origin — back it up to GitHub.

Where to Next

• Point your AI tools at this repo: Claude Code Setup Guide and GitHub Copilot Setup Guide.
• Read Chapter 2 — Your AI Dev Team to see version control and the AI tools working together on a real solution.