ISOM 472 · Fall 2026/2027

Publishing from your repository

Get the repository onto your laptop, move work through a branch and a pull request, and publish the proposal at its own address.

This page has three parts. The first gets the team repository onto your laptop. The second is the loop every change goes through for the rest of the semester — branch, commit, pull request, review, merge. The third publishes the team's proposal at a public web address. Each step says what you should see when it has worked.

Nothing goes straight onto main. Every change, from the proposal onwards, travels on its own branch and is merged by a teammate who read it. Part 2 is that loop, and it starts on day one.

Part 1 — Getting the repository onto your laptop

This assumes GitHub Desktop and Antigravity are installed and you are signed in to your own GitHub account, from the setup guide, and that the instructor has created your team's repository. Everything the team produces — code, the prototype, the ledger, the notes — lives in that one repository.

Every GitHub Desktop screenshot on this page is from macOS; on Windows the same buttons carry the same names and sit where the text describes.

Accept the invitation first

When the instructor creates the team repository, GitHub emails an invitation to the address on your GitHub account. Open it and accept it. Until you do, the repository does not belong to you on GitHub and will not appear in GitHub Desktop's list of repositories to clone.

  1. Open the invitation email and click the button that accepts it. If you cannot find the email, sign in to github.com — the invitation also appears there, at the top of the page.
  2. Accept it.

You should see the team repository open on github.com under your own signed-in account, with its files listed.

Clone the team repository

  1. Open GitHub Desktop.
  2. Open the File menu — on Windows this is inside the GitHub Desktop window itself; on macOS it is in the menu bar at the top of the screen — and choose Clone repository…
  3. Select the GitHub.com tab and find your team's repository in the list.
  4. Choose a folder on your laptop for the local path, then click Clone.

You should see the team repository listed under GitHub.com in the Clone dialog, and then, after cloning, GitHub Desktop showing that repository with its files in the folder you chose. If it is not in the list, the invitation has not been accepted — go back a step.

GitHub Desktop’s main window on a freshly cloned repository. Current Repository at the top left names the repository, Current Branch says main, and the column below holds the Changes and History tabs above a line reading 0 changed files. The large panel on the right reads “No local changes”, offering buttons to open the repository in an external editor, show it in Finder, or view it on GitHub.
GitHub Desktop just after cloning: the repository name at the top left, and the empty Changes tab that an edited file turns up in.
GitHub Desktop’s Clone a Repository dialog. The GitHub.com tab is selected, and under a filter box the repositories on the signed-in account are listed, one of them highlighted. Below the list, a Local Path field holds the folder the repository will be copied into, with a Choose button beside it, and a blue Clone button sits at the bottom right.
Find the team repository on the GitHub.com tab, check the folder in Local Path, then click Clone.

Open the same folder in Antigravity

GitHub Desktop moves the work. Antigravity is where you build it. Both point at the one folder GitHub Desktop just cloned — not a copy of it, and not a second download.

  1. Open Antigravity.
  2. Choose File › Open Folder.
  3. Select the folder GitHub Desktop cloned into, and open it.

You should see the repository's files in Antigravity's file list, with the same names you see in GitHub Desktop. From here on, a file you save in Antigravity appears under Changes in GitHub Desktop within a second or two.

The email your commits carry

Every commit carries a name and an email address, and GitHub matches that email to an account. The email GitHub Desktop commits with must be an email address on your GitHub account. If it is not, github.com shows the commit as plain grey text with no avatar and no link to you, and the work is not attributed to you at all. Check this before your first commit, not after twenty of them.

  1. Open GitHub Desktop's settings — File › Options on Windows, GitHub Desktop › Settings on macOS, named Preferences in older versions.
  2. Choose the Git tab.
  3. Read the Email field. It must be an address listed on your GitHub account. If it is not, replace it with one that is.
  4. To see which addresses count, open https://github.com/settings/emails while signed in to GitHub.

You should see, after your first push, your avatar and your GitHub username beside the commit on github.com, and your username linking to your profile. Grey text with no avatar means the email does not match — fix the Email field before you commit again.

GitHub Desktop’s Settings window with Git selected in the left sidebar. The pane on the right holds a Name field and an Email field, both blanked out here, above a field setting the default branch name for new repositories to main. Cancel and Save buttons sit at the bottom.
The Git tab of settings. The Email field is the one that decides whether a commit is attributed to you.

Your commits, your pull requests and your reviews are the record of what you personally did in this course, and they are the only record that exists. An unattributed commit is work nobody can trace to you.

Part 2 — The loop: branch, commit, pull request, review, merge

Every change goes through these nine steps, including the proposal in Phase 1. The rules behind them — one branch per story, what a commit message contains, what a pull request must say, and what a review means — are on the repository page. This page is the buttons.

1. Start a branch

One branch per story. The branch is made from main, so check what you are branching from before you make it.

  1. In GitHub Desktop, look at the Current Branch button at the top. It should say main. If it does not, click it and switch to main.
  2. Click Current Branch, then New Branch.
  3. Name it <story-number>-<short-name> — lower case, hyphens between words, no spaces and no capitals. The story number is the issue number, so story #14 gives 14-duplicate-order-check.
  4. Click Create Branch.

You should see the Current Branch button now showing your new branch name instead of main, and the Changes tab empty.

The Current Branch button in GitHub Desktop clicked open. The panel underneath has Branches and Pull Requests tabs, a filter box, and a New Branch button to the right of it. Under the heading Default Branch, main is listed with a tick beside it.
Open Current Branch and check the tick is on main before clicking New Branch.
GitHub Desktop’s Create a Branch dialog. The Name field has s-1-duplicate-order-check typed into it. A line below says the new branch will be based on the currently checked out branch, main, which is the repository’s default branch. Cancel and Create Branch buttons sit at the bottom.
Lower case, hyphens, no spaces — and the line under the name tells you what you are branching from, which must read main.

2. Make the change

  1. Work in Antigravity on the folder you opened in Part 1, or open the folder directly — in GitHub Desktop, the Repository menu, then Show in Explorer (Windows) or Show in Finder (macOS).
  2. Make the change and save it.

You should see the file listed under Changes in GitHub Desktop, checked, with the changed lines shown in the panel on the right. If it is not listed, you edited a copy saved somewhere else — on the Desktop or in Downloads — rather than the file inside the cloned folder.

3. Commit to the branch

  1. In the box at the bottom left, write the summary line. It carries a type, a scope, what changed, and the story number — for example: 
    docs(proposal): add section 2, what happens today
  2. Check the commit button underneath. It reads Commit to followed by a branch name, and that name must be your branch — not main.
  3. Click it.

You should see the Changes list empty out, and your commit at the top of the History tab with your avatar beside it.

The Changes tab in GitHub Desktop. The column on the left lists one changed file, docs/proposal.md, with its tick box ticked. The panel on the right shows that file’s diff: two removed lines of placeholder text marked in red, one added line in green, and the unchanged surrounding lines in grey.
Check the left column lists the file you meant to change, and read the diff on the right so you know what the commit will carry.

The full rules for a commit message — the types, the scope, and where the story number goes — are on the repository page. Read them before your team's first commit. Commit often, in small pieces, rather than once at the end of the week.

4. Publish the branch

The branch exists only on your laptop until you publish it. Nobody can review what they cannot see.

  1. Click the button near the top of the GitHub Desktop window. The first time it reads Publish branch; every time after that, on the same branch, it reads Push origin.

You should see the button settle on Fetch origin, and the branch appear in the branch list on github.com.

A close crop of one button at the top of the GitHub Desktop window: an upload arrow icon beside the words Publish branch, with smaller grey text underneath beginning “Publish this branch to”.
The first time you push a branch, this is what the button says.
A close crop of the same button at the top of the GitHub Desktop window, now reading Push origin, with “Last fetched 2 minutes ago” underneath and a small badge showing the figure 1 beside an upward arrow.
The same button slot every time after that: Push origin, with the number of commits waiting to go up.

5. Open a pull request

  1. In GitHub Desktop, click Create Pull Request — it appears after publishing, and is also in the Branch menu. It opens github.com in your browser.
  2. Write the title in the same form as a commit message, carrying the story number.
  3. Fill in the body. The repository ships with a pull request template, so the headings are already in the box when it opens — write under each one rather than deleting them.
  4. Click Create pull request.

The body must say what changed, which story it closes, and how to check it — what the reviewer opens, what they do, and what they should see. It must also carry the AI-Assisted: declaration, on every pull request with no exceptions. The required block, the worked example and the form of the declaration are on the repository page.

You should see the pull request open on github.com with its own number, your title, your body under the template's headings, and your branch named as the source.

A highlighted panel in GitHub Desktop headed “Preview the Pull Request from your current branch”, saying the current branch is already published to GitHub. Its button reads Preview Pull Request, and the small arrow beside that button has been clicked, opening a short menu with two entries: Preview Pull Request, ticked, and Create Pull Request.
The panel that appears once the branch is published. The small arrow beside the button is where Create Pull Request lives.
GitHub Desktop’s Open a Pull Request window. A line across the top reads “Merge 1 commit into base: main from s-1-duplicate-order-check”. Below it docs/proposal.md is listed on the left with its diff filling the panel on the right. At the bottom left a green tick reads “Able to merge. These branches can be automatically merged”, next to Cancel and Create Pull Request buttons.
The preview before anything is created: check the base is main, that the branch beside it is yours, and that it says it is able to merge.

The screenshots come from two example repositories — the GitHub Desktop ones from the team repository template, the github.com ones from a worked example — so the repository name changes partway down this page while the shape stays identical. The numbers in them differ from the #14 example used in the text: there the story is #2 and the merged pull request is #3. The branch names and titles in the images also carry an s- or S- prefix, from an earlier version of these instructions; the story number is now used on its own. You can open the worked example and read the whole loop for yourself — one issue, one branch, one pull request, one review, one merge — on the worked example. The screenshots on this page were taken in an earlier copy of it, so the numbers differ; the shape does not.

The “Open a pull request” form on github.com. The two selectors at the top read base: main and compare: s-2-readme-front-page. The title box has filled itself in from the commit and reads “docs(readme): name the system [S-2]”. The description box below already holds the repository’s pull request template: a heading for what this changes, a heading for the story it closes with “Closes #__” under it, and an AI-Assisted heading, each followed by a grey comment line saying what to write there.
The browser form GitHub Desktop opens. The title arrives already written from the commit, and the template’s headings are already in the description — write under them, and replace Closes #__ with the story issue's number.
An open pull request titled “Add section 2 of the proposal [S-1] #2”, merging the branch s-1-duplicate-order-check into main. The body is written under the template headings: What this changes, The story it closes with “Closes #1”, AI-Assisted naming the tool and what the author rewrote, and For the reviewer.
The pull request as it opens: the story number in the title, Closes #1, the AI-Assisted: line, and what the reviewer is asked to check.

6. Ask a teammate to review

  1. You may find this already done: the repository names every member as an owner of every file, so GitHub requests the review from your teammates the moment the pull request opens, and leaves you out of it. To ask one person in particular, find Reviewers on the right.
  2. Click it and choose one teammate. Not yourself — GitHub will not offer you your own name.
  3. Tell them, so they know it is waiting.

You should see your teammate's name under Reviewers, and the pull request saying a review is required before it can be merged.

7. The review — done by the teammate, not the author

These steps are for the reviewer, on github.com. The author does not do them.

  1. Open the pull request and click Files changed.
  2. Read what changed. Then do what the "how to check it" section says: open it, run it, see what happens.
  3. Click Submit review, at the top right — older screens call this button Review changes.
  4. In the box, write what you opened, what you did, what you saw, and what you did not check. The last part matters as much as the rest.
  5. Choose Approve, then Submit review.

A review that says only "looks good" is not a review. Nothing was opened, nothing was run, and nothing was claimed — and the reviewer's name is on it either way. A worked example of a real review is on the repository page.

You should see the pull request show Approved with the reviewer's name and their written review on the conversation tab.

The Files changed tab of the same pull request. One file, docs/proposal.md, is listed, with the removed placeholder lines in red on the left and the new paragraph about orders arriving by phone in green on the right. A green Submit review button sits above the diff.
The reviewer reads the diff on Files changed, then clicks Submit review to write the review.
A “Finish your review” panel open over the diff, with an empty comment box above three choices. Comment is selected; Approve is greyed out and cannot be chosen, with the note “Pull request authors can’t approve their own pull requests.”
On your own pull request Approve is greyed out — GitHub will not let the author approve it.

Approve greyed out on a pull request that is not yours means you have not accepted the repository invitation. Until you accept it, GitHub treats you as a visitor to a public repository: you can read the code and write a Comment review, and Approve and Request changes stay out of reach — so your review cannot unblock anybody's merge.

Accept the invitation — it is in your email and at github.com/notifications — reload the pull request, and the choice is there. This is the single most common reason a team sits stuck on Review required.

8. Merge — the reviewer merges, never the author

Nobody merges their own pull request. The teammate who reviewed it is the one who merges it. If you wrote it, you are finished at step 6.

GitHub stops you approving your own pull request, but it will let you merge it. The button works. In this course you do neither. Merging your own work is visible in the repository, and it is the thing the rule exists to prevent.

  1. The reviewer clicks Merge pull request, then Confirm merge.
  2. On the screen that follows, the reviewer clicks Delete branch. The work is on main now; the branch has nothing left to hold.

You should see the pull request marked Merged, the change present in the repository's files on main, and the branch gone from the branch list.

The same pull request after merging. A purple Merged badge replaces Open, the line beside it reads “merged 1 commit into main from s-1-duplicate-order-check”, and the Development panel in the sidebar names the story issue the merge closed.
After the merge: the purple Merged banner, and the sidebar showing the issue it closed.

9. Come back to main

Your laptop does not know about the merge until you fetch it. Do this before starting the next story, or you will branch from work that is already out of date.

  1. In GitHub Desktop, click Current Branch and switch to main.
  2. Click Fetch origin.
  3. Click Pull origin when it appears.

You should see the merged work in the History tab while on main, and the Changes list empty. You are ready to start step 1 again for the next story.

When it goes wrong

What actually goes wrong, and what to do:

  • You committed while still on main instead of your branch. You can tell because the commit button named main rather than a branch name, and because your commit is in the History tab while Current Branch says main. Do not try to unpick it and do not push anything else on top. Tell the instructor what happened and leave it alone until it has been sorted out.
  • GitHub refused your push to main. That is the rule working, not a fault: nothing reaches main without a pull request and a review. Make a branch, push that, and open a pull request. Do not force anything, and if you cannot get your work onto a branch, tell the instructor.
  • The Create Pull Request button does nothing, or GitHub Desktop asks you to publish first. The branch was never published. Go back to step 4, click Publish branch, then try again.
  • You cannot approve your own pull request. That is the rule, not a fault, and GitHub enforces it. Do not open a second account, and do not ask a teammate to approve without reading. Ask someone to actually review it.
  • The branch list keeps growing. Merged branches are not being deleted. Whoever merges deletes the branch on the same screen, in the same minute — a list of forty dead branches hides the three that are live.

Part 3 — Giving the proposal a public address

The proposal is delivered twice. docs/proposal.md in the repository is the document that is judged. The same content, published as a page from your team's own repository, is delivered a second time — presented from its live address and checked only as reachable, not judged on how it looks.

GitHub Pages is already switched on for your team repository. The instructor sets it up when the repository is created, publishing from main at the repository root. There is nothing for the team to configure and no setting to change. Get your change onto main and the page rebuilds itself within about a minute — there is no publish button.

The address for the proposal page is https://isom472-fall2026.github.io/<your-repo>/docs/, where <your-repo> is your team number — team1, team2, and so on. The bare repository address — the one without /docs/ — is not blank: GitHub builds a page from your repository's README.md automatically, so that address serves your README rendered as a web page. Until the team fills the README in, it reads "TODO: the system's name", and it is public, so fill it in early. That address is also where the team's running system goes later in the course, which is why the proposal page sits under /docs/.

Edit docs/index.html on a branch

The file is already in your repository. It has the eight headings in the right order and a TODO paragraph under each one. Start with step 1 of Part 2: make a branch. It has no story number, so name it for the work — proposal-public-page.

Then open docs/index.html and replace every TODO with your own text. Leave the headings and the small style block at the top alone. It is not graded on how it looks, and it needs no stylesheet, no script and no images.

You should see the file open correctly if you double-click it on your own laptop before committing it — your headings and your text, with no TODO left anywhere.

Get it onto main through the loop

The page is served from main, and the only way onto main is the loop in Part 2. The proposal is not an exception to it.

  1. Commit the edited file to your branch (step 3).
  2. Publish the branch (step 4).
  3. Open a pull request, with the AI-Assisted: line filled in like any other (step 5).
  4. Ask a teammate to review it (steps 6 and 7).
  5. The reviewer merges it and deletes the branch (step 8).

You should see your own text, and no TODO, when you open docs/index.html on github.com while looking at main — not only on your branch.

Check the address

  1. Wait a minute or two after the merge. The build takes time.
  2. Open https://<owner>.github.io/<repo>/docs/ in a browser.
  3. Check it again from a phone, off the campus network — on phone data, not KU wifi.

You should see your proposal's content load at that address, from a network with no connection to the university at all. "Reachable" means reachable by anyone.

When it goes wrong

What actually goes wrong, and what to do:

  • The address returns a 404 for the first minute or two after the merge. That is normal. Wait, then reload.
  • The file is named something other than index.html. Rename it — GitHub Pages serves index.html from a folder and nothing else. Index.html, index.htm and proposal.html all fail.
  • The work was merged but the page was checked too early. Give it another minute and reload. A hard reload helps if the browser is showing you the 404 it cached a moment ago.
  • The address still shows nothing. The file is on the branch but was never merged. The page is built from main, so an open pull request publishes nothing. Check on github.com that the pull request says Merged.

The team repository is public, so anything committed to it can be read by anyone. Never put a password, a key, or a client's private data in it.

"Delivered" means both things: the file in the repository, and the page reachable at its address. One without the other is not delivered.

Written 12 September 2026. GitHub and GitHub Desktop change their screens and rename their buttons from time to time. If what you see does not match this description, follow the screen in front of you, finish the step, and tell the instructor what changed so this page can be corrected.