Merge pull request circleci#7623 from circleci/DOCTEAM-590_db_sch-pipe-updates

Sch pipe updates

Author: devinmarieb

jekyll/_cci2/inject-environment-variables-with-api.adoc

@@ -27,7 +27,7 @@ The example below triggers a pipeline with parameter values for `workingdir` and
 NOTE: In order to pass a parameter when triggering a pipeline via the API, the parameter must be <<reusing-config#using-the-parameters-declaration,declared in the configuration file>>.
 
 ```shell
-curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
+curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
   "parameters": {
     "workingdir": "./myspecialdir",
     "image-tag": "4.8.2"

jekyll/_cci2/migrate-scheduled-workflows-to-scheduled-pipelines.adoc

@@ -18,7 +18,7 @@ NOTE: **The deprecation of the scheduled workflows feature has been postponed**.
 
 Migrating to scheduled pipelines from scheduled workflows will eliminate the following limitations of scheduled workflows:
 
-- Cannot control the actor, so scheduled workflows can't use restricted contexts
+- Cannot control the actor (yourself, or the scheduling system), so scheduled workflows cannot use restricted contexts
 - Cannot control the interaction with auto-cancelling of pipelines
 - Cannot use scheduled workflows together with dynamic config without complex workarounds
 - Cannot change or cancel scheduled workflows on a branch without triggering a pipeline

jekyll/_cci2/pipeline-variables.md

@@ -1,27 +1,29 @@
 ---
 layout: classic-docs
 title: Pipeline values and parameters
-description: "Detailed information about pipeline parameters and values"
+description: "Information about pipeline parameters and values and how to use them."
 categories: [getting-started]
-order: 1
 contentTags: 
   platform:
   - Cloud
   - Server v4.x
   - Server v3.x
 ---
 
+## Introduction
+{: #introduction}
+
 Pipeline values and parameters can be used to create reusable pipeline configurations.
 
 * **Pipeline values** represent pipeline metadata that can be used throughout the configuration.
-* **Pipeline parameters** are typed pipeline variables that are declared in the `parameters` key at the top level of a configuration. Users can pass `parameters` into their pipelines when triggering a new run of a pipeline through the API.
+* **Pipeline parameters** are typed pipeline variables that are declared in the `parameters` key at the top level of a configuration. Users can pass `parameters` into their pipelines when triggering a new run of a pipeline through the API or web app.
 
 ## Pipeline values
 {: #pipeline-values }
 
 Pipeline values are available to all pipeline configurations and can be used without previous declaration.
 
-For a full list of values and built-in environment variables, see the [Project Values and Variables guide]({{site.baseurl}}/variables/#pipeline-values).
+For a full list of values and built-in environment variables, see the [Project values and variables](/docs/variables/#pipeline-values) guide.
 
 {% include snippets/pipeline-values.md %}
 
@@ -45,28 +47,28 @@ jobs:
       - run: echo $CIRCLE_COMPARE_URL
 ```
 
-When using the above method to set the values in the `environment` key, note that if the pipeline variable is empty it will be set to `<nil>`. If you need an empty string instead, [set the variable in a shell command]({{ site.baseurl }}/set-environment-variable/#set-an-environment-variable-in-a-shell-command).
+When using the above method to set the values in the `environment` key, note that if the pipeline variable is empty it will be set to `<nil>`. If you need an empty string instead, [set the variable in a shell command](/docs/set-environment-variable/#set-an-environment-variable-in-a-shell-command).
 {: class="alert alert-info" }
 
 ## Pipeline parameters in configuration
 {: #pipeline-parameters-in-configuration }
 
-Pipeline parameters are declared using the `parameters` key at the top level of a `.circleci/config.yml` file.
+Pipeline parameters are declared using the `parameters` key at the top level of a `.circleci/config.yml` file. Pipeline parameters can be referenced by value and used as a configuration variable under the scope `pipeline.parameters`.
 
 Pipeline parameters support the following types:
+
 * string
 * boolean
 * integer
 * enum
 
-See [Parameter Syntax]({{ site.baseurl }}/reusing-config/#parameter-syntax) for usage details.
-
-Pipeline parameters can be referenced by value and used as a config variable under the scope `pipeline.parameters`.
+See [Parameter syntax](/docs/reusing-config/#parameter-syntax) for usage details.
 
-The example below shows a configuration with two pipeline parameters (`image-tag` and `workingdir`) defined at the top of the config, and then subsequently referenced in the `build` job:
+The example below shows a configuration with two pipeline parameters (`image-tag` and `workingdir`) defined at the top of the configuration, and then subsequently referenced in the `build` job:
 
 ```yaml
 version: 2.1
+
 parameters:
   image-tag:
     type: string
@@ -95,12 +97,13 @@ jobs:
 
 A pipeline can be triggered with specific `parameter` values using the API v2 endpoint to [trigger a pipeline](https://circleci.com/docs/api/v2/#trigger-a-new-pipeline). This can be done by passing a `parameters` key in the JSON packet of the `POST` body.
 
-**Note:** Please note that the `parameters` key passed in this `POST` request is **NOT** secret.
+The `parameters` key passed in this `POST` request is **NOT** secret.
+{: class="alert alert-warning" }
 
-The example below triggers a pipeline with the parameters described in the above config example (NOTE: To pass a parameter when triggering a pipeline via the API the parameter must be declared in the configuration file.).
+The example below triggers a pipeline with the parameters described in the above configuration example. If you run a command to trigger a pipeline, and the parameter has not been declared in the configuration file, you will receive an error response message, such as `Project not found`.
 
 ```shell
-curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
+curl -u ${CIRCLE_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
   "parameters": {
     "workingdir": "./myspecialdir",
     "image-tag": "4.8.2"
@@ -111,29 +114,18 @@ curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d
 ### Passing parameters when triggering pipelines using the CircleCI web app
 {: #passing-parameters-when-triggering-pipelines-using-the-circleci-web-app }
 
-In addition to using the CLI and API, you can also trigger a pipeline with parameters from the CircleCI web app. To do this:
-
-  1. Navigate to the dashboard view in the web app.
-  2. Use the project filter to select the desired project.
-  3. Use the branch filter to select the branch on which you want to run the new pipeline.
-  4. Click the **Trigger Pipeline** button (towards the top right corner of the page).
-  5. Use the **Add Parameters** dropdown to specify the type, name, and value of your desired parameters.
-  6. Click **Trigger Pipeline**.
+In addition to using the API, you can also trigger a pipeline with parameters from the CircleCI web app. If you pass a parameter when triggering a pipeline from the web app, and the parameter has not been declared in the configuration file, the pipeline will fail with the error `Unexpected argument(s)`.
 
-**NOTE:** If you pass a parameter when triggering a pipeline from the web app, and the parameter has not been declared in the configuration file, the pipeline will fail with the error `Unexpected argument(s)`)
-
-
-## The scope of pipeline parameters
-{: #the-scope-of-pipeline-parameters }
+1. Use the project filter to select the desired project.
+2. Use the branch filter to select the branch on which you want to run the new pipeline.
+3. Click the **Trigger Pipeline** button (towards the top right corner of the page).
+4. Use the **Add Parameters** dropdown to specify the type, name, and value of your desired parameters.
+5. Click **Trigger Pipeline**.
 
-Pipeline parameters can only be resolved in the `.circleci/config.yml` file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your config.yml file. This was done because access to the pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling config, potentially jeopardizing determinism and creating a surface area of vulnerability.
+Parameters can also be called when setting up a scheduled pipeline in the web app. The parameters are part of the trigger form in **Project Settings > Triggers**. Any parameter set up as a part of a scheduled pipeline will also need to be declared in the configuration file, otherwise the the pipeline will fail with the error `Unexpected argument(s)`.
 
-
-## Config processing stages and parameter scopes
-{: #config-processing-stages-and-parameter-scopes }
-
-### Processing stages
-{: #processing-stages }
+## Configuration processing stages
+{: #configuration-processing-stages }
 
 Configuration processing happens in the following stages:
 
@@ -143,10 +135,15 @@ Configuration processing happens in the following stages:
 
 The remaining configuration is processed, element parameters are resolved, type-checked, and substituted.
 
-## Element parameter scope
+## The scope of pipeline parameters
+{: #the-scope-of-pipeline-parameters }
+
+Pipeline parameters can only be resolved in the `.circleci/config.yml` file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your `.circleci/config.yml` file. This is because access to pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling configuration. This would potentially create a surface area of vulnerability, increasing security risks.
+
+### Element parameter scope
 {: #element-parameter-scope }
 
-Element parameters use lexical scoping, so parameters are in scope within the element they are defined in, e.g. a job, a command, or an executor. If an element with parameters calls another element with parameters, like in the example below, the inner element does not inherit the scope of the calling element.
+Element parameters use lexical scoping, so parameters are in scope within the element they are defined in, for example, a job, a command, or an executor. If an element with parameters calls another element with parameters, like in the example below, the inner element does not inherit the scope of the calling element.
 
 ```yaml
 version: 2.1
@@ -160,25 +157,25 @@ commands:
       - run: echo << parameters.message >>
 
 jobs:
-  cat-file:
+  daily-message:
+    machine: true
     parameters:
-      file:
+      message:
         type: string
     steps:
       - print:
-          message: Printing << parameters.file >>
-      - run: cat << parameters.file >>
+          message: Printing << parameters.message >>
 
 workflows:
   my-workflow:
     jobs:
-      - cat-file:
-          file: test.txt
+      - daily-message:
+         message: echo << parameters.message >>
 ```
 
-Even though the `print` command is called from the cat-file job, the file parameter would not be in scope inside the print. This ensures that all parameters are always bound to a valid value, and the set of available parameters is always known.
+Even though the `print` command is called from the `cat-file` job, the file parameter would not be in scope inside the print job. This ensures that all parameters are always bound to a valid value, and the set of available parameters is always known. Running this would throw a pipeline error of `Arguments referenced without declared parameters: message`.
 
-## Pipeline value scope
+### Pipeline value scope
 {: #pipeline-value-scope }
 
 Pipeline values, the pipeline-wide values that are provided by CircleCI (e.g. `<< pipeline.number >>`) are always in scope.
@@ -194,11 +191,9 @@ Pipeline parameters which are defined in configuration are always in scope, with
 ## Conditional workflows
 {: #conditional-workflows }
 
-Use the [`when` clause]({{site.baseurl}}/configuration-reference/#using-when-in-workflows) (or the inverse clause `unless`) under a workflow declaration, along with a [logic statement]({{site.baseurl}}/configuration-reference/#logic-statements), to decide whether or not to run that workflow. Logic statements in a `when` or `unless` clause should evaluate to a truthy or falsy value.
-
-The most common use of this construct is to use a pipeline parameter as the value, allowing an API trigger to pass that parameter to determine which workflows to run.
+Use the [`when` clause](/docs/configuration-reference/#using-when-in-workflows) (or the inverse clause `unless`) under a workflow declaration, along with a [logic statement](/docs/configuration-reference/#logic-statements), to decide whether or not to run that workflow. Logic statements in a `when` or `unless` clause should evaluate to a truthy or falsy value.
 
-Below is an example configuration using the pipeline parameter `run_integration_tests` to drive whether the workflow `integration_tests` will run.
+The most common use of this construct is to use a pipeline parameter as the value, allowing a trigger to pass that parameter to determine which workflows to run. Below is an example configuration using the pipeline parameter `run_integration_tests` to set whether the workflow `integration_tests` will run.
 
 ```yaml
 version: 2.1
@@ -209,7 +204,6 @@ parameters:
     default: false
 
 workflows:
-  version: 2
   integration_tests:
     when: << pipeline.parameters.run_integration_tests >>
     jobs:
@@ -222,7 +216,7 @@ jobs:
       - ... # job steps
 ```
 
-The example shown above prevents the workflow `integration_tests` from being triggered unless it is explicitly invoked when the pipeline is triggered with the following in the `POST` body:
+In this example, the workflow `integration_tests` is not triggered unless it is explicitly invoked when the pipeline is triggered with the following in the `POST` body:
 
 ```json
 {

jekyll/_cci2/scheduled-pipelines.md

@@ -8,27 +8,35 @@ contentTags:
   - Cloud
 ---
 
-## Introduction
-{: #introduction }
-
 **Scheduled pipelines are currently available for GitHub and Bitbucket VCS users.** Scheduled pipelines allow you to trigger pipelines periodically based on a schedule. Scheduled pipelines retain all the features of pipelines:
 
-- Control the actor associated with the pipeline, which can enable the use of [restricted contexts](/docs/contexts/#project-restrictions)
-- Use [dynamic config](/docs/dynamic-config) via setup workflows
-- Modify the schedule without having to edit `.circleci/config.yml`
-- Take advantage of [auto-cancelling](/docs/skip-build/#auto-cancelling)
-- Specify [pipeline parameters](/docs/pipeline-variables/#pipeline-parameters-in-configuration) associated with a schedule
-- Manage common schedules, for example, across workflows
+- Control the actor (yourself, or the scheduling system) associated with the pipeline, which can enable the use of [restricted contexts](/docs/contexts/#project-restrictions).
+- Use [dynamic config](/docs/dynamic-config) via setup workflows.
+- Modify the schedule without having to edit `.circleci/config.yml`.
+- Take advantage of [auto-cancelling](/docs/skip-build/#auto-cancelling).
+- Specify [pipeline parameters](/docs/pipeline-variables/#pipeline-parameters-in-configuration) associated with a schedule.
+- Manage common schedules, for example, across workflows.
 
 Scheduled pipelines are configured through the API, or through the project settings in the CircleCI web app.
 
 A scheduled pipeline can only be configured for one branch. If you need to schedule for two branches, you would need to set up two schedules.
 {: class="alert alert-info"}
 
+## Introduction
+{: #introduction }
+
+Scheduled pipelines allow you to trigger pipelines periodically based on a schedule, from either the CircleCI web app or API. Schedules can range from daily, weekly, monthly, or on a very specific timetable. To set up basic scheduled pipelines, you do not need any extra configuration in your `.circleci/config.yml` file, however, more advanced usage of the feature will require extra `.circleci/config.yml` configuration (for example, workflow filtering, or using parameters).
+
+Pipeline parameters are typed pipeline variables in the form of a string, integer, or boolean. Adding a parameter to a scheduled pipeline can be done in the web app in the triggers form while setting up a schedule. Any parameters set up in this manner must be added to your configuration file using the `parameters` key.
+
+Scheduled pipelines are set to run by an "actor", either the CircleCI scheduling system, or a specific user (for example, yourself). The scheduling actor is important to consider if making use of restricted contexts in workflows. If the user (actor) running the workflow does not have access to the context, the workflow will fail with the `Unauthorized` status.
+
+You can find a basic how-to guide on the [Set a nightly scheduled pipeline](/docs/set-a-nightly-scheduled-pipeline) page, and more advanced examples on the [Schedule pipelines with multiple workflows](/docs/schedule-pipelines-with-multiple-workflows) pages.
+
 ## Get started with scheduled pipelines
 {: #get-started-with-scheduled-pipelines }
 
-To get started with scheduled pipelines, you have the option of using the API, or using the CircleCI web app. Both methods are described below. If you have existing workflows you need to migrate to scheduled pipelines, use the [Scheduled pipelines migration](/docs/migrate-scheduled-workflows-to-scheduled-pipelines) guide.
+To get started with scheduled pipelines, you have the option of using the API, or using the CircleCI web app. Both methods are described below.
 
 ### Use project settings in the web app
 {: #use-project-settings }
@@ -38,7 +46,7 @@ To get started with scheduled pipelines, you have the option of using the API, o
 3. To create a new schedule, click **Add Trigger**.
 4. Define the new schedule by filling out the form, then click **Save Trigger**.
 
-The form also provides the option of adding [pipeline parameters](/docs/pipeline-variables/), which are typed pipeline variables declared at the top level of a configuration.
+The form also provides the option of adding [pipeline parameters](/docs/pipeline-variables/), which are typed pipeline variables that you declare at the top level of a configuration.
 
 If you would like to manage common schedules for multiple workflows, you will need to manually set this in your `.circleci/config.yml` file. See the [Schedule pipelines with multiple workflows](/docs/schedule-pipelines-with-multiple-workflows) page for examples.
 
@@ -72,6 +80,11 @@ curl --location --request POST "https://circleci.com/api/v2/project/<project-slu
 
 For additional information, refer to the **Schedule** section under the [API v2 docs](https://circleci.com/docs/api/v2).
 
+## Migrate scheduled workflows to scheduled pipelines
+{: #migrate-scheduled-workflows-to-scheduled-pipelines }
+
+If you have existing scheduled workflows you need to migrate to scheduled pipelines, use the [Scheduled pipelines migration](/docs/migrate-scheduled-workflows-to-scheduled-pipelines) guide.
+
 ## Scheduled pipelines video tutorial
 {: #scheduled-pipelines-video-tutorial }
 
@@ -107,14 +120,14 @@ curl --location --request GET "https://circleci.com/api/v2/project/<project-slug
 --header "circle-token: <PERSONAL_API_KEY>"
 ```
 
-For GitHub and Bitbucket users: `project-slug` takes the form of `vcs-type/org-name/repo-name`, e.g. `gh/CircleCI-Public/api-preview-docs`.
+For GitHub and Bitbucket users: `project-slug` takes the form of `vcs-type/org-name/repo-name`, for example, `gh/CircleCI-Public/api-preview-docs`.
 
 ---
 
 **Q:** Why is my scheduled pipeline not running?
 
 **A:** There could be a few possible reasons:
-* Is the actor who is set for the scheduled pipelines still part of the organization?
+* Is the assigned actor who is set for the scheduled pipelines still part of the organization (you can find this setting is under **Attribution** in the **Triggers** section of the web app)?
 * Is the branch set for the schedule deleted?
 * Is your GitHub organization using SAML protection? SAML tokens expire often, which can cause requests to GitHub to fail.