Add section to reference shared config in YAML (codefresh-io#715)

NimRegev · web-flow · commit 5e3d33658f08 · 2023-06-13T12:04:55.000+03:00
* Add section to reference shared config in YAML

Added section to reference shared config and made content edits

* Add reference shared config example to api

Moved referencing shared config context as example to pipeline API and added xref in shared config topic

* Update shared-configuration.md

Added reference example to programmatic section with xrefs to CLI context command and full pipeline specifications

* Minor content edits

* Update shared-configuration.md

* Update shared-configuration.md

Fixed link

* Update shared-configuration.md
diff --git a/_docs/integrations/codefresh-api.md b/_docs/integrations/codefresh-api.md
@@ -232,6 +232,35 @@ max-width="70%"
 Notice that you must prefix the name of the pipeline with your username and repository so that it becomes
 visible in the GUI under the correct project.
 
+## Example: Referencing shared configuration contexts 
+Use shared configuration contexts in your pipelines by referencing it in the pipeline's YAML. This method is an alternative to importing the shared configuration contexts with the variables to use from the UI.  
+
+Add the `spec.contexts` field followed by the name or names of the shared configuration context or contexts to use. 
+
+>**IMPORTANT**:  
+Referencing shared configuration contexts with `spec.contexts` only works programmatically via the CLI/API.  
+The UI-based YAML options (**inline YAML**, **Use YAML from Repository/URL**) do not support this.  
+
+
+If you have a shared configuration named `test-hello` that includes the variable `test=hello`, you can add `spec.contexts.test-hello` to the pipeline YAML, and then reference this variable in the pipeline as you would any other variable.
+
+{% highlight shell %}
+{% raw %}
+version: "1.0"
+kind: pipeline
+metadata:
+  name: default/test-shared-config-from-pipe-spec
+spec:
+  contexts:
+    - test-hello
+  steps:
+    test:
+      image: alpine
+      commands:
+        - echo ${{test}} # should output "hello"
+{% endraw %}
+{% endhighlight %}
+
 ## Full pipeline specification
 
 If you don't want to create a pipeline from an existing one, you can also create your own YAML from scratch.  
diff --git a/_docs/pipelines/configuration/shared-configuration.md b/_docs/pipelines/configuration/shared-configuration.md
@@ -20,21 +20,31 @@ You can share:
 * Any kind of YAML data (advanced)
 
 
-## Creating shared configuration
 
-From the left sidebar click *Account settings* to enter your global settings. Then choose *Shared Configuration* from the left menu.
+## Creating shared configuration contexts
+
+Create one or more shared configuration contexts at the account-level to use in pipelines.
+
+1. In the Codefresh UI, on the toolbar, click the **Settings** icon.
+1. From the sidebar, select [**Shared Configuration**](https://g.codefresh.io/account-admin/account-conf/shared-config){:target="\_blank"}.
+1. Click **Add Configuration Context** and select the type of shared configuration context to add.
+1. Enter a name for the shared configuration context and click **Save**.
+1. Add one or more variables in Key = Value format.
+1. To allow access to all users, toggle **Allow access to all users** ON.
+1. Click **Save**.
+
 
 {% include 
 image.html 
 lightbox="true" 
 file="/images/pipeline/shared-configuration/shared-configuration.png" 
 url="/images/pipeline/shared-configuration/shared-configuration.png"
-alt="Creating shared configuration snippets" 
-caption="Creating shared configuration snippets"
+alt="Creating shared configuration contexts" 
+caption="Creating shared configuration contexts"
 max-width="50%"
 %}
 
-You can create four types of shared configuration:
+You can create four types of shared configuration contexts:
 
 * **Shared Configuration**: for environment variables
 * **Shared Secret**: for encrypted environment variables of sensitive data (access tokens, etc.) 
@@ -82,6 +92,7 @@ max-width="60%"
 We recommend that you disable access for all values of type *shared secret* and *secret YAML* unless your organization has different needs.
 
 
+
 ## Using shared environment variables
 
 Each pipeline has a set of environment variables that can be defined in the *Workflow* screen.
@@ -113,12 +124,13 @@ Once you click *Add* the values from the shared configuration will be appended t
 you have in your pipelines. In case of similar values the shared configuration will follow the [precedence rules]({{site.baseurl}}/docs/pipelines/variables/#user-provided-variables).
 
 
+
 ## Using shared Helm values
 
-To use a shared YAML snippet for Helm values you can install a new Helm chart either from:
+To use a shared YAML snippet for Helm values you can install a new Helm chart either from the:
 
-* The [Helm chart list]({{site.baseurl}}/docs/deployments/helm/helm-charts-and-repositories/)
-* The [Helm environment board]({{site.baseurl}}/docs/new-helm/helm-environment-promotion/#moving-releases-between-environments).
+* [Helm chart list]({{site.baseurl}}/docs/deployments/helm/helm-charts-and-repositories/)
+* [Helm environment board]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion/)
 
 In both cases, when you see the Helm installation dialog you can import any of your YAML snippets
 to override the default chart values.
@@ -199,7 +211,7 @@ The shared variables can now be used across your pipelines.
 
 ## Sharing any kind of YAML data in pipelines
 
-All the snippets from shared configuration are also available as context in the [Codefresh CLI](https://codefresh-io.github.io/cli/contexts/)
+All the snippets from shared configuration are also available as context in the [Codefresh CLI](https://codefresh-io.github.io/cli/contexts/).
 
 This means that you can manipulate them programmatically and read their values in the pipeline in any way you see fit.
 
@@ -223,15 +235,15 @@ spec:
 
 ### Example - custom value manipulation
 
-Let's say that you have a YAML segment with the following contents:
+Let's say that you have a YAML segment with the following content:
 
 {% highlight yaml %}
 favorite:
   drink: coffee
   food: pizza
 {% endhighlight %}
 
-Here is a pipeline step that is reading the yaml snippet and extracts a value
+Here is a pipeline step that reads the YAML snippet and extracts a value:
 
   `YAML`
 {% highlight yaml %}
@@ -254,9 +266,34 @@ I love eating pizza
 
 ## Manipulating shared configuration programmatically
 
-You can also create/update/delete shared configuration via the [Codefresh CLI](https://codefresh-io.github.io/cli/) or [API]({{site.baseurl}}/docs/integrations/codefresh-api/).
+You can also manipulate shared configurations programmatically via the [Codefresh CLI](https://codefresh-io.github.io/cli/){:target="\_blank"} and the [Codefresh API](https://g.codefresh.io/api/){:target="\_blank"}.
+
+For example, you can reference one or more shared configuration contexts directly in the YAML using `spec.contexts` as described below.
+
+If you have a shared configuration named `test-hello` that includes the variable `test=hello`, you can add `spec.contexts.test-hello` to the pipeline YAML, and then reference this variable in the pipeline as you would any other variable.
+
+{% highlight shell %}
+{% raw %}
+version: "1.0"
+kind: pipeline
+metadata:
+  name: default/test-shared-config-from-pipe-spec
+spec:
+  contexts:
+    - test-hello
+  steps:
+    test:
+      image: alpine
+      commands:
+        - echo ${{test}} # should output "hello"
+{% endraw %}
+{% endhighlight %}
+
+
+
+For detailed information on how to create/update/delete shared configuration contexts via the CLI, see [Contexts](https://codefresh-io.github.io/cli/contexts/){:target="\_blank"}.
 
-See the [context section](https://codefresh-io.github.io/cli/contexts/create-context/) in the CLI documentation.
+For information on all the options available in the _full Codefresh YAML_, see [Full pipeline specifications]({{site.baseurl}}/docs/integrations/codefresh-api/#full-pipeline-specification).
 
 
 
