Repositories

Create and manage Git repositories for versioned storage of workflows, prompts, agents, and configurations.

Overview

Repositories in M3 Forge are Gitea-hosted Git repositories accessed through an integrated browser and code editor. They provide version control for all AI artifacts with full Git capabilities including branching, committing, merging, and history tracking.

Creating a Repository

Repository Browser

The integrated repository browser provides a file tree interface for navigating repository contents.

File Tree

The left sidebar shows the repository structure:

• Directories expand/collapse to reveal contents
• Files display with icons based on type (JSON, YAML, etc.)
• Current branch displayed at the top
• Commit count shows total commits

Click any file to open it in the code editor.

Code Editor

The built-in code editor supports:

• Syntax highlighting for JSON, YAML, JavaScript, Python, Markdown
• Line numbers for easy reference
• Search and replace within file
• Multi-file editing via tabs
• Auto-save option to prevent lost work

Edit files directly in the browser without cloning the repository locally.

Committing Changes

After editing files, commit your changes to the repository:

Add fraud detection workflow

Implements real-time transaction analysis with rule-based
and ML-based fraud scoring. Includes HITL review step for
high-risk transactions.

Branching

Branches enable isolated development without affecting the main codebase.

Create a Branch

From the branch dropdown:

1. Click New Branch
2. Enter branch name (e.g., feature/add-rag-pipeline)
3. Select base branch (usually main)
4. Click Create

The new branch is immediately active in the editor.

Branch Naming Conventions

Switch Branches

Use the branch dropdown to switch between branches. Uncommitted changes will be lost unless committed first.

Delete a Branch

After merging, delete feature branches to keep the repository clean:

1. Switch to a different branch
2. Open branch dropdown
3. Click delete icon next to branch name
4. Confirm deletion

Viewing History

The History tab shows all commits in reverse chronological order.

Commit List

Each commit displays:

• Commit message — First line of commit description
• Author — Who made the change
• Timestamp — When the commit was created
• Commit hash — Short SHA identifier

Click any commit to view its diff.

Commit Diff

The diff view shows:

• Changed files — List of modified, added, deleted files
• Line-by-line changes — Side-by-side or unified diff
• Green lines — Additions
• Red lines — Deletions

Use this to review exactly what changed in each commit.

File Operations

The repository browser supports standard file operations:

Create File

1. Right-click directory in file tree
2. Select New File
3. Enter filename with extension
4. Click Create

The new file opens in the editor.

Upload File

Drag and drop files from your desktop into the file tree, or use the Upload button.

Supported formats:

• JSON (workflows, query plans, configurations)
• YAML (prompts, agents)
• Markdown (documentation)
• Any text-based format

Rename File

1. Right-click file
2. Select Rename
3. Enter new name
4. Commit the change

Git tracks renames as a delete + add operation.

Delete File

1. Right-click file
2. Select Delete
3. Confirm deletion
4. Commit the change

Deleted files remain in Git history and can be recovered from previous commits.

Repository Settings

Access repository settings via the Settings button:

General

• Repository name — Read-only after creation
• Description — Update anytime
• Visibility — Change between public and private
• Default branch — Set which branch is primary (usually main)

Collaborators

Add team members with specific permissions:

• Read — View files and history only
• Write — Commit changes and create branches
• Admin — Full repository access including settings

Webhooks

Configure webhooks to trigger external systems on repository events:

• Push events — Notify on new commits
• Pull request events — Notify on PR creation/merge
• Tag events — Notify on version tags

Useful for CI/CD integration and automated deployment triggers.

Working with Workflows

Workflows are stored as JSON files in the repository. The repository browser provides specialized handling:

Import Workflow from Repository

From the Workflows page:

1. Click Import from Repository
2. Select repository and branch
3. Choose workflow JSON file
4. Click Import

The workflow is loaded into the visual editor.

Export Workflow to Repository

From the workflow editor:

1. Click Save to Repository
2. Select target repository and branch
3. Enter commit message
4. Click Commit

The workflow DAG JSON is written to the repository and committed.

Working with Prompts

Prompts are stored as YAML files with frontmatter metadata.

Prompt File Format

---
name: "Extract Invoice Data"
model: "gpt-4o"
temperature: 0.0
max_tokens: 2000
---
Extract structured data from the following invoice:
 
{{ invoice_text }}
 
Return JSON with these fields:
- invoice_number
- date
- vendor
- total_amount
- line_items (array)

Edit Prompts in Repository

Navigate to prompts/<name>.yaml and edit directly in the code editor. Commit changes to version the prompt.

Import from Prompt Repository

From the Prompts page:

1. Click Import from Repository
2. Select repository containing prompt YAML
3. Choose prompt file
4. Click Import

The prompt loads into the prompt editor for testing and refinement.

Best Practices

Commit Often

Create small, focused commits rather than large batch commits. Benefits:

• Easier review — Reviewers can understand each change quickly
• Better history — Clear progression of work
• Simpler rollback — Undo specific changes without losing unrelated work

Write Descriptive Messages

Commit messages should explain why a change was made, not just what changed. The diff already shows what changed.

Poor:

Update workflow

Good:

Add retry logic to API call node

Prevents workflow failures when external API returns transient
errors. Implements exponential backoff with max 3 retries.

Use Branches for Features

Never commit experimental or unfinished work directly to main. Use feature branches:

1. Create branch for feature
2. Commit changes iteratively
3. Open pull request when ready
4. Merge after review

This keeps main stable and deployable at all times.

Tag Releases

When deploying to production, create a Git tag marking the release:

v1.2.0

Tags provide named snapshots that can be referenced later for rollback or audit purposes.

Integration with Release Pipeline

The Release Pipeline uses repository commits as the foundation for versioning:

1. Commit changes to a branch
2. Create pull request for review
3. Merge to main after approval
4. Create version from merged commits
5. Deploy version to target environment

See Releases and Environments for the complete deployment workflow.

Troubleshooting

Changes Not Appearing

Cause: Uncommitted changes are not persisted.

Solution: Always commit changes before closing the editor or switching branches.

Merge Conflicts

Cause: Two branches modified the same lines of a file.

Solution: Resolve conflicts manually in the code editor, then commit the resolution.

Lost Commits

Cause: Committed to wrong branch or deleted branch before merging.

Solution: Use Git reflog in Gitea UI to find lost commits. Contact administrator if needed.

Permission Denied

Cause: User lacks write access to repository.

Solution: Repository admin must grant write permissions via Settings → Collaborators.

Next Steps

• Create your first pull request
• Learn about change sets
• Set up Gitea integration
• Integrate with Release Pipeline