re-uploading work
This commit is contained in:
258
docs/packs/QUICKREF-git-installation.md
Normal file
258
docs/packs/QUICKREF-git-installation.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user