klauvsteinen/unifi-network-operator
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
599bf7c3a91947eba225f0b031e29abf9e9f0e50
unifi-network-operator/GITHUB_SETUP_SUMMARY.md

8.3 KiB
Raw Blame History

GitHub Setup Summary - UniFi Network Operator

✅ What Has Been Completed

1. Repository Structure

  • ✅ Repository pushed to GitHub: vegardengen/unifi-network-operator
  • ✅ Remote github configured
  • ✅ Main branch pushed
  • ✅ Feature branch feature/add-helm pushed with Helm chart and CI/CD
  • ✅ All 39 version tags pushed

2. Helm Chart Created

  • ✅ Complete Helm chart in helm/unifi-network-operator/
  • ✅ All CRDs included
  • ✅ Comprehensive values.yaml with 50+ configuration options
  • ✅ Updated to use GitHub URLs and ghcr.io images
  • ✅ Full documentation and README

3. CI/CD Workflows Created

  • ✅ docker-build-push.yaml - Builds multi-arch images (amd64, arm64)
  • ✅ helm-release.yaml - Publishes Helm charts to GitHub Pages
  • ✅ release.yaml - Complete release automation
  • ✅ pr-validation.yaml - PR checks and validation
  • ✅ Chart Releaser configuration
  • ✅ Comprehensive documentation

4. Documentation Created

  • ✅ .github/README.md - Workflow documentation
  • ✅ .github/SETUP.md - Step-by-step setup guide
  • ✅ CICD.md - Complete CI/CD pipeline docs
  • ✅ helm/README.md - Helm chart overview
  • ✅ helm/INSTALL.md - Installation guide
  • ✅ helm/unifi-network-operator/README.md - Chart documentation

🚀 Next Steps (Required)

Step 1: Enable GitHub Pages (Required for Helm Repository)

  1. Go to https://github.com/vegardengen/unifi-network-operator/settings/pages
  2. Under "Build and deployment":
    • Source: Deploy from a branch
    • Branch: gh-pages / / (root)
    • Click Save

Note: The gh-pages branch will be automatically created by the workflow on first run.

Step 2: Configure Workflow Permissions (Required)

  1. Go to https://github.com/vegardengen/unifi-network-operator/settings/actions
  2. Scroll to "Workflow permissions"
  3. Select Read and write permissions
  4. Check ✅ Allow GitHub Actions to create and approve pull requests
  5. Click Save

Step 3: Make Container Images Public (Do After First Build)

  1. After first workflow run, go to https://github.com/vegardengen?tab=packages
  2. Find unifi-network-operator
  3. Click on it → Package settings
  4. Scroll to "Danger Zone"
  5. Click Change visibility → Public
  6. Type package name to confirm

Step 4: Merge the Helm Chart PR

  1. Create PR: https://github.com/vegardengen/unifi-network-operator/pull/new/feature/add-helm
  2. Review changes
  3. Merge to main

This will trigger:

  • Docker image build
  • Helm chart release
  • Publication to GitHub Pages

Step 5: Create Your First Release

Once Steps 1-4 are complete:

# Make sure you're on main and up to date
git checkout main
git pull github main

# Create a release tag
git tag -a v0.1.0 -m "Initial release with Helm chart and CI/CD"

# Push the tag
git push github v0.1.0

This will automatically:

  1. Build and push Docker images (linux/amd64, linux/arm64)
  2. Package and release Helm chart
  3. Create GitHub release with notes
  4. Publish to Helm repository

📦 What Will Be Available

Docker Images

Location: ghcr.io/vegardengen/unifi-network-operator

Usage:

docker pull ghcr.io/vegardengen/unifi-network-operator:latest
docker pull ghcr.io/vegardengen/unifi-network-operator:v0.1.0

Platforms: linux/amd64, linux/arm64

Helm Repository

Location: https://vegardengen.github.io/unifi-network-operator

Usage:

# Add repository
helm repo add unifi-network-operator https://vegardengen.github.io/unifi-network-operator

# Update
helm repo update

# Install
helm install unifi-network-operator unifi-network-operator/unifi-network-operator \
  --namespace unifi-network-operator-system \
  --create-namespace \
  --set unifi.url="https://your-unifi-controller:8443" \
  --set unifi.password="your-password"

🔍 How to Verify Everything Works

Check Workflow Status

  1. Go to https://github.com/vegardengen/unifi-network-operator/actions
  2. Verify workflows are running/passing

Test Docker Image Pull

# After first successful build
docker pull ghcr.io/vegardengen/unifi-network-operator:main

Test Helm Repository

# After first helm release
helm repo add unifi-network-operator https://vegardengen.github.io/unifi-network-operator
helm repo update
helm search repo unifi-network-operator

📊 Repository URLs

Resource URL
GitHub Repository https://github.com/vegardengen/unifi-network-operator
Actions (Workflows) https://github.com/vegardengen/unifi-network-operator/actions
Releases https://github.com/vegardengen/unifi-network-operator/releases
Packages https://github.com/vegardengen/unifi-network-operator/pkgs/container/unifi-network-operator
Helm Repository https://vegardengen.github.io/unifi-network-operator
Create PR https://github.com/vegardengen/unifi-network-operator/pull/new/feature/add-helm

📚 Documentation References

Document Location Purpose
CI/CD Overview CICD.md Complete CI/CD pipeline documentation
Workflow Details .github/README.md Detailed workflow documentation
Setup Guide .github/SETUP.md Step-by-step setup instructions
Helm Overview helm/README.md Helm chart overview
Installation Guide helm/INSTALL.md Helm installation examples
Chart Documentation helm/unifi-network-operator/README.md Complete chart reference

🎯 Workflow Summary

PR Validation (pr-validation.yaml)

Triggers: Pull requests to main

  • Go formatting check
  • Static analysis (go vet)
  • Unit tests with race detection
  • Helm chart linting
  • Docker build test

Docker Build & Push (docker-build-push.yaml)

Triggers: Push to main, feature branches, tags

  • Runs tests
  • Builds multi-arch images
  • Pushes to GitHub Container Registry
  • Creates multiple tags

Helm Release (helm-release.yaml)

Triggers: Push to main (helm changes)

  • Packages Helm chart
  • Creates releases
  • Publishes to GitHub Pages

Complete Release (release.yaml)

Triggers: Version tags (v*)

  • Builds Docker images
  • Packages Helm chart
  • Creates GitHub release
  • Publishes everything

⚠️ Common Issues & Solutions

"Resource not accessible by integration"

Solution: Enable read/write permissions (Step 2 above)

Docker images not public

Solution: Change package visibility to public (Step 3 above)

Helm chart not appearing

Solution:

  • Enable GitHub Pages (Step 1)
  • Wait 5-10 minutes for initial setup
  • Check workflow logs

Workflow fails on first run

Solution: Complete Steps 1 and 2 first, then re-run workflow

🎉 Success Checklist

Once everything is set up, you should have:

  • ✅ GitHub Pages enabled
  • ✅ Workflow permissions configured
  • ✅ PR merged to main
  • ✅ First release created (v0.1.0)
  • ✅ Docker images available at ghcr.io
  • ✅ Helm repository accessible
  • ✅ All workflows passing
  • ✅ Package visibility set to public

🔗 Quick Links for Setup

  1. Enable Pages: https://github.com/vegardengen/unifi-network-operator/settings/pages
  2. Configure Actions: https://github.com/vegardengen/unifi-network-operator/settings/actions
  3. View Actions: https://github.com/vegardengen/unifi-network-operator/actions
  4. Create PR: https://github.com/vegardengen/unifi-network-operator/pull/new/feature/add-helm
  5. Manage Packages: https://github.com/vegardengen?tab=packages

💡 Tips

  • Test locally first: Always run make helm-lint and make test before pushing
  • Use semantic versioning: Major.Minor.Patch (e.g., v1.2.3)
  • Pre-releases: Use alpha/beta/rc tags (e.g., v1.0.0-beta.1)
  • Monitor workflows: Check Actions tab after every push
  • Read the logs: Workflow logs contain detailed information about any failures

🆘 Need Help?

  1. Workflow issues: Check .github/README.md
  2. Setup problems: See .github/SETUP.md
  3. Helm questions: Read helm/README.md
  4. General CI/CD: Review CICD.md

Status: Ready to deploy! Follow Steps 1-5 above to complete the setup.

Created: $(date) Repository: https://github.com/vegardengen/unifi-network-operator