attune/docs/packs/QUICKREF-git-installation.md

Git Pack Installation - Quick Reference

Quick commands and examples for installing packs from git repositories

---

Installation Methods

Web UI

Packs → Add Pack ▼ → Install from Remote → Git Repository

CLI

attune pack install <git-url> [--ref <branch|tag|commit>] [options]

API

POST /api/v1/packs/install

---

Quick Examples

Public GitHub Repository

# Latest from default branch
attune pack install https://github.com/example/pack-slack.git

# Specific version tag
attune pack install https://github.com/example/pack-slack.git --ref v2.1.0

# Specific branch
attune pack install https://github.com/example/pack-slack.git --ref develop

# Specific commit
attune pack install https://github.com/example/pack-slack.git --ref a1b2c3d

Private Repository (SSH)

# SSH URL with tag
attune pack install git@github.com:myorg/private-pack.git --ref v1.0.0

# SSH URL with branch
attune pack install git@github.com:myorg/private-pack.git --ref main

Installation Options

# Force reinstall (replace existing)
attune pack install <url> --force

# Skip tests
attune pack install <url> --skip-tests

# Skip dependency validation
attune pack install <url> --skip-deps

# All options combined
attune pack install <url> --ref v1.0.0 --force --skip-tests --skip-deps

---

Git URL Formats

HTTPS

✓ https://github.com/username/pack-name.git
✓ https://gitlab.com/username/pack-name.git
✓ https://bitbucket.org/username/pack-name.git
✓ https://git.example.com/username/pack-name.git

SSH

✓ git@github.com:username/pack-name.git
✓ git@gitlab.com:username/pack-name.git
✓ user@server:path/to/pack.git

---

Git References

Type	Example	Description
Tag	v1.2.3	Semantic version tag
Tag	release-2024-01-27	Release tag
Branch	main	Main branch
Branch	develop	Development branch
Branch	feature/xyz	Feature branch
Commit	a1b2c3d4e5f6...	Full commit hash
Commit	a1b2c3d	Short commit hash (7+ chars)
None	(omit --ref)	Default branch (shallow)

---

Installation Flags

Flag	Effect	Use When
--force	Replace existing pack, bypass checks	Upgrading, testing
--skip-tests	Don't run pack tests	Tests slow/unavailable
--skip-deps	Don't validate dependencies	Custom environment

⚠️ Warning: Use flags cautiously in production!

---

Required Pack Structure

repository/
├── pack.yaml          ← Required
├── actions/           ← Optional
├── sensors/           ← Optional
└── ...

OR

repository/
└── pack/
    ├── pack.yaml      ← Required
    └── ...

---

API Request

curl -X POST http://localhost:8080/api/v1/packs/install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://github.com/example/pack-slack.git",
    "ref_spec": "v2.1.0",
    "force": false,
    "skip_tests": false,
    "skip_deps": false
  }'

---

Common Workflows

Production Install

# Install specific stable version
attune pack install https://github.com/myorg/pack-prod.git --ref v1.0.0

Development Testing

# Install from feature branch, skip checks
attune pack install https://github.com/myorg/pack-dev.git \
  --ref feature/new-action \
  --force \
  --skip-tests

CI/CD Pipeline

# Install from current commit
attune pack install https://github.com/$REPO.git \
  --ref $COMMIT_SHA \
  --force

---

Troubleshooting

Error	Solution
Permission denied	Check SSH keys or HTTPS credentials
Ref not found	Verify branch/tag exists and is pushed
pack.yaml not found	Ensure file exists at root or in pack/
Dependencies missing	Install dependencies or use --skip-deps
Tests failed	Fix tests or use --skip-tests or --force

---

Security Best Practices

✓ DO:

• Use specific tags in production (v1.2.3)
• Use SSH keys for private repos
• Review code before installing
• Rotate access tokens regularly

✗ DON'T:

• Embed credentials in URLs
• Install from main branch in production
• Skip validation without review
• Use force mode carelessly

---

Web UI Workflow

1. Navigate to Packs page
2. Click Add Pack dropdown button
3. Select Install from Remote
4. Choose Git Repository source type
5. Enter repository URL
6. (Optional) Enter git reference
7. (Optional) Configure installation options
8. Click Install Pack
9. Wait for completion and redirect

---

Quick Tips

💡 Version Control: Always use tags for production (e.g., v1.0.0)

💡 Testing: Test from feature branch first, then install from tag

💡 SSH Setup: Configure SSH keys once, use forever

💡 Shallow Clone: Omit ref for faster install (default branch only)

💡 Commit Hash: Most specific reference, guaranteed reproducibility

---

Related Commands

# List installed packs
attune pack list

# View pack details
attune pack show <pack-ref>

# Run pack tests
attune pack test <pack-ref>

# Uninstall pack
attune pack uninstall <pack-ref>

---

More Information

📖 Full documentation: docs/packs/pack-installation-git.md 📖 Pack structure: docs/packs/pack-structure.md 📖 Pack registry spec: docs/packs/pack-registry-spec.md