Configuring manual approval of CI/CD tasks in SourceCraft

A task requiring manual approval does not run automatically when its dependencies complete successfully. It waits for the user to approve or reject the execution. This allows you, e.g., to verify the result before deploying it to the production environment.

To use manual approval:

1. Enable manual approval in the CI/CD configuration.
2. Confirm or reject task execution.

Enabling manual approval

1. Configure CI/CD in your repository if you have not done this already.

2. Open the .sourcecraft/ci.yaml file.

3. Under workflows:tasks, find a task that needs to be approved manually and add the approval parameter to its description.

   Warning

   The approval parameter gives settings for manual approval of task execution inside the workflows:tasks section. It cannot be used in upper-level tasks described in a separate tasks section outside of workflows.

   The following record forms are supported:

   • approval: true: Enable manual approval with the default timeout of 24 hours.
   • approval: false: Explicitly disable manual approval. This is equivalent to having no approval parameter.
   • approval: {}: Enable manual approval with default parameters.
   • approval: { timeout: ..., note: ..., require_comment: ... }: Enable manual approval with explicitly set parameters.

   The approval section supports the following parameters. All parameters are optional:

   • timeout: Maximum decision timeout, e.g., 1h or 2h. The default value is 24h. The time starts the moment the task status changes to AwaitingApproval. As soon as the time ends, the task gets automatically canceled.
   • note: Instruction for the user who makes the decision. It is a string of under 1,000 characters displayed in the UI. Not set by default.
   • require_comment: Requirement to add a comment when the task is approved or rejected. Specified as a Boolean value. The default value is false. If set to true, the user can make a decision only with a comment. The maximum comment length is 2,000 characters regardless of the require_comment value.

   For example, set a task-build dependency, waiting time, instruction, and the comment requirement:

   workflows:
     deploy:
       tasks:
         - name: build
           cubes:
             - name: build-cube
               script:
                 - echo "build"
         - name: deploy-prod
           needs: [build]
           approval:
             timeout: 2h
             note: "Check the test environment dashboards"
             require_comment: true
           cubes:
             - name: deploy-cube
               script:
                 - echo "deploy"
   

   In this example, after the build task completes successfully, the deploy-prod task will wait for the user's decision for up to two hours. The user must provide a comment to approve or reject the execution. The echo commands illustrate the task execution order; replace them with the build and deployment commands for your application.

4. Save your changes in the repository. If editing the file in the SourceCraft interface:

   1. In the top-right corner, click Commit changes.

   2. In the window that opens, configure the procedure for changes:

      • In the Commit message field, give a comment that will describe the changes you make.
      • Under Commit branch, select the branch you want to change. Create a new branch as needed.
      • Under After commit action, select an action to take after saving changes: Save and create a new change proposal or Just save.

   3. Confirm your changes.

5. Manually run the workflow after you select the branch with the updated .sourcecraft/ci.yaml file and the required workflow. For the example above, select deploy.

Confirming or rejecting task execution

1. Open the repository in the SourceCraft interface.
2. Under Code, navigate to CI/CD.
3. Select the execution with the workflow of interest. Executions awaiting approval will have the Pending status.
4. Wait for the Waiting for approval (AwaitingApproval) status. If the task has dependencies, first wait for them to be successfully completed.
5. Click Approve next to the task.
6. In the Manual approval required window, read the instructions from the note parameter, if any, and check the results of previous tasks.
7. In the Comment field, specify the reason for your decision. A comment is required if require_comment: true. The maximum length is 2,000 characters.
8. Click Approve to allow or Reject to reject the execution of the task.
9. Check the result: following approval, the task will be sent to the execution queue; after rejection, it will get the Rejected status.

With manual approval enabled, after you start a CI/CD pipeline, a task is Created and placed in a wait queue. The task remains in this status while the dependencies defined in the needs parameter are running. After all dependencies complete successfully, or if no dependencies are defined, the task status changes to AwaitingApproval, and the countdown for the approval timeout starts.

Possible outcomes:

• Approval (approve): The task moves to the execution queue and starts normally. The system logs the outcome (approved), user details, and comment in the decision details.
• Rejection (reject): The task is Rejected removed from the wait queue. The system logs the outcome (rejected), user details, and comment in the decision details. The Rejected status applies to the entire workflow and CI/CD execution.
• Timeout expired (expire): If no decision is made in time, the task is Canceled, and the system logs the outcome (expired) in the decision details. The Canceled status applies to the entire workflow and CI/CD execution.

Useful links

• Description of the approval section of the CI/CD reference with examples
• Tasks
• Starting a workflow manually in a SourceCraft repository