Labeling Agents

Choosing which agent a workflow runs on may sometimes be important, if only select hosts are connected to given hardware or can deploy to a static site behind a reverse proxy. In these cases, Woodpecker uses a system of labels to identify which agent(s) a given workflow can run on.

See also

• https://woodpecker-ci.org/docs/administration/configuration/agent#agent_labels
• https://woodpecker-ci.org/docs/usage/workflow-syntax#labels
• Woodpecker Pipelines

You can configure labels by setting an environment variable in the agent’s docker compose file:

services:
  woodpecker-agent:
    container_name: woodpecker_agent
    image: woodpeckerci/woodpecker-agent:v3
    ...
    environment:
      WOODPECKER_AGENT_LABLES: location=parents_house,hardware=zigbee
      WOODPECKER_HOSTNAME: hal9000

Regardless of what you set, agents provide the following default labels unconditionally:

• platform=os/agent-arch
• hostname=my-agent
• backend=docker
• repo=*

(obviously, with the correct values substituted)

I found that the hostname tag was unreliable when running the agent in a Docker container (I think it was probably pulling the container’s sha256 as a hostname), but setting the WOODPECKER_HOSTNAME env fixed that.

Then, to select which agent(s) a given pipeline job may run on, add the following to the top level of the workflow file:

labels:
  location: parents_house

Recognizing label mismatch

The symptom of getting a pipeline label wrong is that it just… never starts. Doesn’t error, just sits in “hasn’t started yet” forever. Especially if you’re specifying the hostname label, check that the WOODPECKER_HOSTNAME environ is set properly on the agent.