GitHub pull, merge and flow

On the GitHub page (button on the left) you manage everything around your code on GitHub. The page has four tabs: Overview, Changes, Branches and GitHub Pages. The GitHub settings open with the gear at the top right. Tabs and buttons use the words you also see on GitHub itself. Click such a word for an explanation, or look it up in the glossary. At Explanation of GitHub terms in the settings you choose Beginner (a short line under every button) or Advanced (only the word; the explanation appears when you hover over it).

How Coodoo works with branches

A branch is a separate version of your code. Your main branch (usually main) is the version that's "done". Coodoo has each goal work on its own branch, like coodoo/login-page-a1b2c3d4. That way main stays clean until you decide the work can go in.

• Every task is committed and pushed right away, so nothing gets lost.
• Would you rather have Coodoo work directly on your main branch? Turn off Own branch per goal under Settings.

Overview

Here you see at a glance where everything stands, and what you can do now.

• The flow bar at the top: this computer, then every branch of your flow, such as development and main. Each step shows where it stands: Up to date, 3 commits waiting, an open pull request, or work that went past the flow. The branch your project folder is on has a blue border.
• Next step: the most important thing to do, with one button. For example Pull when GitHub has newer work, Commit & push for your own changes, or Promote to main when work is ready. With nothing to do, it says Everything is up to date.
• Recent commits: the latest commits with their full description. Merges are hidden by default; turn on Show merges to see them. Click a commit to see what changed.

Changes

Everything between this computer and GitHub.

• Uncommitted changes: files that were changed but not committed yet. Click a file to see the difference. The autopilot commits its own work itself; this is what you changed yourself.

Commit & push

Did you change something yourself, for example with npm update in the terminal? Then the Commit & push block shows under Uncommitted changes. Coodoo suggests a description (such as chore: update packages); change it if you like and click Commit & push. Coodoo first checks that there are no keys in it, just like with its own commits.

• If you're on the first branch of your flow (or have no flow), the commit goes on that branch.
• On a later branch, such as main? Your flow allows nothing directly on it. Coodoo then puts your changes on the first branch (for example development) and switches your project folder to it. Then take them further with Promote on the Branches tab; Coodoo makes the pull request when needed.
• If your changes don't fit on that branch, because the same part changed there too, nothing changes, and Coodoo says what you can do.

Pull

Do you work on more than one computer, for example a PC at home and a laptop? With Pull you bring in the work from your other computer, without your work on this computer being overwritten. The behind notice at the top of the page and the Next step on Overview also bring you here.

1. What's new. Coodoo checks GitHub and shows side by side what's new on GitHub and what's only on this computer. If the same file was changed on both computers, you see it right away.
2. Agent checks it. An agent reads both sides and tells you in plain words what's coming in, what's only here, and whether they clash: Safe, Small chance of a clash or Watch out. It changes nothing.
3. Pull. Coodoo first saves your work on this computer and puts it on a reserve branch (coodoo-reserve/…, on this computer only). Then the newest version is added. If the same lines were changed, an agent combines both versions. Tick Then also push to GitHub so your other computer gets your work from here as well.

Coodoo never throws work away: no overwriting, no forcing. If combining doesn't work, it puts everything back the way it was.

Tip: on any computer, always start with Pull and finish with Push. That way you never work on an old version.

Branches

Your flow, moving work between branches, and managing your branches.

Flow

A flow is the road work takes to your live version, for example development → staging → main. That way nothing reaches main that wasn't on staging first.

Choosing a flow

Open the Branches tab and pick a template:

Template	Order
Simple	everything straight to main (no flow)
With a test branch	development → main
Three steps	development → staging → main

Or choose Make your own flow and put branches in order yourself. Click Save flow. Branches that aren't on GitHub yet are created by Coodoo from the branch further along (usually main).

What changes

• The autopilot always works on the first branch.
• Work reaches the next branch with Promote to …. You first see which commits are waiting. Skipping a step isn't possible.
• Merge and Pull only offer the first branch.
• Is there work on a later branch that isn't on the branch before it yet (for example pushed straight to main)? Bring it back with Back-merge from … at that earlier branch.
• A fixed failsafe makes sure Coodoo never pushes to a later branch outside the flow.

GitHub's rules

For each branch you see the rules that apply on GitHub, in plain words: only through a pull request, approvals, checks that must pass, and more. Coodoo takes them into account for Promote and Back-merge:

• If it's a plain step forward and GitHub asks for nothing extra, Coodoo promotes the work directly.
• Otherwise Coodoo opens a pull request from the branch before and merges it as soon as GitHub allows.
• If someone else has to approve, the pull request stays open and you see what it's waiting for. Then click Promote again.
• If both branches changed the same lines, Coodoo says so and changes nothing.

Flow on GitHub

When you click Save flow, Coodoo also puts the flow on GitHub as rules. Later branches then only change through a pull request, and no branch of the flow can be deleted or force-overwritten. That also applies to anyone working outside Coodoo.

For this your token needs the Administration (read and write) permission; a new token from Coodoo already has it. If it's missing, the flow still works in Coodoo and you see Not on GitHub yet. Then edit your token once on GitHub and click Put the rules on GitHub.

On more than one computer

The flow is kept on GitHub, so all your computers have the same flow. On Save Coodoo puts it as .coodoo/flow.json on the first branch, and as rules in the repository's settings. When you open the project on another computer, Coodoo reads the flow from GitHub: from the rules, with the order from the file. Changed the flow somewhere else? Then Coodoo takes the new flow over by itself.

Merge

This is where you put finished work into a branch of your choice, usually main. Three steps:

1. Where to

Pick Which branch should the work go to? Your default branch is already selected.

2. Which work

You see the finished goals that aren't in that branch yet. Check what should go along.

• If a goal builds on another goal, that other goal goes along automatically (Builds on …; those go along). If you uncheck a foundation, the goals that build on it are unchecked too.
• If the chosen work still has an open critical security problem, you'll see a warning. It's best to have that fixed first. If you want to go ahead anyway, check I understand the risk and want to merge anyway.

3. Merging

Click Merge into main. Coodoo:

1. Merge: merges the branches in a separate working folder, so your project folder stays untouched. If changes clash, the developer resolves that.
2. Test and check: builds and tests everything together, starts the app and looks at it, and runs the security scanners. If something is broken, it gets repaired. If anything had to be resolved or repaired, a review of the whole follows.
3. To GitHub: updates the version numbers and pushes. If the branch is protected on GitHub, Coodoo opens a pull request and merges it itself (it waits up to 30 minutes for the checks).
4. Clean up: sets the version labels (tags) and deletes the branches of the merged goals.

A merge can't start while the autopilot is paused: wait until it's done or stop it.

Tip: Old work branches that are already fully contained somewhere can be removed with Clean up.

Managing branches

• New branch: pick From which branch, give it a name and click Create on GitHub.
• Switch: puts your project folder on another branch. Uncommitted changes are safely set aside first.
• Make default: the branch Coodoo starts the work from and brings it to.
• Delete from GitHub: deletes a branch. Coodoo first checks whether there are commits that only exist on that branch and would be lost, and shows them. You then have to deliberately choose Delete anyway.

You can never delete main, master, your repository's default branch or Coodoo's default branch.

GitHub Pages

On the GitHub Pages tab you put your project online for free as a website. The website always comes from the last branch of your flow, your live version.

Can my project be a website?

Coodoo looks at your project and tells you in plain words. GitHub Pages only serves fixed files: HTML, CSS, JavaScript and images. No server and no database run there.

Can	Can't
Plain HTML files (in the root or in docs/)	Laravel and other PHP projects
Jekyll	Express and other Node servers
Vite, Astro, SvelteKit with the static adapter	Next.js with server parts
Next.js with output: 'export'	Anything with a database

If it can't, Coodoo says why, and Ask the agent asks what it would take.

Turn on GitHub Pages

Click Turn on GitHub Pages. Coodoo turns on GitHub Pages for your repository.

• Plain files and Jekyll: GitHub puts the files of your live branch online right away.
• A project with a build step (such as Vite): Coodoo puts a build file on the first branch of your flow (.github/workflows/coodoo-pages.yml). Then take it to your live branch with Promote on the Branches tab; GitHub builds the site and it goes online. Without a flow, that happens right away.

The build file checks the built files for keys. If it finds something that looks like a key, GitHub doesn't publish the site.

Note: everything on the website is public, even when your repository is private. A website from a private repository needs GitHub Pro, Team or Enterprise.

Updating

When something new lands on your live branch, the website updates by itself. Update website has it built again without any change. You see the site's address, whether it is Online or Building, and when it was last updated.

If building fails, you see which step went wrong. Let the agent fix this gives the agent the error and the end of the log in the chat.

Turning Pages off or setting a custom domain is done on GitHub itself, under Settings → Pages. Coodoo never does that.

Settings

Click the gear at the top right for the GitHub settings.

GitHub

• Own branch per goal: on (the default) or off; see above.
• Import issues: a label to only import certain issues as goals, for example coodoo. Empty means all open issues. See Goals.

Access on GitHub

Click Check to see whether your token can do everything Coodoo needs: reading, pushing, pull requests, issues and Dependabot. See What you need.

The Changes panel

At the bottom is the Changes panel with the files that are now different from the last commit: New, Changed, Deleted or Renamed. Click one to see the difference.

Bringing in changes from GitHub

Did you (or someone else) change something on GitHub? On the GitHub page, open the Changes tab and use Pull. See Pull.