Files workspace

The files workspace is the panel on the right side of the Runbooks window, labeled Files. It shows two types of files:

• Generated files are new files the runbook creates. Use them when the user will do something with the files outside the runbook, such as copying them into another project.
• Repository files are a git repository the runbook cloned. Use them when later blocks create, modify, or delete files in that repo, usually before pushing the changes or opening a pull request.

Tip

A runbook that only generates files shows only the Generated files tab. A runbook that only clones a repository shows only the Repository tab. When both are present, switch between them with the tabs at the top of the workspace.

Generated files

There are two ways a runbook generates files. The workspace opens automatically when either one produces a file.

Template blocks

The Template and TemplateInline blocks generate files from Boilerplate templates. When you fill in the form fields and click “Generate”, the template engine renders the output files. The default target is "generated".

<Template id="vpc-setup" path="templates/vpc" />

Template blocks re-render when you change input values, so the generated files match the form.

Command and Check blocks with $GENERATED_FILES

Scripts run by Command and Check blocks can write files to the directory named by the $GENERATED_FILES environment variable:

<Command
  id="export-tofu"
  command={`tofu output -json > "$GENERATED_FILES/tofu-outputs.json"`}
  title="Export OpenTofu outputs"
/>

Files written to $GENERATED_FILES appear in the workspace when the script exits with code 0 or 2.

Where generated files are stored

Runbooks writes generated files to a generated/ folder inside the folder that contains the runbook file. Template blocks and $GENERATED_FILES captures both write there, even after a script has cd’d somewhere else:

• Directorymy-runbook/

  • runbook.mdx
  • Directorygenerated/ created next to your runbook

    • main.tf
    • variables.tf
    • outputs.tf

For a remote runbook, the runbook’s folder is inside a temporary clone, so its generated files are deleted when you quit Runbooks.

Subdirectories

A script that writes to a subdirectory of $GENERATED_FILES creates the subdirectory itself:

mkdir -p "$GENERATED_FILES/config"
echo '{}' > "$GENERATED_FILES/config/app.json"

• Directorygenerated

  • Directoryconfig/

    • app.json
  • main.tf
  • variables.tf
  • outputs.tf

Repository files

Repository files come from a git repository that a GitClone block cloned. When the clone completes, the workspace switches to the Repository tab.

The clone is stored at the local path set in the GitClone block, relative to the working directory. The working directory starts as the folder that contains runbook.mdx, and it follows any cd that an earlier script made.

Later changes to the repository come from a Template block that sets target="worktree", or from Command and Check scripts that write to the directory named by $REPO_FILES.

The Repository tab has two sub-tabs.

All files

The All files tab shows the complete file tree of the cloned repository. Click any file to view its contents with syntax highlighting.

Changed files

The Changed files tab shows a diff of the files that changed since the repository was cloned:

• Which files were added, modified, or deleted
• Line-by-line additions and deletions
• A summary of total changes at the top

Note

The Changed files tab appears the first time Runbooks detects a change.

Multiple repositories

If a runbook clones more than one repository, a dropdown at the top of the Repository tab replaces the repository and branch name and switches between them.

Where Runbooks reads and writes files

Runbooks checks each path a block asks it to read or write. It resolves symlinks first, then allows the path only when it is inside one of these:

• the working directory
• the folder that contains the runbook
• a repository registered by a GitClone block

This covers the template folder a Template block reads, the folder Template and TemplateInline blocks write to, and the file tree, file contents, and git changes shown in the workspace. A symlink inside an allowed folder that points outside it is rejected.

A GitClone destination has a stricter rule, because cloning can delete what is already there. It must be a subdirectory of the working directory, and it must not contain the open runbook.

Note

These checks apply to paths that blocks pass to Runbooks. Scripts run by Command and Check blocks have full filesystem access and can write anywhere the user has permissions.

Next

Next, read about the use cases for Runbooks.