Put your project on GitHub
GitHub keeps a copy of your project on the internet. With it you can get your work back if your
machine fails, share the code, and have GitHub build and test the game every time you send it a
change: the starter project already has the instructions for that, in
.github\workflows\ci.yml. This page takes the project from
Get the starter project from your machine to GitHub and reads the
first build GitHub runs. It takes about 20 minutes, most of it making the account and waiting for
the first build.
You need Git: step 2 of Install the tools installs it, and step 5 there, Tell Git who you are, gives it your name and an email address. Do both first if the starter page let you skip them. Check Git in the x64 Native Tools Command Prompt:
git --versionIt prints a version, such as git version 2.52.0.windows.1. If it says 'git' is not recognized, Git is not installed, or was installed after this prompt opened: open a new prompt
and try again.
Every command runs in the x64 Native Tools Command Prompt, in your project’s folder:
cd /d C:\dev\mygame-
Make a GitHub account, if you do not have one. It is free. Open github.com/signup in your browser and follow the prompts: an email address, a password and a username. Choose the username with care: it is in the address of everything you put on GitHub, such as
https://github.com/your-name/mygame, and these pages write it asyour-name. During sign-up GitHub asks you to verify the email address, with a message it sends there. Continue with Google on the same page signs up with a Google account instead. -
Make your project a Git repository. If you have already done Put your project in Git, skip to step 3. Otherwise, these three lines record every file of the project, the engine’s included, as the first commit, the first saved version in its history:
Terminal window git initgit add .git commit -m "Start my game from Labrador's starter project"git initanswersInitialized empty Git repository in C:/dev/mygame/.git/, and may add a few lines of hints about the name of the first branch, which you can ignore.git add .can print line-end warnings like this one, which are harmless:Output warning: in the working copy of 'vcpkg.json', LF will be replaced by CRLF the next time Git touches itThey say only that Git will store the file’s line ends in its own way.
git committhen prints onecreate modeline for each file and starts with:Output [master (root-commit) 9d004a4] Start my game from Labrador's starter project1145 files changed, 319765 insertions(+)Your seven characters after
root-commitdiffer, and the counts depend on the engine’s version and grow with your game. The build folder,out, is not among the files: the project’s.gitignoreleaves it out.If you have opened the project in Visual Studio, check before the
commitline that its.vsfolder is not among them either, because that folder is Visual Studio’s own and changes every time it opens. A starter made since 31 October 2026 lists.vs/in its.gitignore, and this prints nothing; an older one lists onlyout/:Terminal window git status --short .vsIt prints nothing when the folder is not recorded. If it prints lines starting
A .vs/, these three lines leave the folder out; adding.vs/to.gitignorealone does not, becausegit add .has already recorded its files:Terminal window echo .vs/>> .gitignoregit rm -r --cached -q .vsgit add .The
git add .prints its line-end warnings again, andgit status --short .vsthen prints nothing. Run thegit commitline now.If
git commitsaysAuthor identity unknown, do Tell Git who you are, then run thegit commitline again.This keeps the engine’s files in your repository as plain files, as the ZIP gave them. To move to a newer Labrador later, follow Move a starter project to a newer Labrador and commit the result. Put your project in Git makes the engine a pointer to Labrador’s repository instead; either works with GitHub and its build.
-
Name the branch
main. A repository’s history is kept on a branch, and Git names the first onemasterunless it was told otherwise. GitHub names itmain, and the next steps do too:Terminal window git branch -M maingit branch --show-currentThe first prints nothing; the second prints
main. -
Make an empty repository on GitHub. Signed in on github.com, click the + at the top right of any page, then New repository. On the form:
- Owner is your username.
- Repository name:
mygame, or your game’s name, short. Letters, digits,-,_and.only. GitHub’s build checks the project out in a folder named twice after the repository, such asD:\a\mygame\mygame, and that folder must stay under 100 characters for the reason Choose a short folder gives, so keep the name under 40 characters;mygameis 6. - Description is optional.
- Public or Private: see What is public at the top of this page and Build minutes below.
- Leave the repository empty. Do not add a README, a
.gitignoreor a licence: your project already has its files, and a repository that starts with one of these refuses your first push (If something fails has the fix).
Click Create repository. GitHub opens a Quick setup page for the empty repository. Under it, the HTTPS address is the one to use, such as
https://github.com/your-name/mygame.git; the copy button beside it copies it. The page also lists commands for push an existing repository from the command line: they are the ones in steps 3, 5 and 6 here. -
Tell your project where the repository is. Paste this line, and before you press Enter, change
your-nameto your GitHub username, andmygametoo if you named the repository differently, as Typing the commands shows; or delete the address and paste the one you copied:Terminal window git remote add origin https://github.com/your-name/mygame.gitIt prints nothing.
originis the name your project now uses for the repository on GitHub. Check it:Terminal window git remote -vOutput origin https://github.com/your-name/mygame.git (fetch)origin https://github.com/your-name/mygame.git (push)with your username. If the address is wrong, fix it as If something fails shows, rather than adding it again.
-
Send the project to GitHub, which Git calls a push:
Terminal window git push -u origin mainIf this machine has not already signed in to GitHub, the first push asks who you are. A window titled Connect to GitHub opens, from Git Credential Manager, which came with Git for Windows. Click Sign in with your browser. Your browser opens a GitHub page asking you to authorize Git Credential Manager; sign in there if it asks, and click Authorize. The browser then shows Authentication Succeeded. You may now close this tab and return to the application. Close the tab: the push carries on in the prompt. Windows keeps the sign-in, so later pushes do not ask again. The window’s Sign in with a code button does the same through a code you type on a GitHub page, for when the browser does not open.
The prompt shows the upload’s progress when it runs in an interactive prompt. The completed first push of the
v0.3.0starter to the proof repository printed these final lines:Output branch 'main' set up to track 'origin/main'.To https://github.com/your-name/mygame.git* [new branch] main -> mainThe address has been changed to the example’s; yours names your repository. Progress output, ordering and upload time depend on your prompt, project and connection.
-umakesorigin’smainthe place a plaingit pushsends to from now on. If it fails, the message is under If something fails. -
Look at it on GitHub. Reload the repository’s page in your browser. It now lists your project’s folders and files:
.github,external,game,CMakeLists.txtand the rest, with your commit’s message beside them. Your project is on GitHub.
Sending the next change
Section titled “Sending the next change”After you change the game and it builds and passes its tests, record the change and send it, in the same folder:
git add .git commit -m "Say what you changed"git pushChange the message between the quotation marks to one line that says what you changed; you can
edit it there before pressing Enter. git status shows what git add . will record, and prints
nothing to commit, working tree clean when everything is already committed. git push prints
the same kind of output as step 6, shorter, and ends main -> main. A git commit that prints
nothing to commit recorded nothing, because nothing changed since the last commit.
Save and undo changes with Git shows the rest of the everyday loop:
git diff, the history, and undoing an edit or a commit.
Watch GitHub build it
Section titled “Watch GitHub build it”Every push starts a run of the workflow in .github\workflows\ci.yml: GitHub borrows a Windows
machine with Visual Studio on it, called a runner, checks your project out there, and runs the
same configure, build and test commands you run, then reports. You do nothing to start it. The
workflow and each of its steps are explained in Check your game in CI.
-
Open the run. On your repository’s page, click Actions, under the repository’s name. The page lists runs, newest first, each named after its commit’s message: the first is Start my game from Labrador’s starter project, from the workflow named build and test. A run that is still going has a yellow dot or a turning circle; it becomes a green tick when it passes, or a red cross when it fails. The same mark appears beside the commit on the repository’s front page, and clicking it lists the run too.
-
Wait for it. The first run needs to build the engine’s libraries from vcpkg and keep them for next time. The
v0.3.0starter’s first plain-file push on 16 November 2026 passed with awindowsjob of 1 minute 48 seconds, including 71 seconds configuring and 20 seconds building. The earlier submodule project’s first run took 2 minutes 31 seconds; its cached second run took under two minutes. Your connection, runner and project affect these times. -
Read it. Click the run’s name. Its page shows one job, windows; click it. The job’s steps are listed in order, each with a tick or a cross, and a step that never ran in grey. This example is from the v0.3.0 starter run:
The v0.3.0 windows job's steps Set up jobRun actions/checkout@v4Point at the runner's vcpkgCache vcpkg's binariesFind vcvars64ConfigureBuildTestPost Cache vcpkg's binariesPost Run actions/checkout@v4Complete jobClick Test to open its log. The end is your two tests passing, as on your machine:
Test Test project D:/a/mygame/mygame/out/build/x64-debugStart 1: MyGameTests1/2 Test #1: MyGameTests ...................... Passed 0.35 secStart 2: MyGameSmokeTests2/2 Test #2: MyGameSmokeTests ................. Passed 0.76 sec100% tests passed out of 2D:\a\mygame\mygameis where the runner keeps your project. The v0.3.0 run showed a warning that checkout and cache targeted Node.js 20. The development recipe pins newer Action commits that target Node.js 24, so its checkout step displays the pinned commit.
A failed run
Section titled “A failed run”A red cross means a step failed, and the steps after it were skipped. On the run’s page, click
the windows job: the failed step has a cross and its log is already open, ending in a red
line such as Process completed with exit code 1.. That line only says the step failed; the
reason is above it. Scroll up to the first line that says error, FAILED or ***Failed, or
type error in the Search logs box at the top right of the log. The step tells you where to
look:
| The step with the cross | What happened | What to do |
|---|---|---|
| Configure | CMake stopped before building, as it would on your machine. Read the log’s CMake Error lines. If it says does not contain a CMakeLists.txt file about external/labrador, the engine folder was not pushed: run dir external\labrador on your machine, then git status. |
Fix it on your machine, check that cmake --preset x64-debug works there, then commit and push. |
| Build | The compiler or linker stopped. The log’s error lines are the same as on your machine; Read a build error shows how to find the one that matters. A change that builds at home but not here is usually a file you created and did not commit: git status lists it as untracked. |
Fix it, check that it builds at home, commit and push. For a missing file, git add ., commit and push. |
| Test | A test failed: the log shows ***Failed and, for the start-up test, the startup failure: line that says why. The step ends Process completed with exit code 8., ctest’s code for failed tests. |
Run ctest --preset x64-debug on your machine. If it passes there, the runner lacks something your machine has, most often a content file that is not committed: git status lists it. |
Build, with C1083 or Cannot open compiler generated file |
A path is longer than the compiler allows, because the repository’s name is long. | Rename the repository shorter, under its Settings, then run git remote set-url origin with the new address, as below. |
| Set up job, or the run never starts | GitHub could not give the job a runner. For a private repository, the month’s included build minutes may be used up; GitHub’s message on the run says so. | See Build minutes. |
To run the same commit again, for example after a failure that was GitHub’s rather than yours, open the run, click Re-run jobs at the top right, and Re-run failed jobs or Re-run all jobs. A fix to your project is a new commit and push instead, which starts a new run.
Build minutes
Section titled “Build minutes”GitHub’s runners are free for a public repository. A private repository’s runs come out of a monthly allowance that a free account includes, worth US$12 a month at the time of writing; a Windows runner costs US$0.010 a minute, so that is about 1,200 minutes, or about 400 runs of the starter at three minutes each. When it is used up, GitHub stops starting runs until the next month, unless you add a payment method and allow more. The current figures are on GitHub’s GitHub Actions billing page; your account’s Settings, then Billing and licensing, shows what you have used.
If something fails
Section titled “If something fails”Troubleshooting lists these messages too.
Where to go next
Section titled “Where to go next”- Put your game on the web publishes the browser build with GitHub Pages, from this account, so a friend can play it from a link.
- Send your game to a friend zips the Windows release.
- Check your game in CI explains each step of the workflow, and what to change as the project grows.
What was checked
Section titled “What was checked”On 16 November 2026 the current release’s labrador-starter-v0.3.0.zip was downloaded,
its published SHA-256 checked, and its unchanged files extracted into a new folder. Steps 2,
3, 5 and 6 then ran against a new dedicated public repository,
matt439/labrador-starter-proof, using the
already authenticated owner account. The commit recorded 1,145 plain files, including the
engine, with no submodule. The commit counts and final push output above are from this run;
the push address is changed to the example’s. The run used existing credentials and does not
verify Credential Manager’s sign-in window.
The first push’s workflow
passed on windows-latest, with the unchanged ci.yml supplied by the ZIP. The two test times
above are from that run’s log, with its repository name changed to mygame in the path. The
public Actions summary showed the push, commit, main branch and windows job; its step
names, timings, test log and final success were read with gh run view. The repository was
created using GitHub CLI, rather than the browser form. Account sign-up, the browser’s
new-repository form, Credential Manager’s sign-in window and the Actions log’s interactive
controls were not followed; those instructions retain that qualification.
On 2026-10-30, in a starter project made from a starter ZIP of this tree at
C:\dev\g8-author\mygame, with Git for Windows 2.52.0 and its Git Credential Manager 2.6.1, the
commands of steps 2, 3 and 5 ran as shown, and their output was quoted from that run with the folder
changed to C:\dev\mygame. git add . printed 175 line-end warnings; the commit recorded 1,125
files and left git status clean.
That October run made no GitHub account or repository and pushed nothing to GitHub. Steps 1, 4 and 6’s sign-in, the Actions pages and the billing figures were written from GitHub’s documentation as it stood on 2026-10-30: Creating an account on GitHub, Creating a new repository, Adding locally hosted code to GitHub, Using workflow run logs, Re-running workflows and jobs and GitHub Actions billing. The Connect to GitHub window’s title, its Sign in with your browser and Sign in with a code buttons and the browser’s Authentication Succeeded page are read from Git Credential Manager’s own source and the copy installed here; the window was not opened. The push output then shown in step 6 was a real push of this project, to an empty repository on the same machine standing in for GitHub, with the address line changed: the counts and size are this project’s, and GitHub’s own extra lines, if any, were not seen.
The failure messages were made on purpose with the credential helper turned off, so that nothing
could sign in: src refspec main does not match any with the branch left as master and with no
commit; remote origin already exists; Authentication failed and Invalid username or token
from a push to GitHub with a made-up username and password in the address; Could not resolve host for github.con; 'orign' does not appear to be a git repository; and [rejected] (fetch first) and the --force recovery against a local repository holding a README commit, which is
the same refusal Git prints for GitHub. Repository not found needs a sign-in, so its wording is
GitHub’s documentation’s. The Credential Manager removal steps were not followed.
The CI run’s steps, times and log lines were read, with gh run view, from the workflow’s
recorded runs on the public repository
matt439/labrador-mygame, which holds the project
Start your own project builds; its first run took 2 minutes 31 seconds and the next 1 minute 38
seconds. The test log then quoted was the first run’s, run 40242503246, which its push started, with
the repository’s name, labrador-mygame, changed to mygame in its path. Process completed with exit code 8. is from a failed test step in a run of Labrador’s own CI. That a starter project
pushed as plain files, with no submodule, runs the same workflow was then checked by cloning the
October commit from the stand-in repository into a fresh folder, as a runner’s checkout does,
and configuring, building and testing it there. The November proof above closes the hosted
plain-file workflow gap.
On 2026-10-31 a second agent followed the page as worded in another fresh starter at
C:\dev\g8-follow\mygame, with the credential helper off and a local stand-in repository in place
of GitHub. Git printed git version 2.52.0.windows.1; git add . took 5.5 seconds and printed 188
line-end warnings, within the page’s about 175; the commit, git branch -M main, git remote -v, the push to an empty stand-in, Sending the next change, and every failure above except
Repository not found and 'git' is not recognized gave the output quoted, Authentication failed included from GitHub
itself; and gh run view listed the same eleven job steps. Two points were corrected: the test
log had been the second, manually started run’s, with times of 0.41 and 0.90 seconds, and was changed
to the first run’s; and the follower’s commit recorded a startup.txt that
Send your game to a friend had written into the project’s folder,
which that page now writes to %TEMP%. The follower also found the starter’s own ci.yml
saying the engine is a submodule, which is false for a project committed as this page commits
it; its comment now covers both.
On 2026-10-31 a reviewer ran steps 2, 3 and 5 again in a third fresh starter: 187 warnings, 1,128
files, and the remote origin already exists, 'orign', src refspec and github.con messages
as quoted. The reviewer also found that adding .vs/ to .gitignore after git add . leaves the
folder’s files recorded, as a scratch repository with a .vs file showed; step 2 now takes them
out with git rm -r --cached, which that repository confirmed. Visual Studio itself was not opened
for it.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.