Skip to content

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:

Terminal window
git --version

It 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:

Terminal window
cd /d C:\dev\mygame
  1. 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 as your-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.

  2. 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 init
    git add .
    git commit -m "Start my game from Labrador's starter project"

    git init answers Initialized 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 it

    They say only that Git will store the file’s line ends in its own way. git commit then prints one create mode line for each file and starts with:

    Output
    [master (root-commit) 9d004a4] Start my game from Labrador's starter project
    1145 files changed, 319765 insertions(+)

    Your seven characters after root-commit differ, 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 .gitignore leaves it out.

    If you have opened the project in Visual Studio, check before the commit line that its .vs folder 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 only out/:

    Terminal window
    git status --short .vs

    It 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 .gitignore alone does not, because git add . has already recorded its files:

    Terminal window
    echo .vs/>> .gitignore
    git rm -r --cached -q .vs
    git add .

    The git add . prints its line-end warnings again, and git status --short .vs then prints nothing. Run the git commit line now.

    If git commit says Author identity unknown, do Tell Git who you are, then run the git commit line 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.

  3. Name the branch main. A repository’s history is kept on a branch, and Git names the first one master unless it was told otherwise. GitHub names it main, and the next steps do too:

    Terminal window
    git branch -M main
    git branch --show-current

    The first prints nothing; the second prints main.

  4. 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 as D:\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; mygame is 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 .gitignore or 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.

  5. Tell your project where the repository is. Paste this line, and before you press Enter, change your-name to your GitHub username, and mygame too 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.git

    It prints nothing. origin is the name your project now uses for the repository on GitHub. Check it:

    Terminal window
    git remote -v
    Output
    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.

  6. Send the project to GitHub, which Git calls a push:

    Terminal window
    git push -u origin main

    If 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.0 starter 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 -> main

    The 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. -u makes origin’s main the place a plain git push sends to from now on. If it fails, the message is under If something fails.

  7. 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.txt and the rest, with your commit’s message beside them. Your project is on GitHub.

After you change the game and it builds and passes its tests, record the change and send it, in the same folder:

Terminal window
git add .
git commit -m "Say what you changed"
git push

Change 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.

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.

  1. 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.

  2. Wait for it. The first run needs to build the engine’s libraries from vcpkg and keep them for next time. The v0.3.0 starter’s first plain-file push on 16 November 2026 passed with a windows job 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.

  3. 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 job
    Run actions/checkout@v4
    Point at the runner's vcpkg
    Cache vcpkg's binaries
    Find vcvars64
    Configure
    Build
    Test
    Post Cache vcpkg's binaries
    Post Run actions/checkout@v4
    Complete job

    Click 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-debug
    Start 1: MyGameTests
    1/2 Test #1: MyGameTests ...................... Passed 0.35 sec
    Start 2: MyGameSmokeTests
    2/2 Test #2: MyGameSmokeTests ................. Passed 0.76 sec
    100% tests passed out of 2

    D:\a\mygame\mygame is 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 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.

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.

Troubleshooting lists these messages too.

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.

All documentation versions