Config overrides, URL orbs and centralised config (#9411)

* Adding `override-with` key to config reference (#9370)

* Adding new  key paragraph to config reference

* Implementing review suggestions

* Intro URL orbs (#9405)

* add sections to introduce url orbs

* Update jekyll/_cci2/orb-intro.adoc

* Adding `override-with` key to config reference (#9370)

* Adding new  key paragraph to config reference

* Implementing review suggestions

---------

Co-authored-by: Yann D. <[email protected]>

* How to override a job (#9407)

* scaffolding for simple example done.

* some formatting updates

* structural changes and corrections

* fixes

* Adding `override-with` key to config reference (#9370)

* Adding new  key paragraph to config reference

* Implementing review suggestions

* updates from review

* update syntax and add note to update URL

* fix link and typo

---------

Co-authored-by: Yann D. <[email protected]>

* Orb authoring guides updates (#9416)

* combine orb author guides and mention URL orbs

* fix links

* Add guide to managing a url orb allow list (#9413)

* Creating URL orb related how-to page

* Completing and improving page content

* Implementing review suggestions

* Addressing review comments

* Adding note for screenshots

* add screenshots

---------

Co-authored-by: Rosie Yohannan <[email protected]>

* update links from how to guide

* fix some lint errors

* create real links to API docs in manage allow-list page

---------

Co-authored-by: Yann D. <[email protected]>

Author: rosieyohannan

jekyll/_cci2/orb-author-intro.adoc renamed to archived/_cci2/orb-author-intro.adoc

@@ -11,10 +11,14 @@ contentTags:
 :page-layout: classic-docs
 :page-liquid:
 
-[#quick-start]
-== Quick start
+CircleCI orbs are packages of xref:orb-concepts#orb-configuration-elements[reusable configuration] that you can import into you CircleCI configuration files. Orbs come in two types:
 
-Orbs take xref:orb-concepts#orb-configuration-elements[reusable configuration] and package it in a way that can be published to the link:https://circleci.com/developer/orbs[Orb Registry] and imported into multiple configuration files. If you manage multiple, similar projects, consider abstracting out your config with orbs.
+* Registry orbs are packaged in a way that can be published to the link:https://circleci.com/developer/orbs[orb registry] and imported into multiple configuration files.
+* URL orbs can be stored anywhere that can be accessed by your CircleCI project, and are referenced by a URL to import into your configuration files.
+
+If you manage multiple, similar projects, consider abstracting out your config with orbs.
+
+== Prerequisites
 
 Before authoring an orb, it is recommended that you become familiar with the xref:config-intro#[CircleCI config] and authoring xref:reusing-config#[parameterized reusable config elements] pages.
 
@@ -26,12 +30,12 @@ Orbs consist of three main elements:
 
 Practice with xref:reusing-config#writing-inline-orbs[inline orbs]. Inline orbs can be defined within a single config file for testing.
 
-NOTE: Orb authors automatically agree to the CircleCI link:https://circleci.com/legal/code-sharing-terms/[Code Sharing Terms of Service]. All publicly published orbs are made available on the Orb Registry under the link:https://opensource.org/licenses/MIT[MIT License agreement]. For more information, see link:https://circleci.com/developer/orbs/licensing[Orb Licensing].
+NOTE: Registry orb authors automatically agree to the CircleCI link:https://circleci.com/legal/code-sharing-terms/[Code Sharing Terms of Service]. All publicly published orbs are made available on the Orb Registry under the link:https://opensource.org/licenses/MIT[MIT License agreement]. For more information, see link:https://circleci.com/developer/orbs/licensing[Orb Licensing].
 
-CAUTION: Once an orb is created it cannot be deleted. Orbs are link:https://semver.org/[SemVer compliant], and each published version is immutable. Publicly released orbs are potential dependencies for other projects. Therefore, allowing orb deletion would make users susceptible to unexpected loss of functionality.
+CAUTION: Once a registry orb is created it cannot be deleted. Registry orbs are link:https://semver.org/[SemVer compliant], and each published version is immutable. Publicly released orbs are potential dependencies for other projects. Therefore, allowing orb deletion would make users susceptible to unexpected loss of functionality.
 
 [#getting-started]
-== Getting started
+== Getting started with registry orbs
 
 [#orb-cli]
 === Orb CLI

jekyll/_cci2/configuration-reference.adoc

@@ -138,7 +138,7 @@ workflows:
 Documentation is available for orbs in the following sections:
 
 * xref:orb-intro#[Using Orbs]
-* xref:orb-author-intro#[Authoring Orbs].
+* xref:orb-author#[Authoring Orbs].
 
 Public orbs are listed in the https://circleci.com/developer/orbs[Orb Registry].
 
@@ -2455,6 +2455,36 @@ workflows:
 ----
 
 '''
+
+[#override-with]
+====== *`override-with`*
+
+The `override-with` key is used to override the job configuration with a job from the referenced orb.
+
+[.table.table-striped]
+[cols=4*, options="header", stripes=even]
+|===
+| Key | Required | Type | Description
+
+| `override-with`
+| N
+| String
+| The orb job name that will be used to override the existing job configuration. (Both URL-based and registry orbs are supported)
+|===
+
+*Example:*
+
+[,yml]
+----
+include::../_includes/snippets/orchestration-examples/override-with.yml[]
+----
+
+In the example above, the `test` job in the workflow is being overridden with the orb job `my-orb/my-test`. The `my-orb/my-test` job might be defined with a different resource class or execution steps.
+
+If the `my-orb/my-test` job is not defined inside the orb, the `test` job will compile using the local job definition.
+
+'''
+[#serial-group]
 ====== `serial-group`
 
 The `serial-group` key is used to add a property to a job to allow a group of jobs to run in series, rather than concurrently, across an organization. Serial groups control the orchestration of jobs across an organization, not just within projects and pipelines.

jekyll/_cci2/create-an-orb.adoc

@@ -37,7 +37,7 @@ circleci update
 
 circleci version
 ```
-* xref:orb-author-intro#register-a-namespace[Register a namespace] for your GitHub organization. Ensure the organization on GitHub is the owner for the CircleCI namespace for which you are developing your orb. This will be automatically configured correctly if you are using your own personal organization and namespace.
+* xref:orb-author#register-a-namespace[Register a namespace] for your GitHub organization. Ensure the organization on GitHub is the owner for the CircleCI namespace for which you are developing your orb. This will be automatically configured correctly if you are using your own personal organization and namespace.
 
 [#create-your-orb]
 == Create your orb

jekyll/_cci2/deployment-overview.adoc

@@ -78,7 +78,7 @@ workflows:
 
 Under the hood, this orb creates, bundles, and deploys your application using your specified parameters set under the `aws-code-deploy/deploy` job declaration.
 
-Check out the full range of available orbs in the link:https://circleci.com/developer/orbs[orbs registry]. If the orb you need has not been created yet, consider xref:orb-author-intro#[authoring one]!
+Check out the full range of available orbs in the link:https://circleci.com/developer/orbs[orbs registry]. If the orb you need has not been created yet, consider xref:orb-author#[authoring one]!
 
 [#using-images-to-simplify-deployment]
 == Using images to simplify deployment