259 lines
5.4 KiB
Markdown
259 lines
5.4 KiB
Markdown
# 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
|
|
```bash
|
|
attune pack install <git-url> [--ref <branch|tag|commit>] [options]
|
|
```
|
|
|
|
### API
|
|
```bash
|
|
POST /api/v1/packs/install
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Examples
|
|
|
|
### Public GitHub Repository
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
# Install specific stable version
|
|
attune pack install https://github.com/myorg/pack-prod.git --ref v1.0.0
|
|
```
|
|
|
|
### Development Testing
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`
|