Change Requests

📷

Requires an upgraded subscription

This feature is exclusive to our Enterprise Plan. Book a demo to see it in action.

Overview

In most organizations, code is reviewed before it is considered for release. Given that secrets and configs are instrumental to code working correctly, they should be given the same thought and consideration as code - which is exactly why we built Change Requests.

Change Requests are a workflow-driven mechanism for proposing additions, modifications, or deletions of values stored in Doppler. Change Requests are then reviewed by a team member who holds the proper access to approve the changes.

Creating Change Requests

New Change Request

Creating Change Requests via the New Change Request form is great for proposing changes to configs you don't have write access to. This allows admins to minimize access scope creep while providing a low-overhead mechanism for developers to propose changes or additions.

📘

Permissions to Create a Change Request

A user can create a Change Request targeting any config that they are able to view in the dashboard, including configs the user can't view the secrets for. So long as the user can see the config on the Projects page, they will be able to target it in a Change Request.

1. From the navigation, select Change Requests.
2. Click the New Change Request button.
3. On the New Change Request form, the following fields are available:
   • Title of the Change Request
   • Description of the changes the Change Request is making
   • Project containing the configs you want to update, a Change Request can include changes for multiple projects
   • Configs you want to update
   • Secret Name of the secrets to add, update, or delete
   • Secret Value for each config being edited, including the Visibility Type and Value Type for each
4. To add changes to another secret click the + button at the bottom of the page.
5. Click the Submit Change Request button to submit your changes for review.

Secret Visibility Type

You're able to set the visibility type of a secret in a Change Request, but there are some caveats when it comes to restricted secrets.

You can only include a secret with the restricted visibility type in a Change Request if you also have the ability to review the change yourself. This is because restricted secrets in Change Requests follow the same rules as elsewhere in the dashboard, so reviewers won't be able to reveal them. As such, the user setting the restricted secret value must have review access to approve the change because they'll be the only user who knows what value was used. The only exception to this is that you can assign an empty value to a restricted secret as a placeholder, signaling to reviewers that they need to fill the secret in with a real value.

Editing Change Requests

Any Change Request can be edited once created.

1. From the navigation, select Change Requests.
2. Select the Change Request you would like to edit.
3. Click the Edit button at the top right of the page.

Any user that can review a change can edit that change, even if they did not author it. Authors may also edit their own Change Requests. Any modifications will dismiss approvals for the affected changes, and they will need to be approved again before they are applied.

Reviewing Change Requests

Once a Change Request has been created it will appear in the Change Requests list view with an Open status. When viewing an open Change Request, you're shown the sets of secret changes presented in a diff format. Some behavior that's worth noting:

• Secrets on the left-hand side of the diff (i.e., the current secret values) won't be visible if you don't have View Secrets access on the target config.
• Regardless of access, the full diff will not be displayed for canceled and applied changes, only the right-hand side (what was in the Change Request) will.

📘

Permissions to Review a Change Request

A user is able to review and approve a Change Request for a config if they have the Approve Change Requests permission for the target config.

Statuses

There are two types of statuses for a Change Request. The first is the overall status of the Change Request. This is displayed in the Change Request list view and can have the following statuses:

• Open indicates that a Change Request has secret changes in it that are either In Review or Draft.
• Closed indicates that a Change Request has had all changes in it applied or canceled.

The second type of status is for each of the individual sets of changes to a secret. Each set is assigned one of the following statuses:

• In Review is for when changes are ready to be reviewed. This is the default status when a Change Request is opened.
• Draft is for when changes aren't ready to be reviewed/applied. Notification emails won't be sent for changes in Draft. Changes can't be applied while in Draft, though they can be approved.
• Canceled changes can't be modified, can't be applied, and can't be approved, but can be set back to In Review or Draft.
• Applied changes are those that have already been applied to the target config. No modifications can be made to these.

These statuses exist for each set of changes for a secret in the Change Request, so you could have one secret that's in the Draft status while another is in the In Review status.

Review and Approval

Once a change to a config has been approved it can be applied. Applying a change to a config will trigger webhooks and automated config syncs in the same way saving a change directly in the config would.

1. From the navigation, select Change Requests.
2. Select the Change Request you would like to review. Change Requests with a green checkmark have already been applied. Change Requests with a gray icon have been closed.
3. You are now presented with a view of the changes to be made to the applicable secret configs. If the changes are correct for a config click the Approve button.
4. Clicking Apply to Config will apply the changes to the config. Either the reviewer or author of the Change Request can apply the change once it is approved.

📘

All changes require a single approval before they can be applied.

Rescinding Approval

Any user that has approved a change can rescind that approval prior to the change being applied.

📘

It's possible for multiple reviewers to approve a change. The Rescind Approval option is only displayed if you have approved a change yourself. Rescinding your approval might not change the overall state from Approved if another reviewer approved the change as well.

Closing a Change Request

Clicking the Close Change Request button within a Change Request will set its status to "Closed", and changes that have not been applied will be have their status set to "Canceled". A closed Change Request can be re-opened by setting the status of any change back to "In Review" or "Draft".

Create an approval workflow

Using custom roles you can require that your users make changes to secrets through Change Requests.

Create a role for authors

1. Creating a new custom project role with all the permissions your users should have, but without the Manage Secrets permission.
2. Assign the new role as the role for your users on any projects you want to enforce a Change Request approval workflow on.

📘

You can ensure your users automatically get this role on projects they're added to by making it the Default Project Role in your workplace from the Team > Roles settings page.

Create a role for reviewers

1. Create a new custom project role with all the permissions you want your reviewer users to have, including the Review Change Requests permission. If you want to prevent your reviewer users from being able to modify secrets outside of Change Requests, then be sure to exclude the Manage Secrets permission in this role too.
2. Assign the new role as the role for any users you want to be approvers for the projects you want to enforce a Change Request approval workflow on.

🚧

Default roles

Note that any user with the default Admin or Collaborator project roles will still be able to make changes to secrets without using Change Requests in that project's configs.

Additional Considerations

Activity Log

All actions related to Change Requests are visible in the activity log.

Integration Syncs

Change Requests are applied per config, so if changes impact more than one secret config in a Change Request the changes will be applied separately for each secret config. If you have integration syncs or webhooks configured for each secret config, they will trigger separately.