Skip to content

Keep a board in sync with Git

A board can be connected to a branch and a folder of its repository. Studio then commits the board’s Screenplay files there. The model lives next to the code it describes, and every change to it has a history.

  • The project has a repository connected. See Connect a repository.
  • Git sync works through the GitHub App installation of your organization (see Connect GitHub). Studio stores no Git credentials for it.
The Export submenu of Project options listing Screenplay file, Screenplay folder, Mermaid, Event Modeling JSON, Context for an agent, Share snapshot link, Keep in sync with Git and Draw on Miro
Keep in sync with Git is in the Export submenu.
  1. On the event model board, open Project options, then Export, and choose Keep in sync with Git.

  2. In Keep the board in sync with Git, choose the Branch.

  3. Enter the Folder inside the repository, such as model. The contents of the folder are replaced by the board’s files, so use a folder that holds nothing else.

  4. Turn on Offer changes pushed to these files for import into the board if people may also edit the files in the repository and you want those edits offered back to the board.

  5. Select Keep in sync.

The Keep the board in sync with Git dialog with Branch set to main, Folder set to model, the option Offer changes pushed to these files for import into the board ticked, and the Keep in sync and Close buttons
Fill in Branch and Folder, decide on the import option, then select Keep in sync. The dialog warns that the contents of the folder are replaced by the board's files.

The dialog then shows Synced to the folder and branch, whether repository changes are offered for import, and the time and commit of the last sync.

The folder holds what the Screenplay export gives you: the .play documents, the screens’ sketches, mockups and images, and a .screenplay/notes.json file with the slices’ issue links. Images are committed byte for byte. Each commit message names the board and lists the files added, changed and removed.

Studio waits until the board has been quiet for a while before it commits, so a modeling session becomes a few commits instead of one per change. By default that is about a minute without changes. A board that keeps changing is committed anyway after at most ten minutes.

The dialog says where the sync stands:

Status What it means
In sync with the repository at a commit The repository holds the board as it is.
Waiting for the board to settle before the next commit. The board changed recently. Studio commits when it goes quiet.
Someone changed the board’s files in the repository. Studio has not committed since. See the next section.
Both the board and its files in the repository changed. Studio has not overwritten either.
The last sync failed with a reason Fix what the reason says, and Studio tries again.

Studio never overwrites a change it has not seen. When the folder changed in the repository since Studio’s last commit, Studio stops committing and the dialog lists Files that differ. Choose one of two ways forward:

  • Import the repository’s version. It goes through the usual import preview, and brings the sketches, mockups, images and issue links in the folder back with it.
  • Commit Studio’s version on top. The repository’s change stays in the history, but the files in the folder become the board’s. Studio asks you to confirm first.

When Offer changes pushed to these files for import into the board is on, a repository change that has no matching board change is offered for import. When both changed, the conflict is reported and neither side is overwritten.

Select Stop syncing in the dialog and confirm. Studio stops committing the board. Nothing already committed is removed.