# Workspaces and git

> Running and debugging · https://spoletta.com/docs/workspaces

A flow that works on code lists its repositories. Each run's agents and scripts then work in a workspace: a checkout of each repository, all on a git branch of the run's own, so runs never step on each other.

## Adding repositories

1.  **Open the flow's settings**
    
    Press **Settings** in the board's toolbar.
    
2.  **Add a repository**
    
    Under **Repositories**, choose the host: **GitHub** takes `org/repository`, **Other** takes an https URL. Optionally give a **Base branch** to start from. Each listed repository has **Remove**.
    
3.  **Set a branch prefix (optional)**
    
    **Branch prefix** names the branches runs make. It applies to runs started from then on.
    

## Branches

Every run works on a branch of its own, named after the prefix and the run:

The branch of run 41, with the branch prefix spoletta/sentry:

```text
spoletta/sentry/run-41
```

-   Every process of a run works on the **same branch** and picks up where the one before left off: the agent that fixes a bug and the one that opens the pull request see the same checkout.
-   When a flow process runs once per item of a list, **each item gets its own branch**, so items running at once don't meet.
-   A re-run gets a branch of its own, starting from where the original was when its process started. See [Re-runs and follow-ups](https://spoletta.com/docs/reruns.md).

## Commits

Whatever a step leaves uncommitted is committed for it, with the run, the step and the agent's session recorded in the commit. Each step in the run panel shows *Worked on the branch*, the commits it made per repository, from one commit to another, and whether it left changes uncommitted. Pushing and opening a pull request is up to the flow: an agent asked to “push the branch and open a pull request” does so.

Once a run is over, its checkouts are released, but the branches and agent sessions are kept, so a follow-up message or a re-run makes them again from the branch.

## Which steps get a checkout

| Setting | Effect |
| --- | --- |
| Every repository of the flow | The default for an agent or script: it works in all of them. |
| Some repositories picked | It works only in those. |
| None picked | It gets no checkout, written `repositories: []` in a setup file. Use it for agents that only post to Slack or comment on an issue. |

In a script, `$WORKSPACE` is the directory holding a checkout of each repository, named as the repository is, and `$BRANCH` is the run's branch.

> **Procedures have their own:** A procedure runs as a run of its own, with its own repositories, in its own workspace on its own branch. It can't carry on the caller's checkout. Push or finish code work in the caller, and give the procedure only what needs no checkout. See [Procedures](https://spoletta.com/docs/procedures.md).