Merge pull request #2923 from buildkite/bm/global_priority

Add information on using priority as a global value

pages/pipelines/managing_priorities.md

@@ -17,6 +17,26 @@ steps:
 
 Job priority is considered before jobs are dispatched to [agent queues](/docs/agent/v3/queues), so jobs with higher priority are assigned before jobs with lower priority, regardless of which has been longest in the queue. Priority only applies to command jobs, including plugin commands.
 
+## Prioritizing whole builds
+
+The `priority` key can be set as a top-level value, which applies it to all steps in the pipeline that do not have their own `priority` key set. This is useful when an entire pipeline requires a higher priority than others. For example:
+
+```yml
+priority: 100
+steps:
+  - label: "emergency fix"
+    command: "run_this_now.sh"
+  - wait: ~
+  - label: "this can wait"
+    command: "tests.sh"
+    priority: 1
+```
+{: codeblock-file="pipeline.yml"}
+
+The `emergency fix` step runs before _any step of any other running pipeline_ within your organization, unless one of these other pipeline steps has a priority greater than 100. If all available agents are running jobs, an appropriate agent will run the `emergency fix` step _only_ after its current job completes running.
+
+Prioritizing whole builds comes in handy when you need to reduce the number of agents (for example, to reduce costs over a weekend due to fewer available team members) but want to ensure any builds created on a critical pipeline are not left waiting for agents to run their jobs.
+
 ## Job dispatch precedence
 
 Jobs are dispatched in the following order: