Question: Filtering scheduled pipelines by branch name

[blag]

Hello, I'm digging through the new scheduled pipelines feature documentation.

When converting from the old scheduled workflows syntax, I noticed that there doesn't seem to be an equivalent way to ensure that scheduled pipelines only trigger for specific branches.

Old trigger:

daily-run-workflow:
  triggers:
    - schedule:
        # Every day, 0421Z.
        cron: "21 4 * * *"
        filters:
          branches:
            only:
              - main  # <-- Only run on the main branch
  jobs:
    - test
    - build

But there doesn't seem to be an equivalent way to filter workflows by branch name:

daily-run-workflow:
  when:
    and:
      - equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
      - equal: [ "my schedule name", << pipeline.schedule.name >> ]
      # Missing mechanism to filter by branch name
  jobs:
    - test
    - build

I hope I'm not misunderstanding how scheduled pipelines work with respect to branches, but please correct me if that's the case.

Is there an existing way to filter on branch name? Maybe something like:

daily-run-workflow:
  when:
    and:
      - equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
      - equal: [ "my schedule name", << pipeline.schedule.name >> ]
      - equal: [ "main", << pipeline.branch.name >> ]  # <-- only match when pipeline.branch.name equals "main"

Or is this on the development roadmap?

Scheduled pipelines look like a very cool feature, I'm looking forward to fully utilizing them! Thank you!

Edit: Fixed YAML syntax and reworded a bit for clarity.

[sulami]

Hi @blag,

Scheduled pipelines are a change in structure, in that schedules are
not defined in config anymore, which has been problematic in all kinds
of ways. Instead they're defined within our platform via the this API
call, which includes the branch (or tag) to trigger the schedule on.

The only thing left to do in config is workflow filtering, which can
be done with pipeline values, as shown further along in that same
document.

Is there an existing way to filter on branch name? Maybe something
like:

This is not really related to scheduled pipelines due to the above,
but actually yes. The pipeline value you'll want to look at is
<< pipeline.git.branch >>. We also have a full list of currently
available pipeline values in our docs.

I hope that answers your questions, but let me know if anything is
unclear.

[blag]

Hey @sulami thanks for the response. I realize I misworded a few things in my issue, so I've tweaked a bit of the wording to be more clear what I'm referring to.

It would be great if the conversion examples included the branch filtering from the before examples. I have submitted PR #104 that includes examples for that, as well as fixing up a few small GFM syntax things.

I have been unable to find much documentation on the when and unless clauses in workflow filtering. If you can point me to more detailed documentation on that, I would appreciate it. Thank you!

[sulami]

I'll leave the scheduled pipelines docs bits to @h42zhu.

With regards to the when/unless clauses, the config reference has a good section on this. You should be able to adapt the branch filtering examples from there.

On a related note, @rosieyohannan / @thomasr8, I just realised the config reference doesn't list when/unless under <workflow_name> as it should.