Git Macro Projects and Code Sync for Cloud Runs

Every macro project in Macro Automation Studio (MAS) is a git repository, and every cloud run starts with a code sync that copies your working tree to the cloud. This page covers the Git view in the Code Editor, where the files live on disk, how code sync works, and the two API routes behind it. It is for people who edit projects, use branches, or run on cloud devices.

Every macro project is a git repository

When you create a code project, MAS creates a repository on its git host and clones it the first time you open the project. The remote URL has the form https://<api host>/git/<user id>/<project id>.git, authenticated with your MAS sign-in; there are no separate git credentials. The remote is named origin and the default branch is master. MAS adds a .gitignore with .vscode/, __pycache__/ and *.pyc.

Later opens fetch the remote and pull the current branch when the pull is a fast-forward. Nothing is committed or pushed on its own: there is no sync button and no auto-commit. Local runs and cloud runs both execute the working tree, so uncommitted edits run. Commit when you want a point to return to; push when you want the project on the server, for example to open it on another computer.

The Git view

Open the Git view in the editor sidebar. It shows the current branch, how many commits it is ahead of or behind the remote, and the changed files with a status of Modified, Added, Deleted or Untracked.

Commit

1. Review a file with Open diff. Discard returns it to the last commit.
2. Click Stage on each file, or Stage all. Unstage and Unstage all reverse it.
3. Enter a commit message and click Commit.

Push and pull

• Push sends the current branch to origin. The first push of a new branch also sets it to track the remote.
• Pull fetches and fast-forwards the current branch. If the remote branch has moved in a way that needs a merge, MAS reports “non-fast-forward pull is not supported” and leaves your files alone; resolve it with a git client of your choice.
• A branch that only exists locally shows “This branch has not been published yet”. Publish it to push it and start tracking.

Branches and merges

• Create branch makes a new branch, and by default switches to it.
• Switch to Branch checks out another branch. MAS warns when open files have unsaved edits, which would be discarded.
• Merge Branches… merges one branch into another. Only fast-forward merges are supported; a merge that needs a merge commit is refused with “non-fast-forward merge required”, and the branches stay as they were.
• When a pull leaves conflicts, each conflicted file offers Accept ours and Accept theirs, then Stage resolved file. Finish with Complete Merge or back out with Abort Merge.

History

The commit list shows hash, message, author and time. Inspect diff shows the files a commit changed with their before and after content. Restore to this commit returns the working tree to that commit.

Adopt an existing repository

If the project folder already contains a git repository whose remotes do not point at MAS, the editor shows “Existing Git Repository Found” with two choices:

• Adopt keeps your folder, branches and remotes. MAS adds its host as a remote named mas, shows the files that would change on the server, and asks you to confirm before it overwrites the server copy with your current branch.
• Move aside renames your folder to a backup and clones a fresh copy from MAS.

A repository with no remotes at all is attached to MAS without a prompt.

Where the working tree lives

The name part is lowercased with spaces turned into underscores. You can open the folder in any editor or git client; MAS watches it and reloads changed files. The editor itself only writes files under 5 MB with an allowed extension; the list is on the Studio tour.

Code sync before a cloud run

A cloud device runs your macro server-side, so the cloud needs your code. MAS does not use git for that. Before every cloud run, whether from the Code Editor’s Run with a cloud device selected or from Start on a cloud device card, MAS does the following:

1. Hashes the project folder into a content-addressed identity: one SHA-256 over the sorted list of files, sizes and file hashes.
2. Asks the server for the macro’s current code state (GET /api/macros/{id}/code-state).
3. Uploads a zip of the working tree (POST /api/macros/{id}/code-snapshot) only when the hash differs. An unchanged tree costs one small request.
4. Starts the run on the snapshot.

The Console shows “Syncing code” while this happens, and MAS shows the toast “Syncing code to cloud device”. A sync failure fails the run with the server’s reason, such as a syntax error with file and line, so a run never silently executes stale code.

What goes into the snapshot:

• Every regular file in the project folder, except paths with a dot-prefixed segment (.git, .venv, .claude, and so on), __pycache__, node_modules, venv, and *.pyc files.
• At most 500 files, and a zip of at most 10 MiB. Over either limit, the run stops before upload with a message that names the limit.
• The entry point: src/app.py, then any main.py, then the first .py file.
• Template images are not in the zip. MAS reads the image IDs from your mas.images call and fetches those images from your Image Library at run time. Only images you own resolve.

The server keeps the last 10 snapshots per macro, allows 10 uploads per minute, and gives each account 500 MB of snapshot storage. A project with no local Python files, such as a Marketplace bot, skips sync and runs from its published source. What a cloud device includes, and how to create one, is on the cloud devices page.

Code sync from the API

Both routes accept an API key in the X-API-KEY header, so a build server can push code and start a run without the app. Create a key on API keys; the other routes are on the REST API page.

GET /api/macros/{id}/code-state returns the current snapshot, or 404 when the macro has never been synced:

{
  "worktree_hash": "e9b721da...",
  "entry_path": "src/app.py",
  "size_bytes": 4096,
  "file_count": 3,
  "created_at": "2026-09-04T10:00:00Z"
}

POST /api/macros/{id}/code-snapshot takes the zip as base64 and the hash you computed. The server recomputes the hash from the bytes it received and rejects a mismatch. entry_path is optional. The request body may be up to 16 MiB.

{
  "zip_file_base64": "UEsDBBQ...",
  "worktree_hash": "e9b721da...",
  "entry_path": "src/app.py"
}

The response carries the stored worktree_hash, the file_count and whether a new snapshot was created. Then start the run with POST /api/hosted/devices/{id}/run, as described on Cloud devices.

Troubleshooting

non-fast-forward pull is not supported

The remote branch and your local branch have diverged. MAS does not merge on pull. Commit your work, then resolve the divergence with a git client, or create a branch from your local state and pull master fresh.

Existing Git Repository Found

The project folder already holds a repository that points elsewhere. Choose Adopt to keep it and overwrite the MAS copy, or Move aside to keep it as a backup and clone a fresh copy. Cancel leaves the folder untouched and does not load the project.

project has more than 500 files

Code sync stopped before upload. Remove generated files and data from the project folder, or move them into a dot-prefixed folder such as .data, which sync ignores. A venv folder inside the project is ignored already.

code snapshot storage quota exceeded

Your account has reached its 500 MB of snapshot storage. Delete macros you no longer use, or contact support at support@automationmacro.com.