The documentation for $DRONE_TAG is rather weak - is it supposed to be set only for tag events (and “promotion events that are derived from tags”)? We need to get the tag for ref triggers also, and luckily, AFAICT $DRONE_TAG is actually available for these builds too (only based on observing one build as of yet).
Can you please clarify if $DRONE_TAG is also supposed to be set for ref triggered builds, where the ref is a tag? If so, also update the documentation please. We really need $DRONE_TAG in combination with the ref trigger (provided that the ref is a tag of course), since we can’t filter tag events.
Many thanks for confirming that @bradrydzewski! Would you mind updating the $DRONE_TAG docs to reflect this? Would appreciate it, to help the future me and others I mean, currently the docs give the impression the variable won’t be set for ref triggered builds.
I will see what we can do to clarify, however, I believe the docs are technically accurate. There are only six types of events in the system (push, pull_request, tag, cron, rollback and promote). These events are determined by the incoming webhook that we receive from GitHub and correspond to the webhook event type. The ref filter in the trigger section of the yaml and the event are different, unrelated data types.
Reading the $DRONE_TAG documentation it gives the impression that only tag and promotion (“derived from tags”) trigger events cause $DRONE_TAG to be set. It turns out however, it will also be set for the ref trigger, if corresponding to a tag (which is good!).
So, basically reading the $DRONE_TAG documentation, it gives the reader the impression it only applies to tag and promotion trigger events. If you operate with a different notion of event in this documentation, you should be explicit as you can’t expect the reader to have the same understanding.
I think we should rename trigger to when in the yaml (note that we would of course make this backward compatible). The current naming is misleading and can cause confusion. A build is triggered by a webhook or by the user action of promoting or rolling back a build. It would be more accurate to describe the trigger section of the yaml as a filter, since it is not actually trigging a build. Renaming should help eliminate any confusion.
I don’t personally see how renaming trigger would help in this case. The confusion arises from the difference between webhook events Drone is dealing with and trigger events you can use in your configuration. As I already wrote, when I read $DRONE_TAG documentation, I thought instinctively that “event” referred to trigger events, until @ashwilliams1’s pointing out that event here refers to Drone’s internal notion (stemming from a webhook).
The “trigger” part isn’t causing the confusion, but the “event” option since it’s orthogonal to triggering by “ref” (thus giving me the impression that $DRONE_TAG wouldn’t be set when triggering on “ref”).