Standardize global vs job-specific keywords in CI YAML reference doc
This topic has inconsistent information about which keywords are global and which are job-specific.
Apply a standard sentence or note for each. Ensure it's easy to scan for this information.
Side note: Use "globally-defined" consistently. Is it "globally-defined keywords"? If so, try to repeat that text each time you refer to it.
From !45499 (diffs, comment 432130459):
What is the difference between a configuration keyword and a global keyword?
Could these be called "Job keywords?" Or just plain "Keywords?" (Just trying to learn for myself, because I don't really know the difference and the terms can help clarify for me.)
What are the various types? Maybe you can spell this out in a topic called Keyword types? Here is my guess:
- Keywords (can apply to a job or globally)
- Global keywords (apply to all jobs)
- Job-specific keywords (apply only to job)
- Reserved keywords (ones you can't use at all because they're reserved for us?)
Proposal
Perhaps we can standardize on two types of keywords. We define these two as the standards at the top of the reference page, making it clear what we mean if we mention them anywhere in the page:
-
job keyword
: Can only be defined within jobs, (or adefault:
block), and apply to individual jobs . -
pipeline keywords
: Can only be defined at the pipeline level (never in jobs), and affect the pipeline as a whole (workflow
,stages
,include
,default
)
Keywords that are in a grey area, like variables
, will have extra details explaining that they can be used at both levels.