Agent availability and offline handling in Jenkins - Step-by-Step Execution

Process Flow - Agent availability and offline handling

Agent starts

↓

Agent connects to Jenkins Master

↓

Agent status: Online

↓

Agent executes jobs

↓

Agent disconnects or fails

↓

Agent status: Offline

↓

Jenkins Master detects offline

↓

Handle offline: retry, notify, or mark unavailable

↓

Agent reconnects or manual intervention

This flow shows how a Jenkins agent connects, runs jobs, goes offline, and how Jenkins handles the offline state.

Execution Sample

Jenkins

agent.connect()
if agent.is_online():
    agent.run_job(job)
else:
    jenkins.notify_admin(agent)
    agent.retry_connection()

This code tries to connect an agent, runs a job if online, otherwise notifies admin and retries connection.

Process Table

Step	Action	Agent Status	Result	Notes
1	Agent starts and attempts connection	Connecting	Connection attempt sent	Agent tries to connect to Jenkins master
2	Agent connection successful	Online	Agent ready for jobs	Agent status changes to online
3	Agent receives job	Online	Job started	Agent begins executing job
4	Agent job running	Online	Job in progress	Agent is busy running job
5	Agent loses connection	Offline	Connection lost detected	Network or agent failure occurs
6	Jenkins detects offline agent	Offline	Admin notified	Jenkins marks agent offline and sends alert
7	Jenkins retries agent connection	Retrying	Retry attempt sent	Jenkins tries to reconnect agent
8	Agent reconnects successfully	Online	Agent ready again	Agent back online and ready for jobs
9	Agent remains offline after retries	Offline	Marked unavailable	Agent marked as unavailable for scheduling jobs

💡 Agent either reconnects successfully or is marked unavailable after retries

Status Tracker

Variable	Start	After Step 2	After Step 5	After Step 8	Final
agent.status	Disconnected	Online	Offline	Online	Online or Offline
jenkins.admin_notified	False	False	True	True	True or False
agent.retry_attempts	0	0	1	2	Max retries or 0

Key Moments - 3 Insights

Why does the agent status change to offline at step 5?

Because the agent lost connection to the Jenkins master, Jenkins detects this and updates the status to offline as shown in execution_table row 5.

What happens if the agent does not reconnect after retries?

Jenkins marks the agent as unavailable for scheduling jobs, as shown in execution_table row 9, preventing jobs from being assigned to a non-responsive agent.

How does Jenkins notify about an offline agent?

At step 6, Jenkins sends a notification to the admin to alert them about the offline agent, as indicated in the 'Result' and 'Notes' columns of execution_table row 6.

Visual Quiz - 3 Questions

Look at the execution table, what is the agent status at step 3?

A Online

B Offline

C Retrying

D Disconnected

💡 Hint

Check the 'Agent Status' column in execution_table row 3.

At which step does Jenkins notify the admin about the offline agent?

A Step 4

B Step 7

C Step 6

D Step 9

💡 Hint

Look at the 'Result' and 'Notes' columns in execution_table row 6.

If the agent never reconnects, what is the final agent status?

A Retrying

B Offline

C Online

D Disconnected

💡 Hint

Refer to the 'Final' column in variable_tracker for agent.status and execution_table row 9.

Concept Snapshot

Jenkins agents connect to the master to run jobs.
Agent status can be Online or Offline.
If offline, Jenkins detects and notifies admin.
Jenkins retries connection automatically.
If retries fail, agent is marked unavailable.
This ensures jobs run only on available agents.

Full Transcript

In Jenkins, agents connect to the master to execute jobs. When an agent starts, it attempts to connect. If successful, its status is Online and it can run jobs. If the agent loses connection, Jenkins detects this and marks the agent Offline. Jenkins then notifies the administrator and tries to reconnect the agent automatically. If the agent reconnects, it becomes Online again and resumes job execution. If it fails to reconnect after retries, Jenkins marks the agent as unavailable to prevent job assignment. This process ensures Jenkins only schedules jobs on agents that are available and responsive.