Guide

Sync a workspace through GitHub or GitLab

A workspace is local by default. Track it and it also becomes a git repository on your machine; connect one remote and that history is kept in a repository you control, where another machine, another person, or CI can read it. Credentials are your own git credentials, and the sensitive parts are never written to the repository.

Download APIWeave

Git must be installed and on your PATH

Connect

An empty repository, then one URL

The host never needs to know what APIWeave is. It sees an ordinary repository, pushed by an ordinary git client.

Create an empty repository on GitHub or GitLab. Do not add a README, a .gitignore, or a first commit.
Copy its URL — the HTTPS one, or the SSH one if your key is in an agent.
In APIWeave, open Settings → Workspace settings → Version history (git) and choose Track this workspace.
Paste the URL under Remote URL and choose Connect to remote.

The first Track this workspace commits the whole workspace, and Commit automatically is on by default: a commit happens about 30 seconds after your last edit. Turn it off and Sync now commits only when you choose, after showing what the commit holds.

If git does not know who you are, the panel asks for a name and email once and keeps them in this workspace's repository only. Your global git configuration is not touched.

The connection is refused, with the workspace left unconnected, when the repository already holds history the workspace did not come from — a repository with a README and a first commit included. That is why the repository has to start empty.

Accepted URL forms

Remote URL

https://github.com/owner/repo.git
ssh://[email protected]/owner/repo.git
[email protected]:owner/repo.git
file:///path/to/repo.git

Credentials

APIWeave runs your own git with its prompts off, so the host's credentials must already be available to it: an SSH key in your agent, or a credential helper that has signed in. Credentials never go in the URL — one that carries a password, or a user name in an https:// URL, is refused, because the URL is stored in plain text. The git@ in an SSH URL is an account name and is fine. Use the SSH form, or let the credential helper answer.

Plain http:// and git:// are refused, as is a bare path such as repo.git, a URL with a query string or fragment, and a host or user name that starts with -.

What a sync does

Fetch, integrate, then push

The app runs this cycle on its own in auto mode, and when you press Sync now in manual mode. It also runs on launch and every five minutes; in manual mode those only fetch, to count what is waiting.

One sync cycle

1. Commit   the workspace's changes, if the tree changed
2. Fetch    the remote's branch
3. Integrate  fast-forward when only the remote moved;
              otherwise merge by record, node and field
4. Push     this device's commits, retrying once if the
            remote moved during the cycle

When only the remote moved, the app fast-forwards and imports its records, so both machines see the same projects, workflows, and environments. When both moved, the merge below runs first. A push the host refuses for permissions makes the workspace read-only: edits still save and commit locally, the remote's commits still come in, and an explicit retry still attempts the push.

The header shows the state as an icon and a word — synced, pending, syncing, incoming, merge needed, diverged, read-only, or an error — never colour alone. Open it for what the state means, when the workspace last synced, and its last commit.

When both machines changed

APIWeave merges by record, node and field, not by line. Changes that touch different things are combined, positions take the remote's, and an edge whose node the other side deleted is dropped; the commit message lists what the merge settled that way. The result is a real merge commit with both sides as parents.

Where the same field changed differently, the workspace stops at Merge needed and nothing is pushed or imported. Review merge shows each conflicted place side by side under Your copy and Remote copy, with a pick per field or per record. Every other change from both sides is already part of the merge. Settling the last conflict commits, imports, and pushes in one step, and the decisions survive quitting the app.

Contents

A small tree of JSON files

The repository is a projection of the workspace, written the same way on every machine so a change reviews as a small diff.

Repository layout

.apiweave/format.json              {"format": "apiweave-workspace", "version": 1}
.gitattributes                     * text eol=lf
workspace.json                     workspace id, name, description
projects/<slug>--<id>.json         name, description, color, workflow order
workflows/<slug>--<id>.json        one file per workflow
environments/<slug>--<id>.json     name, description, variables

Holds

The workspace, its projects, its workflows
Workspace environments and their plain variables
The {{secrets.NAME}} references a workflow uses

Only the files above belong to APIWeave. A README, a CI configuration, or any other file you keep in the repository is left alone.

Never holds

Secret values, their ciphertext, and the secret store
Run history and response bodies
User-scoped environments, node presets, agents, and workflow revisions

A credential typed straight into a request or a variable is withheld as <SECRET>, or a secret-named header is left out. A request that sends <SECRET> needs a {{secrets.NAME}} reference instead; the next commit writes the reference.

Another machine

Open the workspace from git

A workspace is identified by the id in workspace.json, not by its name or its URL, so opening the same repository elsewhere gives you the same workspace.

Open the workspace switcher at the top of the sidebar and choose Open from git….
Paste the repository URL and choose Open workspace.
Set the secret values the workspace references; none are in the repository.

The repository is cloned into a scratch folder and checked before anything is created: .apiweave/format.json must be there at a format version this build knows, and every file the format reads must be valid. Otherwise the open is refused, the message names the file and the problem, and nothing is left behind.

Only the repository's default branch is opened. The workspace arrives tracked in auto mode and connected to that URL, so later cycles push your commits and bring in other people's exactly as for any connected workspace.

Secret values are not in a repository, so the new workspace starts with none. Set the values its {{secrets.NAME}} references use, and replace any credential withheld as <SECRET>.

Run the repository in a pipeline

Connecting a remote is all a pipeline needs: a checkout of the connected repository holds the workspace files, with the commit subjects as their history.

Clone and run

git clone <your remote url> my-tests
apiweave run ./my-tests

# every project, or one of them
apiweave run ./my-tests --project "Shop API" --env Staging

apiweave run takes the repository folder directly, with the same importer the app uses, and never needs git installed. It defaults to every project in the repository's order; pick one with --project and an environment with --env.

Exit code 0 means everything passed, 1 means a test failed, and 2 is a usage or configuration error, such as a missing secret or an invalid file.

Secret values reach the run as environment variables named after the reference: a workflow that uses {{secrets.API_KEY}} reads APIWEAVE_SECRET_API_KEY. The repository holds only the reference.

Limits

What git sync does not do yet

Knowing the edges saves a debugging session. These are the real ones in this release.

The branch is fixed: A workspace syncs one branch — main for one the app created, or the repository's default branch for one opened from git. There is no branch picker, and the app does not create branches or open pull requests.
Environment inheritance is not carried: An environment's base environment is not written to the repository. Put the variables a run needs in the environment itself.
Local history stays separate: A workflow's own version history in the app is not its git history. The repository records the workspace's commits; it does not replace the per-workflow revisions.
Secret values are never in the repository: There is no encrypted secret material in the repository to unlock. Each machine and each pipeline supplies the values its references need.

New to the canvas? Build a workflow first, then come back and put it in a repository.

What stays local Getting started