filters / Labels are not very well documented.

[reivilibre]

In the agent's flags, there seems to be the ability to specify some filters:

woodpecker/cmd/drone-agent/flags.go

Lines 67 to 71 in a07f120

	cli.StringFlag{
	EnvVar: "DRONE_FILTER,WOODPECKER_FILTER",
	Name: "filter",
	Usage: "filter expression to restrict builds by label",
	},

It says we can restrict builds by label — perfect, but it's not clear what those labels are or what the filters look like.

I've been digging through the code a little bit, and it turns out that:

1: this has examples of the filter syntax: https://github.com/woodpecker-ci/expr/blob/164b8b3d0915b31a990c04f93e20928ed67a45fb/selector_test.go#L11

2: the below defines the 'filter function' — one thing I notice is that it seems to be that if you specify a filter, you MUST manually specify platform == ... in that filter otherwise you won't be filtering by platform anymore (The 'platform' is special-cased into the filter.Labels map at some point leading up to here, but I've lost track)

woodpecker/server/rpc.go

Lines 494 to 518 in a07f120

	func createFilterFunc(filter rpc.Filter) (queue.Filter, error) {
	var st *expr.Selector
	var err error
	if filter.Expr != "" {
	st, err = expr.ParseString(filter.Expr)
	if err != nil {
	return nil, err
	}
	}
	return func(task *queue.Task) bool {
	if st != nil {
	match, _ := st.Eval(expr.NewRow(task.Labels))
	return match
	}
	for k, v := range filter.Labels {
	if task.Labels[k] != v {
	return false
	}
	}
	return true
	}, nil
	}

3: this below is where the labels are attached to the Task
https://github.com/woodpecker-ci/woodpecker/blob/master/server/hook.go#L390-L395

4: it seems like this might be specifiable as a labels map in the pipeline YAML, but that part is not entirely clear to me — seems to be libcompose.SliceorMap.

Point (2) seems like a bug to me — surely you shouldn't be able to bypass the platform filter.
But in any case, none of this seems documented (please point it out if it is :)) and it'd be nice to change that (I'm happy to do so, just wanted to know if I'm missing anything / not understanding properly).

[anbraten]

@reivilibre Do you mean the Filter type used for the RPC communication? 🤔 Could you provide some additional context?

[reivilibre]

@reivilibre Do you mean the Filter type used for the RPC communication? thinking Could you provide some additional context?

my apologies, I hit enter in the title bar and sent it without a body :(. I added some details now

[anbraten]

We just released some new docs with #282 two days ago and there are still some points missing / outdated. Would be super cool if you could create a PR and document some of the points you found out. Maybe a new page called Agent config similar to the Server config would be the best place.