GITGUD

neiam neiam /home-assistant-plasmoid

Home Assistant Plasmoid

public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages

⭐

Log in to mark this repository.

actions

f546085 · gmorell · 2025-06-26 03:36

7 files +542 -0

Files changed

added .github/README.md
+172 −0
@@ -0,0 +1,172 @@
1 +# GitHub Actions for KDE Store Publishing
2 +
3 +This repository includes GitHub Actions workflows to automate the packaging and release process for your plasmoid, making it easier to publish to the KDE Store.
4 +
5 +## 🚀 Workflows
6 +
7 +### 1. Release Workflow (`.github/workflows/release.yml`)
8 +
9 +Automatically creates releases with packaged plasmoid files ready for KDE Store upload.
10 +
11 +**Triggers:**
12 +- **Git Tags:** Push a tag starting with `v` (e.g., `v2.1`, `v3.0`)
13 +- **Manual:** Use GitHub's "Actions" tab to manually trigger with custom version
14 +
15 +**What it does:**
16 +- Updates `metadata.json` with the new version number
17 +- Creates properly packaged `.tar.gz` and `.zip` files
18 +- Creates a GitHub release with download links
19 +- Provides step-by-step instructions for KDE Store upload
20 +
21 +### 2. Validation Workflow (`.github/workflows/validate.yml`)
22 +
23 +Validates your plasmoid structure and catches issues early.
24 +
25 +**Triggers:**
26 +- Push to main/master/develop branches
27 +- Pull requests
28 +
29 +**What it checks:**
30 +- Required files exist (`metadata.json`, `contents/ui/main.qml`)
31 +- `metadata.json` is valid JSON with required fields
32 +- QML syntax (basic check)
33 +- Package size and structure
34 +
35 +## 📦 How to Create a Release
36 +
37 +### Method 1: Git Tags (Recommended)
38 +
39 +```bash
40 +# Create and push a new tag
41 +git tag v2.1
42 +git push origin v2.1
43 +```
44 +
45 +The workflow will automatically:
46 +1. Create packages for version 2.1
47 +2. Update metadata.json
48 +3. Create a GitHub release
49 +4. Provide KDE Store upload instructions
50 +
51 +### Method 2: Manual Trigger
52 +
53 +1. Go to your repository on GitHub
54 +2. Click "Actions" tab
55 +3. Select "Create Plasmoid Release"
56 +4. Click "Run workflow"
57 +5. Enter the version number (e.g., `2.1`)
58 +6. Click "Run workflow"
59 +
60 +## 🏪 Publishing to KDE Store
61 +
62 +After the GitHub Action completes:
63 +
64 +1. **Download the package:** Go to the created GitHub release and download the `.tar.gz` file
65 +2. **Login to KDE Store:** Go to [store.kde.org](https://store.kde.org) and login
66 +3. **Navigate to your plasmoid:** Find your existing plasmoid page
67 +4. **Add new version:** Click "Add Version" or similar button
68 +5. **Upload package:** Upload the downloaded `.tar.gz` file
69 +6. **Update details:** Add changelog, update version number
70 +7. **Publish:** Submit for review/publish
71 +
72 +## 🧪 Local Testing
73 +
74 +Use the included `package.sh` script to test packaging locally:
75 +
76 +```bash
77 +# Create a development package
78 +./package.sh
79 +
80 +# Create a specific version package
81 +./package.sh 2.1
82 +```
83 +
84 +This creates the same packages that the GitHub Action would create.
85 +
86 +## 🔧 Configuration
87 +
88 +### Required Repository Settings
89 +
90 +No special configuration required! The workflows use the default `GITHUB_TOKEN` which is automatically available.
91 +
92 +### Optional Customizations
93 +
94 +You can customize the workflows by editing:
95 +
96 +- **Package name:** Change `home-assistant-plasmoid` in `release.yml`
97 +- **Excluded files:** Modify the `--exclude` patterns in both workflows
98 +- **Release notes:** Edit the template in `release.yml`
99 +
100 +### Version Management
101 +
102 +The workflow automatically:
103 +- Extracts version from git tags (removes `v` prefix)
104 +- Updates `metadata.json` with the new version
105 +- Uses the version in package filenames
106 +
107 +## 📋 Best Practices
108 +
109 +1. **Use semantic versioning:** `v1.0.0`, `v1.1.0`, `v2.0.0`
110 +2. **Test locally first:** Use `./package.sh` before creating releases
111 +3. **Write good commit messages:** They may be used in release notes
112 +4. **Update README:** Keep installation instructions current
113 +5. **Tag releases:** Always use git tags for version releases
114 +
115 +## 🐛 Troubleshooting
116 +
117 +### Workflow Fails
118 +
119 +Check the Actions tab for detailed logs. Common issues:
120 +
121 +- **Missing files:** Ensure `metadata.json` and `contents/ui/main.qml` exist
122 +- **Invalid JSON:** Validate `metadata.json` syntax
123 +- **Permission issues:** Usually resolve themselves, try re-running
124 +
125 +### Package Issues
126 +
127 +- **Too large:** Check for unnecessary files (logs, cache, etc.)
128 +- **Missing files:** Verify your `.gitignore` isn't excluding needed files
129 +- **Wrong structure:** Ensure the standard plasmoid directory structure
130 +
131 +### KDE Store Upload Issues
132 +
133 +- **Wrong format:** Use the `.tar.gz` file, not `.zip`
134 +- **Version conflicts:** Ensure the version number is unique
135 +- **Metadata mismatch:** Version in `metadata.json` should match store version
136 +
137 +## 🔄 Alternative: Fully Automated Publishing
138 +
139 +**Note:** The KDE Store doesn't provide an official API for automated publishing. However, there are experimental approaches:
140 +
141 +### Web Scraping Approach (Advanced)
142 +
143 +```yaml
144 +# This is experimental and not recommended for production
145 +- name: Auto-upload to KDE Store (EXPERIMENTAL)
146 + run: |
147 + # Would require:
148 + # - Storing KDE credentials securely
149 + # - Web scraping/automation tools
150 + # - Handling CSRF tokens and cookies
151 + # - High maintenance due to website changes
152 + echo "⚠️ Fully automated upload not implemented"
153 + echo "Manual upload to KDE Store still required"
154 +```
155 +
156 +### Why We Don't Recommend Full Automation
157 +
158 +1. **No official API:** KDE Store lacks automation-friendly APIs
159 +2. **Security concerns:** Storing credentials for web scraping
160 +3. **Fragility:** Website changes break automation
161 +4. **Terms of service:** May violate automated access policies
162 +
163 +The semi-automated approach (package creation + manual upload) provides the best balance of automation and reliability.
164 +
165 +## 📞 Support
166 +
167 +If you encounter issues:
168 +
169 +1. Check the GitHub Actions logs in your repository
170 +2. Validate your plasmoid structure locally with `./package.sh`
171 +3. Refer to [KDE Store documentation](https://store.kde.org)
172 +4. Check [KDE Community resources](https://community.kde.org)
added .github/workflows/release.yml
+122 −0
@@ -0,0 +1,122 @@
1 +name: Create Plasmoid Release
2 +
3 +on:
4 + push:
5 + tags:
6 + - 'v*'
7 + workflow_dispatch:
8 + inputs:
9 + version:
10 + description: 'Version number (e.g., 2.1)'
11 + required: true
12 + type: string
13 +
14 +jobs:
15 + create-release:
16 + runs-on: ubuntu-latest
17 +
18 + steps:
19 + - name: Checkout code
20 + uses: actions/checkout@v4
21 +
22 + - name: Set version
23 + id: version
24 + run: |
25 + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
26 + echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
27 + echo "tag=v${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
28 + else
29 + echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
30 + echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
31 + fi
32 +
33 + - name: Update metadata.json version
34 + run: |
35 + sed -i 's/"Version": "[^"]*"/"Version": "${{ steps.version.outputs.version }}"/' metadata.json
36 +
37 + - name: Create plasmoid package
38 + run: |
39 + # Create a temporary directory for packaging
40 + mkdir -p /tmp/plasmoid-package
41 +
42 + # Copy all necessary files (excluding git and temporary files)
43 + rsync -av --exclude='.git' --exclude='.github' --exclude='*.swp' --exclude='*~' . /tmp/plasmoid-package/
44 +
45 + # Create the plasmoid archive
46 + cd /tmp
47 + tar -czf home-assistant-plasmoid-${{ steps.version.outputs.version }}.tar.gz plasmoid-package/
48 +
49 + # Also create a zip file (alternative format)
50 + zip -r home-assistant-plasmoid-${{ steps.version.outputs.version }}.zip plasmoid-package/
51 +
52 + # Move packages to workspace
53 + mv home-assistant-plasmoid-${{ steps.version.outputs.version }}.tar.gz $GITHUB_WORKSPACE/
54 + mv home-assistant-plasmoid-${{ steps.version.outputs.version }}.zip $GITHUB_WORKSPACE/
55 +
56 + - name: Generate release notes
57 + id: release_notes
58 + run: |
59 + cat > release_notes.md << 'EOF'
60 + ## Home Assistant Control Plasmoid v${{ steps.version.outputs.version }}
61 +
62 + ### 📦 Installation
63 +
64 + **Automatic Installation (Recommended):**
65 + 1. Right-click on your desktop or panel
66 + 2. Select "Add Widgets..."
67 + 3. Click "Get New Widgets" → "Get New Widgets..."
68 + 4. Search for "Home Assistant Control"
69 + 5. Click "Install"
70 +
71 + **Manual Installation:**
72 + 1. Download the `.tar.gz` or `.zip` file from this release
73 + 2. Extract the archive
74 + 3. Run: `kpackagetool6 --type Plasma/Applet --install extracted-folder`
75 +
76 + ### 🔄 KDE Store Upload
77 +
78 + The packaged files are ready for upload to the KDE Store:
79 + - `home-assistant-plasmoid-${{ steps.version.outputs.version }}.tar.gz`
80 + - `home-assistant-plasmoid-${{ steps.version.outputs.version }}.zip`
81 +
82 + ### 📋 Changelog
83 +
84 + <!-- Add your changelog here -->
85 + - Bug fixes and improvements
86 +
87 + ### 🐛 Known Issues
88 +
89 + <!-- Add any known issues here -->
90 +
91 + ---
92 +
93 + **Repository:** https://github.com/neiam/home-assistant-plasmoid
94 + **KDE Store:** https://store.kde.org/p/XXXXXX (Update with your store URL)
95 + EOF
96 +
97 + - name: Create Release
98 + uses: softprops/action-gh-release@v1
99 + with:
100 + tag_name: ${{ steps.version.outputs.tag }}
101 + name: Home Assistant Control v${{ steps.version.outputs.version }}
102 + body_path: release_notes.md
103 + files: |
104 + home-assistant-plasmoid-${{ steps.version.outputs.version }}.tar.gz
105 + home-assistant-plasmoid-${{ steps.version.outputs.version }}.zip
106 + draft: false
107 + prerelease: false
108 + env:
109 + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
110 +
111 + - name: Upload to KDE Store Instructions
112 + run: |
113 + echo "🎉 Release created successfully!"
114 + echo ""
115 + echo "📤 To upload to KDE Store:"
116 + echo "1. Go to https://store.kde.org"
117 + echo "2. Log in with your KDE account"
118 + echo "3. Navigate to your plasmoid page"
119 + echo "4. Click 'Add Version'"
120 + echo "5. Upload: home-assistant-plasmoid-${{ steps.version.outputs.version }}.tar.gz"
121 + echo "6. Update version number to: ${{ steps.version.outputs.version }}"
122 + echo "7. Add changelog and publish"
added .github/workflows/validate.yml
+108 −0
@@ -0,0 +1,108 @@
1 +name: Validate Plasmoid
2 +
3 +on:
4 + push:
5 + branches: [ main, master, develop ]
6 + pull_request:
7 + branches: [ main, master, develop ]
8 +
9 +jobs:
10 + validate:
11 + runs-on: ubuntu-latest
12 +
13 + steps:
14 + - name: Checkout code
15 + uses: actions/checkout@v4
16 +
17 + - name: Validate plasmoid structure
18 + run: |
19 + echo "🔍 Validating plasmoid structure..."
20 +
21 + # Check required files
22 + required_files=("metadata.json" "contents/ui/main.qml")
23 + missing_files=()
24 +
25 + for file in "${required_files[@]}"; do
26 + if [[ ! -f "$file" ]]; then
27 + missing_files+=("$file")
28 + fi
29 + done
30 +
31 + if [[ ${#missing_files[@]} -gt 0 ]]; then
32 + echo "❌ Missing required files:"
33 + printf '%s\n' "${missing_files[@]}"
34 + exit 1
35 + fi
36 +
37 + echo "✅ All required files present"
38 +
39 + - name: Validate metadata.json
40 + run: |
41 + echo "🔍 Validating metadata.json..."
42 +
43 + # Check if metadata.json is valid JSON
44 + if ! jq empty metadata.json 2>/dev/null; then
45 + echo "❌ metadata.json is not valid JSON"
46 + exit 1
47 + fi
48 +
49 + # Check required fields
50 + required_fields=("KPlugin.Id" "KPlugin.Name" "KPlugin.Version" "KPlugin.Authors")
51 +
52 + for field in "${required_fields[@]}"; do
53 + if [[ $(jq -r ".$field // empty" metadata.json) == "" ]]; then
54 + echo "❌ Missing required field: $field"
55 + exit 1
56 + fi
57 + done
58 +
59 + echo "✅ metadata.json is valid"
60 +
61 + # Display current metadata
62 + echo "📋 Current metadata:"
63 + jq . metadata.json
64 +
65 + - name: Check QML syntax
66 + run: |
67 + echo "🔍 Checking QML files..."
68 +
69 + # Install Qt6 QML tools
70 + sudo apt-get update
71 + sudo apt-get install -y qt6-declarative-dev-tools
72 +
73 + # Find and check all QML files
74 + find . -name "*.qml" -type f | while read -r qml_file; do
75 + echo "Checking: $qml_file"
76 + if ! qmlls "$qml_file" 2>/dev/null; then
77 + echo "⚠️ QML syntax check failed for: $qml_file"
78 + # Don't fail the build for QML syntax issues as qmlls might not work perfectly in CI
79 + fi
80 + done
81 +
82 + echo "✅ QML syntax check completed"
83 +
84 + - name: Create test package
85 + run: |
86 + echo "📦 Creating test package..."
87 +
88 + # Create a temporary directory for packaging
89 + mkdir -p /tmp/test-package
90 +
91 + # Copy all necessary files
92 + rsync -av --exclude='.git' --exclude='.github' --exclude='*.swp' --exclude='*~' . /tmp/test-package/
93 +
94 + # Test packaging
95 + cd /tmp
96 + tar -czf test-plasmoid.tar.gz test-package/
97 +
98 + # Check package size (warn if > 10MB)
99 + size=$(stat -c%s test-plasmoid.tar.gz)
100 + size_mb=$((size / 1024 / 1024))
101 +
102 + echo "📏 Package size: ${size_mb}MB"
103 +
104 + if [[ $size_mb -gt 10 ]]; then
105 + echo "⚠️ Package is larger than 10MB. Consider optimizing."
106 + fi
107 +
108 + echo "✅ Test package created successfully"
added .gitignore
+54 −0
@@ -0,0 +1,54 @@
1 +# Build artifacts
2 +*.tar.gz
3 +*.zip
4 +home-assistant-plasmoid-*
5 +
6 +# Editor files
7 +*.swp
8 +*.kate-swp
9 +*~
10 +.vscode/
11 +.idea/
12 +
13 +# OS files
14 +.DS_Store
15 +Thumbs.db
16 +
17 +# Logs
18 +*.log
19 +
20 +# Temporary files
21 +tmp/
22 +temp/
23 +
24 +# Node.js (if using any JS build tools)
25 +node_modules/
26 +npm-debug.log*
27 +yarn-debug.log*
28 +yarn-error.log*
29 +
30 +# Python (if using any Python scripts)
31 +__pycache__/
32 +*.py[cod]
33 +*$py.class
34 +*.so
35 +.Python
36 +build/
37 +develop-eggs/
38 +dist/
39 +downloads/
40 +eggs/
41 +.eggs/
42 +lib/
43 +lib64/
44 +parts/
45 +sdist/
46 +var/
47 +wheels/
48 +*.egg-info/
49 +.installed.cfg
50 +*.egg
51 +
52 +# Local configuration files
53 +config.local.json
54 +settings.local.json
added package.sh
+86 −0
@@ -0,0 +1,86 @@
1 +#!/bin/bash
2 +
3 +# Local packaging script for Home Assistant Plasmoid
4 +# This script mirrors what the GitHub Action does for local testing
5 +
6 +set -e
7 +
8 +VERSION=${1:-"dev"}
9 +PACKAGE_NAME="home-assistant-plasmoid"
10 +
11 +echo "🚀 Packaging $PACKAGE_NAME version $VERSION"
12 +
13 +# Create temporary directory
14 +TEMP_DIR=$(mktemp -d)
15 +PACKAGE_DIR="$TEMP_DIR/$PACKAGE_NAME"
16 +
17 +echo "📁 Creating package directory: $PACKAGE_DIR"
18 +mkdir -p "$PACKAGE_DIR"
19 +
20 +# Copy files (excluding development files)
21 +echo "📋 Copying files..."
22 +rsync -av \
23 + --exclude='.git' \
24 + --exclude='.github' \
25 + --exclude='*.swp' \
26 + --exclude='*~' \
27 + --exclude='*.kate-swp' \
28 + --exclude='package.sh' \
29 + --exclude='node_modules' \
30 + --exclude='*.log' \
31 + . "$PACKAGE_DIR/"
32 +
33 +# Update version in metadata.json if not "dev"
34 +if [[ "$VERSION" != "dev" ]]; then
35 + echo "🔢 Updating version to $VERSION"
36 + sed -i "s/\"Version\": \"[^\"]*\"/\"Version\": \"$VERSION\"/" "$PACKAGE_DIR/metadata.json"
37 +fi
38 +
39 +# Create packages
40 +cd "$TEMP_DIR"
41 +
42 +echo "📦 Creating tar.gz package..."
43 +tar -czf "${PACKAGE_NAME}-${VERSION}.tar.gz" "$PACKAGE_NAME/"
44 +
45 +echo "📦 Creating zip package..."
46 +if command -v zip >/dev/null 2>&1; then
47 + zip -r "${PACKAGE_NAME}-${VERSION}.zip" "$PACKAGE_NAME/"
48 + CREATED_ZIP=true
49 +else
50 + echo "⚠️ zip command not found, skipping zip package creation"
51 + CREATED_ZIP=false
52 +fi
53 +
54 +# Move to current directory
55 +mv "${PACKAGE_NAME}-${VERSION}.tar.gz" "$OLDPWD/"
56 +if [[ "$CREATED_ZIP" == "true" ]]; then
57 + mv "${PACKAGE_NAME}-${VERSION}.zip" "$OLDPWD/"
58 +fi
59 +
60 +# Cleanup
61 +rm -rf "$TEMP_DIR"
62 +
63 +echo "✅ Packages created:"
64 +echo " - ${PACKAGE_NAME}-${VERSION}.tar.gz"
65 +if [[ "$CREATED_ZIP" == "true" ]]; then
66 + echo " - ${PACKAGE_NAME}-${VERSION}.zip"
67 +fi
68 +
69 +# Display package info
70 +echo ""
71 +echo "📊 Package information:"
72 +if [[ "$CREATED_ZIP" == "true" ]]; then
73 + ls -lh "${PACKAGE_NAME}-${VERSION}".{tar.gz,zip}
74 +else
75 + ls -lh "${PACKAGE_NAME}-${VERSION}.tar.gz"
76 +fi
77 +
78 +echo ""
79 +echo "🎯 Next steps:"
80 +echo "1. Test the package locally:"
81 +echo " kpackagetool6 --type Plasma/Applet --install ${PACKAGE_NAME}-${VERSION}.tar.gz"
82 +echo ""
83 +echo "2. Upload to KDE Store:"
84 +echo " - Go to https://store.kde.org"
85 +echo " - Navigate to your plasmoid page"
86 +echo " - Add new version and upload ${PACKAGE_NAME}-${VERSION}.tar.gz"

Parents: 13e402a