Manual approval

Use this job to request a workflow approval from users and teams. Refer to Manage workflows for more information.

The Approver role (predefined) is the role used for workflow approvals.

Although the role name does not reference workflows, users assigned to the Approver role (predefined) can approve workflow steps unless specific approvers are defined in the job itself.

Workflow approvers do not apply to feature flag changes. If you need approvers for feature management, create a custom role as described in Custom roles for feature management.

All CloudBees custom job repositories are listed on GitHub under CloudBees, Inc..

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`approvalInputs`	String, Boolean, Choice, Number	No	The input parameters for workflow approvers. Valid parameter types: `string`, `number`, `boolean`, and `choice`. These approval parameter input values can be accessed in subsequent jobs using the outputs context. For example: To return all parameter input values provided by a workflow approver in JSON format, use: `${{ needs.<approval_job_name>.outputs.approvalInputValues }}` To return a specific approval parameter input value, use: `${{ fromJSON(needs.<approval_job_name>.outputs.approvalInputValues).<parameter_name> }}`
`approvers`	String	No	A list of users whose participation in the workflow approval process is requested. The `approvers` field supports both user IDs and email addresses. If this field is not specified, approval eligibility defaults to users assigned to the Approver role (predefined). Approval rules and notifications are as follows: If approvers are specified, then: Only listed approvers will receive the email notification. Only listed approvers can participate in the approval process. If approvers are not specified, then: Only the workflow initiator will receive the email notification. All eligible users can participate in the approval process.
`delegates`	String	Yes	The value must be the path to the Manual approval custom job YAML file. For example, `https://github.com/cloudbees-io/manual-approval/custom-job.yml@v1`.
`disallowLaunchByUser`	String	No	When set to `true`, it prevents the user who started the workflow from participating in the approval. Default value is `false`.
`instructions`	String	Yes	Instructional text for approvers. This text appears: In the approval request email notification. On the workflow run details page.
`timeout-minutes`	Integer	No	The amount of time approvers have to respond to the approval request. The default value is `4320` minutes (three days).

Usage example

In your YAML file, add:

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Workflow example
on:
  workflow_dispatch:
jobs:
  build:
    steps:
      - uses: docker://golang:1.20.3-alpine3.17
        name: Say hello
        kind: test
        shell: sh
        run: |
          echo "hello world"
    needs: build-approval
  build-approval:
    with:
      approvers: ""
      disallowLaunchByUser: false
      instructions: "Please provide inputs"
      approvalInputs: |
        string-value:
          type: string
        retry-count:
          type: number
        boolean:
          type: boolean
          default: false
        Picklist:
          type: choice
          options:
            - abc
            - xyz
    timeout-minutes: 4320
    delegates: cloudbees-io/manual-approval/custom-job.yml@v1
  use-approval-parameters:
      needs:
        - build-approval
      steps:
        - uses: docker://golang:1.20.3-alpine3.17
          name: Echo inputs
          shell: sh
          run: |
            echo "string-value: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).string-value }}"
            echo "retry-count: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).retry-count }}"
            echo "boolean: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).boolean }}"
            echo "Picklist: ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).Picklist }}"

            echo "\
            Comments:
            ${{ fromJSON(needs.build-approval.outputs.approvalInputValues).string-value }}"▼