Improve agent identity persistence and stale agent management #7

New issue

Open

opened 2026-05-03 06:21:57 +00:00 by lambadalambda · 0 comments

lambadalambda commented

2026-05-03 06:21:57 +00:00

Owner

Problem

A Docker Compose agent without a persistent /etc/woodpecker volume re-registered as a new agent after restart. Because the hostname was not explicitly set, the agent name defaulted to a container id. This left stale/offline agent records behind.

Issues encountered:

missing persistent agent config created new agent ids on restart
default container-id hostnames are not operationally meaningful
stale agents accumulated and had to be identified manually
the startup log showed persistence errors, but the operational impact was easy to miss

Desired behavior

Improve agent lifecycle UX:

make missing persistent agent config a prominent warning with remediation steps
document persistence requirements clearly in Docker Compose examples
recommend or require explicit WOODPECKER_HOSTNAME in containerized examples
provide UI/API affordances to identify and clean stale agents
optionally support automatic stale-agent expiry or de-duplication by hostname

Why this matters

Stable agent identity is important for operations, debugging, and scheduler trust. The current behavior makes it easy to accidentally create noisy stale agents.

## Problem A Docker Compose agent without a persistent /etc/woodpecker volume re-registered as a new agent after restart. Because the hostname was not explicitly set, the agent name defaulted to a container id. This left stale/offline agent records behind. Issues encountered: - missing persistent agent config created new agent ids on restart - default container-id hostnames are not operationally meaningful - stale agents accumulated and had to be identified manually - the startup log showed persistence errors, but the operational impact was easy to miss ## Desired behavior Improve agent lifecycle UX: - make missing persistent agent config a prominent warning with remediation steps - document persistence requirements clearly in Docker Compose examples - recommend or require explicit WOODPECKER_HOSTNAME in containerized examples - provide UI/API affordances to identify and clean stale agents - optionally support automatic stale-agent expiry or de-duplication by hostname ## Why this matters Stable agent identity is important for operations, debugging, and scheduler trust. The current behavior makes it easy to accidentally create noisy stale agents.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

pleroma/woodpecker#7

No description provided.

Rows
Columns