{"id":13585088,"url":"https://github.com/tomaae/homeassistant-portainer","last_synced_at":"2026-02-24T20:43:58.986Z","repository":{"id":162375882,"uuid":"636943975","full_name":"tomaae/homeassistant-portainer","owner":"tomaae","description":"Portainer integration for Home Assistant","archived":false,"fork":false,"pushed_at":"2025-09-06T00:15:51.000Z","size":608,"stargazers_count":134,"open_issues_count":12,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-09T09:46:27.747Z","etag":null,"topics":["docker","hacs","homeassistant","homeassistant-components","homeassistant-custom-component","homeassistant-integration","portainer"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomaae.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"tomaae"}},"created_at":"2023-05-06T03:28:40.000Z","updated_at":"2025-09-27T14:24:11.000Z","dependencies_parsed_at":"2024-03-31T13:22:54.709Z","dependency_job_id":"27be5784-5829-4770-bc99-f83fafdb1c89","html_url":"https://github.com/tomaae/homeassistant-portainer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tomaae/homeassistant-portainer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaae%2Fhomeassistant-portainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaae%2Fhomeassistant-portainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaae%2Fhomeassistant-portainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaae%2Fhomeassistant-portainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomaae","download_url":"https://codeload.github.com/tomaae/homeassistant-portainer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaae%2Fhomeassistant-portainer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29799216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T19:56:48.334Z","status":"ssl_error","status_checked_at":"2026-02-24T19:55:43.372Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","hacs","homeassistant","homeassistant-components","homeassistant-custom-component","homeassistant-integration","portainer"],"created_at":"2024-08-01T15:04:44.245Z","updated_at":"2026-02-24T20:43:58.979Z","avatar_url":"https://github.com/tomaae.png","language":"Python","funding_links":["https://ko-fi.com/tomaae"],"categories":["Python"],"sub_categories":[],"readme":"# Portainer integration for Home Assistant\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/tomaae/homeassistant-portainer?style=plastic)\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg?style=plastic)](https://github.com/hacs/integration)\n![Project Stage](https://img.shields.io/badge/project%20stage-development-yellow.svg?style=plastic)\n![GitHub all releases](https://img.shields.io/github/downloads/tomaae/homeassistant-portainer/total?style=plastic)\n\n![GitHub commits since latest release](https://img.shields.io/github/commits-since/tomaae/homeassistant-portainer/latest?style=plastic)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/tomaae/homeassistant-portainer?style=plastic)\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/tomaae/homeassistant-portainer/ci.yml?style=plastic)\n\n[![Help localize](https://img.shields.io/badge/lokalise-join-green?style=plastic\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyhpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuNi1jMTQ1IDc5LjE2MzQ5OSwgMjAxOC8wOC8xMy0xNjo0MDoyMiAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6REVCNzgzOEY4NDYxMTFFQUIyMEY4Njc0NzVDOUZFMkMiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6REVCNzgzOEU4NDYxMTFFQUIyMEY4Njc0NzVDOUZFMkMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENDIDIwMTcgKE1hY2ludG9zaCkiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDozN0ZDRUY4Rjc0M0UxMUU3QUQ2MDg4M0Q0MkE0NjNCNSIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDozN0ZDRUY5MDc0M0UxMUU3QUQ2MDg4M0Q0MkE0NjNCNSIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/Pjs1zyIAAABVSURBVHjaYvz//z8DOYCJgUxAtkYW9+mXyXIrI7l+ZGHc0k5nGxkupdHZxve1yQR1CjbPZURXh9dGoGJZIPUI2QC4JEgjIfyuJuk/uhgj3dMqQIABAPEGTZ/+h0kEAAAAAElFTkSuQmCC)](https://app.lokalise.com/public/892665226456f113e0a814.16864793/)\n\n![English](https://raw.githubusercontent.com/tomaae/homeassistant-mikrotik_router/master/docs/assets/images/flags/us.png)\n\n![Portainer Logo](https://raw.githubusercontent.com/tomaae/homeassistant-portainer/master/docs/assets/images/ui/logo.png)\n\nMonitor and control Portainer from Home Assistant.\n\nFeatures:\n\n- List Endpoints\n- List Containers\n- Check registry, for container updates\n  - Public repos on docker and github are currently supported\n\n# Features\n\n## Endpoints\n\nList of Portainer endpoints.\n\n![Endpoints](https://raw.githubusercontent.com/tomaae/homeassistant-portainer/master/docs/assets/images/ui/endpoints.png)\n\n## Containers\n\nList of containers.\n\n\u003cimg width=\"544\" height=\"838\" alt=\"image\" src=\"https://github.com/user-attachments/assets/fccee760-c43c-456e-a1bb-d576790e3b7d\" /\u003e\n\n## Update Check Feature\n\nThe integration supports checking for available updates for your containers via Docker Hub and GitHub registries.\n\n- **Check update**: This option is **disabled by default**. To use update checks, you must enable the option in the integration settings (`Configuration -\u003e Integrations -\u003e Portainer -\u003e Configure`).\n- **Update check time**: You can set the hour of day when the automatic update check should run. The update cycle is every 24 hours at the configured time.\n- **Update check button and sensor**: Both the update check button (\"Force update check\") and the update check sensor are **disabled by default** in the Home Assistant entity registry. You must enable them manually under `Settings -\u003e Devices \u0026 Services -\u003e Entities` to use them.\n- **Force update**: The update check button allows you to trigger an immediate update check outside the regular schedule. **Note:** Most registries (Docker Hub, GitHub) have rate limits. Excessive use of the force update button may result in temporary blocks or errors from the registry.\n- **Supported registries**: Currently, Docker Hub and GitHub Container Registry are supported for update checks.\n\nYou can view the update status and details in the sensor attributes. The button entity can be used to trigger a manual check, but please use it responsibly to avoid hitting registry rate limits.\n\n### Status Codes\n\nThe update check sensor and button use the following status codes in their state and attributes:\n\n| Status Code | Meaning                                                 |\n| ----------- | ------------------------------------------------------- |\n| 0           | No update available (up to date)                        |\n| 1           | Update available                                        |\n| 2           | Update status not yet checked                           |\n| 401         | Unauthorized (registry credentials required or invalid) |\n| 404         | Image not found on registry                             |\n| 429         | Registry rate limit reached                             |\n| 500         | Registry/internal error                                 |\n\nThe sensor attributes also include a human-readable `update_status_description` for each code. For details on errors or rate limits, see the sensor attributes.\n\n# Install integration\n\nThis integration is distributed using [HACS](https://hacs.xyz/).\n\nYou can find it under \"Integrations\", named \"Portainer\".\n\n## Get portainer access token\n\n1. Login into your portainer instance\n2. Click your username at the top right and select \"My Account\"\n3. Under \"Access tokens\", click \"Add access token\"\n4. Enter name for your access token (can be anything, for example \"homeassistant\")\n5. Copy displayed access token for use in integration setup\n\n## Setup integration\n\nSetup this integration for your Portainer in Home Assistant via `Configuration -\u003e Integrations -\u003e Add -\u003e Portainer`.\nYou can add this integration several times for different portainer instances.\n\n- \"Name of the integration\" - Friendly name for this Portainer instance\n- \"Host\" - Use hostname or IP and port (example: portainer.domain.tld or 192.168.0.2:9000)\n- \"Access token\" - Use access token from previous step\n- \"Use SSL\" - Connect to portainer using SSL\n- \"Verify SSL certificate\" - Validate SSL certificate (must be trusted certificate)\n\n## Configuration\n\nAfter setup, you can configure custom attributes and options for each Portainer entry via `Configuration -\u003e Integrations -\u003e Portainer -\u003e Configure`.\n\n### Supported options:\n\n- **Health check**: Checks if the container is running correctly by executing a defined command.\n- **Restart policy**: Defines how and when the container restarts after stopping.\n- **Check update**: Enable or disable the update check feature (see above for details).\n- **Update check time**: Set the hour of day for the daily update check.\n\n\u003cimg width=\"575\" height=\"517\" alt=\"image\" src=\"https://github.com/user-attachments/assets/98986c18-ce35-4c15-b92d-6b0d25c17e74\" /\u003e\n\n# Development\n\n## SonarCloud Automation\n\nTo enable SonarCloud analysis via GitHub Actions, you must create the following secrets in your GitHub repository:\n\n- `SONAR_PROJECT_KEY`\n- `SONAR_ORGANIZATION`\n- `SONAR_TOKEN`\n\nGo to your repository's **Settings \u003e Secrets and variables \u003e Actions** and add these secrets. This allows the SonarCloud workflow to run automatically for code analysis.\n\n## Visual Studio Code Setup\n\nA `.vscode-template` directory is provided in the repository to help you set up your development environment in Visual Studio Code. Copy the contents of `.vscode-template` to your `.vscode` directory to use recommended settings and launch configurations for Python development and testing.\n\n## Software Development\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Git\n- Visual Studio Code (recommended)\n\n### Setting up the Development Environment\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/tomaae/homeassistant-portainer.git\ncd homeassistant-portainer\n```\n\n#### 2. Create a Virtual Environment\n\nIt's highly recommended to use a virtual environment to isolate dependencies:\n\n```bash\n# Create virtual environment\npython -m venv .venv\n\n# Activate virtual environment\n# On Linux/macOS:\nsource .venv/bin/activate\n# On Windows:\n.venv\\Scripts\\activate\n```\n\n#### 3. Install Dependencies\n\n```bash\n# Install runtime dependencies\npip install -r requirements.txt\n\n# Install development and testing dependencies\npip install -r requirements_test.txt\n```\n\n#### 4. Install Development Tools (Optional)\n\n```bash\n# Install pre-commit hooks for code quality\npre-commit install\n```\n\n### Code Formatting\n\nThis project uses Black for code formatting. All code must be Black-formatted before committing. VS Code is configured to auto-format on save if you use the provided settings.\n\n```bash\n# Format all Python files\nblack custom_components/ tests/\n\n# Check formatting without making changes\nblack --check custom_components/ tests/\n```\n\n### Running Tests\n\n#### Command Line\n\n```bash\n# Run all tests\npython -m pytest\n\n# Run tests with verbose output\npython -m pytest -v\n\n# Run tests with coverage report\npython -m pytest --cov=custom_components.portainer --cov-report=html\n\n# Run specific test file\npython -m pytest tests/test_tag_parsing.py\n\n# Run specific test\npython -m pytest tests/test_tag_parsing.py::TestDockerImageTagParsing::test_parse_image_name\n```\n\n#### Visual Studio Code Integration\n\n##### 1. Install Extensions\n\nInstall the following VS Code extensions:\n\n- **Python** (ms-python.python)\n- **Python Test Explorer** (or use built-in testing)\n\n##### 2. Configure VS Code Settings\n\nCreate or update `.vscode/settings.json`:\n\n```json\n{\n  \"python.defaultInterpreterPath\": \"./.venv/bin/python\",\n  \"python.testing.pytestEnabled\": true,\n  \"python.testing.unittestEnabled\": false,\n  \"python.testing.pytestArgs\": [\"tests\"],\n  \"python.testing.autoTestDiscoverOnSaveEnabled\": true,\n  \"python.terminal.activateEnvironment\": true,\n  \"editor.formatOnSave\": true,\n  \"python.formatting.provider\": \"black\"\n}\n```\n\n##### 3. Activate Tests in VS Code\n\n1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)\n2. Run `Python: Select Interpreter`\n3. Choose `./.venv/bin/python`\n4. Run `Test: Refresh Tests` to discover tests\n5. Open the Test Explorer (`Ctrl+Shift+T` / `Cmd+Shift+T`)\n\nYou should now see all 110 tests organized by file and class in the Test Explorer.\n\n##### 4. Running Tests in VS Code\n\n- **Run all tests**: Click the play button at the top of Test Explorer\n- **Run specific test**: Click the play button next to any test\n- **Debug test**: Right-click on a test and select \"Debug Test\"\n- **View test output**: Click on any test to see results and output\n\n### Test Structure\n\n```\ntests/\n├── test_availability_fix.py      # Entity availability management (enabled/disabled states)\n├── test_dynamic_ui_reactive.py   # Dynamic UI behavior\n├── test_pure_logic.py            # Core config flow logic and validation\n├── test_tag_parsing.py           # Docker image name parsing\n├── test_ui_field_visibility.py   # Conditional field display\n├── test_unique_id_fix.py         # Entity unique ID generation\n└── test_update_checks.py         # Container update logic and caching\n```\n\n### Development Workflow\n\n1. **Create a feature branch**: `git checkout -b feature/your-feature`\n2. **Make changes** to the code\n3. **Format code**: Use Black to ensure consistent code style\n4. **Run tests**: `python -m pytest` to ensure nothing breaks\n5. **Commit changes**: `git commit -m \"Description of changes\"`\n6. **Push and create PR**: `git push origin feature/your-feature`\n\n#### Code Formatting with Black\n\nThis project uses [Black](https://black.readthedocs.io/) for consistent code formatting.\n\n```bash\n# Format all Python files\nblack custom_components/ tests/\n\n# Check if files need formatting (without applying changes)\nblack --check custom_components/ tests/\n\n# Format specific file\nblack custom_components/portainer/coordinator.py\n```\n\n**Important**: All code must be Black-formatted before committing. VS Code is configured to auto-format on save if you use the provided settings.\n\n### Debugging\n\nAdd breakpoints in VS Code and use the debug configuration for pytest:\n\n```json\n// .vscode/launch.json\n{\n  \"version\": \"0.2.0\",\n  \"configurations\": [\n    {\n      \"name\": \"Python: pytest\",\n      \"type\": \"debugpy\",\n      \"request\": \"launch\",\n      \"module\": \"pytest\",\n      \"args\": [\"tests/\", \"-v\"],\n      \"console\": \"integratedTerminal\",\n      \"python\": \"./.venv/bin/python\",\n      \"cwd\": \"${workspaceFolder}\"\n    }\n  ]\n}\n```\n\n### Current Test Coverage\n\n- **Total Tests**: 121\n- **Entity Availability Tests**: Entity enabled/disabled states\n- **Static UI Tests**: Static UI behavior\n- **Pure Logic Tests**: Config flow logic and validation\n- **Tag Parsing Tests**: Docker image name parsing\n- **UI Field Visibility Tests**: Conditional field display\n- **Unique ID Tests**: Entity unique ID generation\n- **Update Check Tests**: Container update logic and caching\n- **Success Rate**: 100% ✅\n\n## Translation\n\nTo help out with the translation you need an account on Lokalise, the easiest way to get one is to [click here](https://lokalise.com/login/) then select \"Log in with GitHub\".\nAfter you have created your account [click here to join Portainer project on Lokalise](https://app.lokalise.com/public/892665226456f113e0a814.16864793/).\n\nIf you want to add translations for a language that is not listed please [open a Feature request](https://github.com/tomaae/homeassistant-portainer/issues/new?labels=enhancement\u0026title=%5BLokalise%5D%20Add%20new%20translations%20language).\n\n## Enabling debug\n\nTo enable debug for Portainer integration, add the following to your configuration.yaml:\n\n```\nlogger:\n  default: info\n  logs:\n    custom_components.portainer: debug\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaae%2Fhomeassistant-portainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomaae%2Fhomeassistant-portainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaae%2Fhomeassistant-portainer/lists"}