Git Storage

Store deployment scripts in version-controlled Git repositories.

Overview

Git storage clones repositories and reads scripts from the local clone:

When to Use Git Storage

Use Case	Recommendation
Version control	Track all script changes
GitOps workflows	PR-based review processes
Audit trails	Git history for compliance
Team collaboration	Multiple contributors
Branch strategies	Different scripts per environment

Configuration

Properties

Property	Required	Description
Name	Yes	Unique identifier for the storage
URL	Yes	Git repository URL
Reference	Yes	Branch, tag, or commit to checkout
Path	Yes	Local path for cloned repository
Authentication	No	Credentials for private repositories

Creating Git Storage

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Create Git Storage                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name *                                                     │
│  [deployment-scripts                       ]                │
│                                                             │
│  Repository URL *                                           │
│  [https://github.com/org/scripts.git       ]                │
│                                                             │
│  Reference *                                                │
│  [main                                     ]                │
│  Branch, tag, or commit SHA                                 │
│                                                             │
│  Local Path *                                               │
│  [/var/mantis/cache/scripts                ]                │
│  Where to clone the repository                              │
│                                                             │
│  Authentication                                             │
│  [github-deploy-key               ▼]                        │
│  Select authentication method                               │
│                                                             │
│                                     [Cancel]  [Create]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1. Navigate to Storage in the sidebar (under Infrastructure)
2. Click New Storage
3. Click the Git Storage tab
4. Enter repository details
5. Select authentication method
6. Click Create

Via REST API

Git storage is created through POST /api/v1/storage/git. The reference field takes a branch, tag, or commit, and auth_id references a git auth credential (see Authentication).

# Create git storage with SSH key auth
curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "deployment-scripts",
    "url": "git@github.com:org/scripts.git",
    "reference": "main",
    "path": "/var/mantis/cache/scripts",
    "auth_id": "<github-ssh-auth-id>"
  }'

# Create with a specific tag
curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "versioned-scripts",
    "url": "https://github.com/org/scripts.git",
    "reference": "v1.2.3",
    "path": "/var/mantis/cache/versioned"
  }'

Repository Structure

Recommended Layout

deployment-scripts/
├── README.md
├── deploy/
│   ├── web-app.sh
│   ├── api-service.sh
│   └── database.sh
├── configure/
│   ├── nginx.conf.sh
│   └── ssl-setup.sh
├── health/
│   ├── check-web.sh
│   └── check-db.sh
└── rollback/
    └── restore.sh

Referencing Scripts

Reference scripts relative to repository root:

Repository	Filename	File Location
scripts.git	deploy/web-app.sh	repo/deploy/web-app.sh
scripts.git	configure/nginx.conf.sh	repo/configure/nginx.conf.sh

Detail View

┌─────────────────────────────────────────────────────────────┐
│  Git Storage: deployment-scripts                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Type: Git                                                  │
│  URL: git@github.com:org/scripts.git                        │
│  Reference: main                                            │
│  Local Path: /var/mantis/cache/scripts                      │
│  Auth: github-deploy-key                                    │
│  Created: January 15, 2024                                  │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Last Fetched: 5 minutes ago                                │
│                                                             │
│                                        [Edit] [Delete]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Fetch Behavior

The git repository is synced on every read. File content is cached by commit hash, so the cache invalidates automatically whenever the repository’s HEAD commit changes — the first read after a new commit re-fetches, and subsequent reads of the same commit are served from cache. There is no time-based cache expiry to configure and no manual “refresh” action.

Branch Strategies

Environment-Based Branches

Use different branches for different environments:

Repository: scripts.git
├── main          # Production scripts
├── staging       # Staging scripts
└── development   # Development scripts

Create a separate storage source per branch by setting reference accordingly ("main", "staging", "development"):

curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "scripts-prod",
    "url": "git@github.com:org/scripts.git",
    "path": "/var/mantis/cache/scripts-prod",
    "reference": "main"
  }'

Tag-Based Versioning

Use tags for immutable versions by setting reference to a tag:

{
  "name": "scripts-v1",
  "url": "git@github.com:org/scripts.git",
  "path": "...",
  "reference": "v1.2.3",
}

Commit SHA Pinning

Pin to a specific commit for reproducibility by setting reference to a SHA:

{
  "name": "scripts-pinned",
  "url": "git@github.com:org/scripts.git",
  "path": "...",
  "reference": "abc123def456789",
}

Authentication Methods

Git storage supports multiple authentication methods. See Authentication for detailed setup.

Quick Reference

Method	Use Case	URL Format
SSH Key	Deploy keys, personal access	git@github.com:org/repo.git
HTTPS + Token	GitHub/GitLab tokens	https://github.com/org/repo.git
HTTPS + Password	Basic auth (deprecated)	https://github.com/org/repo.git

Example: SSH Key Authentication

# Create an SSH git auth credential
curl -X POST "$MANTIS_URL/api/v1/storage/git/auth" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"name\": \"github-deploy-key\",
    \"auth_type\": \"ssh_key\",
    \"ssh_private_key\": \"$(cat ~/.ssh/deploy_key)\"
  }"

# Reference its returned id (auth_id) when creating git storage
curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "scripts",
    "url": "git@github.com:org/scripts.git",
    "path": "/var/mantis/cache/scripts",
    "reference": "main",
    "auth_id": "<github-deploy-key-auth-id>"
  }'

GitOps Workflow

PR-Based Changes

Workflow Steps

1. Branch: Create feature branch for changes
2. Commit: Add script changes
3. Review: Create PR for team review
4. Merge: Merge to target branch after approval
5. Deploy: Mantis fetches and uses updated scripts

Tip

Use protected branches in your Git provider to require reviews before merging.

Multi-Repository Setup

Different Repos for Different Purposes

Create a separate git storage source per repository (each needs a path and reference):

{ "name": "app-deploy",   "url": "git@github.com:org/app-scripts.git",  "path": "/var/mantis/cache/app-deploy",   "reference": "main" }
{ "name": "infra-config", "url": "git@github.com:org/infra-config.git", "path": "/var/mantis/cache/infra-config", "reference": "main" }
{ "name": "shared-utils", "url": "git@github.com:org/shared-scripts.git","path": "/var/mantis/cache/shared-utils", "reference": "main" }

Monorepo Subdirectories

For monorepos, scripts can be in subdirectories:

monorepo/
├── src/
├── docs/
└── deploy/
    └── scripts/
        ├── web.sh
        └── api.sh

When creating an action against this storage source (in Lens, or via the Actions API), set the action’s filename to include the subdirectory path, e.g. deploy/scripts/web.sh. See Creating Actions.

Best Practices

1. Use Deploy Keys

For production, use repository-specific deploy keys:

Approach	Security	Recommendation
Deploy keys	High	Recommended for production
Personal tokens	Medium	OK for development
User passwords	Low	Avoid

2. Pin to Tags in Production

Use immutable tags for production deployments:

// Good: pin reference to an immutable tag
{ "name": "prod-scripts", "reference": "v2.1.0", "url": "...", "path": "..." }

// Avoid: a mutable branch in production (can change unexpectedly)
{ "name": "prod-scripts", "reference": "main", "url": "...", "path": "..." }

3. Include README

Document your scripts repository:

# Deployment Scripts

## Structure

- `deploy/` - Deployment scripts
- `configure/` - Configuration scripts
- `health/` - Health check scripts

## Usage

Scripts are used by Mantis for automated deployments.

## Contributing

1. Create feature branch
2. Make changes
3. Submit PR for review

4. Test Before Merge

Validate scripts before merging:

.github/workflows/validate.yml

on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Lint scripts
        run: shellcheck deploy/*.sh

Troubleshooting

”Repository not found”

Cause: Wrong URL or missing access

Solution:

1. Verify repository URL is correct
2. Check authentication is configured
3. Ensure deploy key has read access

”Reference not found”

Cause: Branch/tag doesn’t exist

Solution:

1. Verify branch or tag name
2. Check if reference was deleted
3. Update storage with correct reference

”Authentication failed”

Cause: Invalid or expired credentials

Solution:

1. Regenerate SSH key or token
2. Update authentication in Mantis
3. Verify key is added to Git provider

Clone Taking Too Long

Cause: Large repository or slow network

Solution:

1. Consider repository size reduction
2. Check network connectivity

Next Steps

• S3 Storage - Cloud artifact storage
• Authentication - Configure credentials
• Overview - Return to storage overview