Workflow Run Rules allow you to sequence the order in which workflows run.

Take this scenario: I have a login workflow that I need an auth token from to run before all of the other workflows on my team.

General overview of Workflow Run Rules

How do I accomplish this? Well, let's jump into it.

  1. First, you need to create a Rule for your team. Please be aware that all rules will apply to all runs on all branches.

    <aside> ⚠️

    Only create rules that the team as a whole needs

    </aside>

    Navigate to the bottom right corner when viewing a team and click on the Rules button

    Screenshot 2024-12-13 at 9.26.15 AM.png

    Click the create rule button

    Screenshot 2025-01-12 at 10.36.06 AM.png

    You will then be able to define which workflows should run before which. Please notice that you can also define this by the groups or tags that the workflows belong to. In the above rule, I have chosen to run all workflows that have the Auth tag, before Dependent Test and Failing Test

    <aside> ⚠️

    Please be aware of creating loops within rules. The UI will prevent you from doing this, but it is good to be thinking of this ahead of time. Heres an example: I have two rules (Rule A) and (Rule B). Rule A runs a workflow Start before all CI tags, Rule B runs a workflow Delete after all CI tags. It is important that you do not add the CI tag to the Start or Delete workflows, as that would create a loop in the rules. If you do accidentally create a loop, the UI will notify you

    </aside>

    Screenshot 2025-01-16 at 7.32.54 AM.png

    There is also a checkbox that says Fail workflows if any priors fail this checkbox determines what should happen to dependent workflows when a prerequisite fails. If this checkbox is not checked, the dependent workflows will still run.

  2. After defining your rules, you will sometimes need to access information from one of the workflows that needs to run first. This can be done by using the setOutput function available in all Node 20 runners

    <aside> ⚠️

    Workflow Run Rules is not compatible with Classic Runners

    </aside>

  3. You can use the setOutput function like so.

    <aside> ⚠️

    Note that the key used in the setOutput function must be unique. If you use the same key again it will overwrite the previous key value pair

    </aside>

    Screenshot 2024-12-13 at 9.33.33 AM.png

  4. You can then access the output in runs that depend on the above workflow by accessing the workflowInputs object:

    Screenshot 2024-12-13 at 9.35.56 AM.png

  5. When a workflow that has dependencies fails, all workflows that require that workflow will immediately fail.

    Screenshot 2024-12-13 at 9.38.26 AM.png

    There will also be a failure reason surfaced in the run result

    Screenshot 2024-12-13 at 9.38.18 AM.png

Common edge cases

There are some situations where the usage of rules may not be obvious. These are documented below.

  1. Imagine you have a workflow you need to run before all CI flows, and a workflow you need to run after all CI flows. More or less a beforeAll and afterAll, if you are familiar with jest. You just created some rules that look like the ones below:

    Screenshot 2025-01-16 at 7.42.32 AM.png

    When the CI suite is run you would expect that Start test Session runs before all CI tags, and Delete Test session runs afterwards! However, you notice that the Delete Test Session workflow was not included in the CI run. Why? You’ve defined a rule that says it needs to run after CI flows, it definitely should be included, right?

    The Delete Test Session workflow does depend on all of the CI flows to be able to run, but if it is not included in the suite run, it doesn’t affect any of the CI flows so everything will proceed. In this situation, it is important to ensure the trigger running the CI suite includes all of the workflows you need it to run. This can be accomplished by adding a unique tag to both the Start Test Session Workflow and Delete Test Session workflow.