Jenkins smart home integration, free and open source
Your Jenkins jobs in Gladys: build status, failure alerts, run a job from a scene.
Published by guim31
- Devices
- Version 1.0.0
- Requires Gladys >=5.1.0
- ★ 0
Jenkins is the free, self-hosted automation server used to build, test and deploy software. This integration follows its jobs: each one becomes a device with the result of its last build, its number and duration, and whether a build is running; a Jenkins device sums up the build queue, the offline agents and the failing jobs. Scenes can react to a finished build, a job that fails or goes back to green, or an agent going offline, read a job, and, if you allow it, run a job with its parameters. A dashboard widget shows every job at a glance.
Tested against a real Jenkins 2.580 LTS (Docker); not against a real Gladys instance yet: feedback welcome on the issues.
What you need
- Gladys Assistant 5.1.0 or later.
- A Jenkins reachable from the Gladys machine, on the local network or on the Internet.
- A Jenkins user and its API token. Reading needs the Overall/Read and Job/Read permissions; running jobs from scenes needs Job/Build too.
At each refresh (every minute by default) the integration makes three light requests: the job list with the ten newest builds of each job (folders included, three levels deep), the build queue and the nodes. Running a job adds two requests, only when a scene asks for it.
Getting started
1. Create an API token
In Jenkins, click your name at the top right, then Security → API Token → Add new Token, give it a name and copy it (it is shown once). A dedicated user with only the permissions above limits what Gladys can do.
2. Configure the integration
In Gladys, open Integrations → Jenkins → Configuration and fill in:
- Jenkins address: the address you open Jenkins with,
http://192.168.1.2:8080orhttps://ci.example.com(keep the sub-path if Jenkins runs under one, e.g.https://example.com/jenkins). - User and API token: the user of step 1 and its token. Both empty: anonymous access, if your Jenkins allows anonymous reading.
- Jobs to follow: empty for every job (50 at most), or job names or links
copied from the browser, separated by commas. A folder name follows every job
in it. Example:
backup, infra/deploy. - Allow scenes to run jobs: off by default. Turn it on to use the Run a Jenkins job action.
- Refresh interval and Language of the names.
Click Test the connection: Jenkins and its version, how many jobs are followed, failing or queued, how many agents are offline, whether scenes may run jobs, and the listed jobs Jenkins does not know.
3. Add the devices
In Discovery, add the Jenkins device and the jobs you want. Their values arrive at once. The scene triggers and the widget work even for a job not added as a device.
The devices
One device per job
Named after the full name of the job (folder/job inside a folder). Jenkins
gives a job no other identifier: a renamed job is a new device.
| Feature | Type | Value |
|---|---|---|
| Status | text | Success, Failed, Unstable, Aborted, Not built, Running or Never built |
| Last build passed | binary | 1 when the last finished build succeeded, 0 when failed or unstable |
| Building | binary | 1 while a build runs |
| Last build number | counter | number of the last build |
| Last build duration | duration | duration of the last finished build, in seconds |
While a build runs, the status says Running; Last build passed and Last build duration keep the values of the previous build. An aborted build leaves Last build passed unchanged.
The Jenkins device
| Feature | Type | Value |
|---|---|---|
| Build queue | counter | builds waiting in the queue |
| Offline agents | counter | nodes offline (the built-in node included) |
| Failing jobs | counter | followed jobs whose last build failed or is unstable |
| Running jobs | counter | followed jobs building |
Dashboard
The Jenkins jobs widget shows one row per job, with its status and the number of its last build: failed jobs first, then the unstable ones, then the running ones. A line above says how many builds wait in the queue and how many agents are offline, when there are some. Choose some jobs in its settings, or leave it empty for all. Refresh reads Jenkins again at once.
Scenes
Triggers
- Jenkins build finished: a build of a followed job ended, whatever its result (filter on the job and the result: success, failed, unstable, aborted). Variables: the job name, the build number, the result in words, the duration in seconds, the link and a summary ready for a message.
- Jenkins job failing or back to green: a job starts failing (a failed or unstable build after a success, or its first build failing), or passes again after a failure (filter on the job and the change). Variables: the job name, the build number, the result, the link and a summary.
- Jenkins agent offline: a node that was online goes offline (filter on the agent name, empty for any). Variables: the agent name, the reason given by Jenkins and a summary.
The first reading of a job or an agent only learns its state: the past is never announced. At most three builds per job and reading are announced. What was seen is kept in the integration, so a restart neither misses an event nor announces one twice.
Actions
- Run a Jenkins job: queues a build of a followed job. Optional parameters,
NAME=valueseparated by&(e.g.TARGET=prod&VERSION=1.2), or a JSON object for a value holding&({"MESSAGE": "a & b"}); empty, the job uses its default values. A parameter the job does not declare is refused. Needs Allow scenes to run jobs in the configuration. Variables: the job name, whether the build was queued and its queue item number. The build goes on in Jenkins: use Jenkins build finished to react to its end. - Read a Jenkins job: the state of a followed job as variables for the next actions: status in words, last result, last build passed, building, last build number and duration, link.
Scene ideas
- Jenkins job failing or back to green, change "Failing" → turn the office lamp red and send the summary; change "Back to green" → turn it back to white.
- Every night at 3:00, if nobody is home → Run a Jenkins job
backup; Jenkins build finished forbackupwith result "Failed" → send a message. - Jenkins agent offline → send yourself a message with the summary: the machine of the agent may be down.
Troubleshooting
- Jenkins does not answer: check the address from the Gladys machine (same
port, same protocol); a Docker Gladys reaches the host by its IP address, not
localhost. - The address redirects: type the
https://address the browser ends on, with the sub-path if any. - User or API token refused: the token was revoked or mistyped; create a new one. A password works too, but a token is better.
- Access denied: no user was typed while Jenkins refuses anonymous reading, or the user lacks Overall/Read.
- Jenkins refused: the user needs the Job/Build permission: give it to the user, or keep running jobs off.
- No Jenkins API at this address: the address points to another service, or misses the sub-path.
- A job does not appear: it is deeper than three folder levels, or more than 50 jobs match the list: list fewer jobs or folders.
- Certificate refused: a self-signed certificate is not accepted; use the
http://address on the local network.
Limits
- Running jobs is the only command, and is off by default. Builds cannot be stopped from Gladys.
- 50 jobs at most, three folder levels deep; Jenkins is read every minute at the most often: an event arrives up to one interval late.
- A job is known by its full name: renaming it or moving it to another folder makes a new device.
- The ten newest builds of each job are read: when more than ten builds end between two readings, the oldest ones are not announced.
- Pipeline stages, test reports and build logs are not read.
- The texts of devices and scenes follow the language of the configuration; feature names are set when a device is added.
- Developed and tested against Jenkins 2.580 LTS; older versions with the same JSON API should work, without a guarantee.
Configuration settings
These are the settings Jenkins asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Jenkins | section | No | Enter the address of your Jenkins, a user and its API token (click your name at the top right → Security → API Token → Add new Token). A user with the Overall/Read and Job/Read permissions is enough to follow the jobs. |
| Jenkins address | string | No | The address you open Jenkins with: http://192.168.1.2:8080 or https://ci.example.com. |
| User | string | No | The Jenkins user the API token belongs to. |
| API token | secret | No | Empty with the user empty: anonymous access, if Jenkins allows it. |
| Jobs to follow | string | No | Empty: every job (50 at most). Otherwise job names or links, separated by commas; a folder name follows every job in it. |
| Options | section | No | |
| Allow scenes to run jobs | boolean | No | Off by default. When on, the "Run a Jenkins job" action can start any followed job: the user needs the Job/Build permission. |
| Refresh interval | select | No | How often Jenkins is read: three light requests each time. |
| Language of the names | select | No | Language of the feature names (set when a device is added), of the job statuses and of the scene texts. |
How to install Jenkins in Gladys
- In Gladys, open Integrations: Jenkins appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-jenkins:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-jenkins.
Jenkins requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Jenkins is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation