Request Approval

Puts an approval gate at the end of the step the op sits in. When the step finishes, the job stops in the approval state instead of moving on, and waits for one of the people you nominated to approve or reject it from the job monitor. Both answers are recorded against the job with the approver's name and comment.

The op does not stop the job where it stands. Everything after it in the same step still runs, and the gate only closes once the step is over. That is the first thing people get wrong with this op, and the reason it usually belongs near the start of the step it guards rather than immediately before the work it is meant to hold back. If you need the job to halt on the spot, use Pause a Job.

Fields

Approvers

The users and roles allowed to answer. The only field on the form. Required, and you can name as many as you like.

Pick entries from the list. Users and roles are mixed in the same picker, each one tagged with which it is, and system accounts appear alongside real people. Only active users are offered. Naming a role means every user currently holding that role can answer, evaluated when they try, so a role gained after the job paused still works.

The field accepts values typed by hand, which is how you get a ${} placeholder in here for an approver chosen at run time. What gets stored for a picked entry is user/ or role/ followed by that user's or role's id, so a placeholder only works when the stash value has that shape. Typing free text also offers an entry tagged Email, which stores the text as typed. Nothing rejects it, and nobody can use it to answer, so the job waits in approval with nobody on the list able to release it.

The list is not the only way in. Anybody holding the permission to approve all jobs can approve or reject regardless of what you put here, which is the escape hatch when the nominated approver is on holiday. Plan for that rather than around it.

Running this op twice in the same step does not stack the two lists. The last one to run replaces the first, and its approvers are the ones who count.

What each answer does

Approved

A log line records who approved and what they wrote. The job returns to the ready state and the scheduler picks it up again at the next step, carrying on from where the step ended. An approved event is raised.

Rejected

The comment is logged as an error, the job is marked rejected, and it does not go forward. Steps that registered a need to roll back are rolled back, then POST runs and the job ends in the rejected state. A rejected event is raised.

Nobody answers

Running the op stamps an approval deadline on the job, which the monitor can show in its Approval expiration column. The value comes from the job settings, not from this form. A job whose scheduled time has already passed gets the current time plus the approval expiry time, one day out of the box. A job still scheduled ahead gets its scheduled time plus the approval delay, zero out of the box.

That stamp is informational. What actually ends the wait is the job's Max Start Date, fixed when the job was created and not extended by this op. Once it passes, a background sweep moves the job to the expired state with an error line in the log naming the approval deadline, and raises an expiry event. The job does not carry on and it does not roll back. Someone has to reschedule or restart it.

Set the approval expiry time longer than the job expiry time and the extra allowance has no effect, because the job expires on the earlier deadline.

Notifications

The approval-requested event fires the moment the op runs, not when the step ends and the job actually stops. Approvers can be reading the mail while the rest of the step is still deploying.

The event is scoped to the job's projects, and carries the job name and the list of applications in the subject line. Whether anyone gets mail depends on the notification rules subscribed to that event.

Being listed in Approvers does not by itself put you on the mailing list. If you want the nominated approvers mailed, subscribe them to the approval-requested event, or send the message yourself with Send a notification right after this op.

Stash and rollback

Nothing is written into the stash. Return Key on the op's Options tab captures a constant 1 whatever happens, so it tells you nothing about the answer.

The op runs again during a rollback pass by default, which puts an approval gate on the end of the rollback step as well. Clear Run Rollback on the op's options (see the rule palette) unless a rollback really does need signing off too.

Combining with other ops

Wrap it in IF var condition THEN so that only the deployments that warrant it are gated. Gating every environment trains people to click approve without reading.

Change Topic Status after the gate, in the following step, is the way to record the approval on the topics themselves, since ops in the same step run before the gate closes.

Pause a Job is the op for a wait that has to happen at an exact point in the step, or where the release does not need to be attributed to a named approver.

Examples

Gate a production deployment on a release manager role, with an individual named as a fallback.

Approvers   Release Managers (role), foo_user (user)

Gate on an approver chosen earlier in the rule, for example the owner of the project being deployed. The variable has to already hold a role/ or user/ value; a bare user name does not resolve.

Approvers   ${approver_role}