Setting Up Workzone Cloud

Time to set up Workzone for Bitbucket Cloud!

Below is a simple step-by-step tutorial on basic settings configuration to help get you started. Once a basic setup has been implemented, we encourage you to read through all Workzone Features to assist with adding further complexity.

Using Workzone with Bitbucket Premium #

All workspaces signed up for Bitbucket Cloud Premium and using IP Allowlisting under Access Controls in the Bitbucket Workspace settings, will need to whitelist Workzone IPs to ensure correct functionality of Workzone. Please visit this FAQ page for instructions on how to add Workzone IP to your workspace IP allowlist.

Create Workzone account user and app password #

In the following steps you will

• Create and invite an account user (recommended) or use an existing user with administrative privileges to act on Workzone’s behalf.
• Set up an app-password for the account user in their personal profile settings.

Note: These steps only need to be performed once at the initial setup. Other workspaces can re-use the Workzone account user.

Setting up the Workzone account user with an app password #

1. Create an additional Workzone account email within your organisation
   • (e.g. [email protected])
2.  Using the new Workzone account email, invite a new user in your workspace and assign admin permissions.
   

Access the invitation email and click on the invitation link. Join bitbucket.org and create the Workzone account including password.

1. Log in as the Workzone account user.
2. Open your “Personal Settings”.
3. Open “App Passwords” in the left menu.
4. Click the “Create App Password” button.
5. Add “workzone-app” as the label. 
6. Add the following permissions;
   • ‘Account’:read
   • ‘Workspace membership’:write
   • ‘Projects:write’
   • ‘Repositories:admin’
   • ‘Pull requests: write’
7. Click “Create”.
8. Note down the generated app-password – you need it in the next step.
9. Click “Close”.

You can now log back in to your own admin account and continue with the steps below.

Subscription Settings #

Teams consisting of up to 5 people can use Workzone Cloud with a free subscription. However, if your team currently consists of more than 5 people, a paid subscription will need to be activated after a 30 day trial.

To ensure maximum security and ease of configuration, we use Stripe for all Workzone Cloud subscription payments.

To activate a subscription, complete the following steps;

1. Navigate to your Workspace Settings
2. Scroll down the left menu to “Subscription Settings” under the “Workzone” title.
3. On this screen, you can view your current workspace user count along with the estimated cost. Click “Subscribe” to open the Stripe payment process.

An invoice will be sent to the email address used during the Stripe Payment process. The email address used does not need to be the same as the Atlassian account email being used.

You can choose between a monthly or yearly billing option via the two tabs. 

App Settings #

Performance parameters #

You can ignore these settings during setup and use the default values provided.

Credentials for Workzone #

Use Credentials for Workzone to save the Workzone account user name and app-password for Workzone you have created in step 1. Workzone needs to know the username and app-password to act on behalf of the account user. Note the app-password cannot be used to take over the account or compromise the account in any way and the app-password is stored encrypted.

1. In your admin account, navigate to your workspace settings.
2. Scroll down to “App Settings” under Workzone in the left menu.
3. Add in the new Workzone Account Username – Please refer to the “Finding Account Username” section below to ensure the correct details are entered. 
4. Add in the Workzone Account App-Password from the previous setup.
5. Click “Save”.
6. Click “Test” to confirm credentials entered are correct.

Credentials for Workzone Continued – Finding Account Username #

If you are encountering issues when entering the Workzone Account Username fields, this could be due to entering the account email instead of the account username. To find the account username, please follow the steps below. If you have already successfully entered the Credentials for Workzone, please continue with the “Repository brand restrictions settings” section below. 

1. Log in as the workzone account user and go to Settings > Personal Bitbucket settings

2. Find the Bitbucket username under the “Bitbucket profile settings” on the Account settings page.

3. Use the Bitbucket username to configure the Workzone account in Workzone app settings as per previous instructions.

Repository branch restrictions settings #

In order for Workzone to control the pull request merge process and enforce the configured merge-conditions it is recommended to add repository branch restrictions for the same set of branches that have a Workzone reviewer and merge configuration in the workspace. This way only Workzone can merge pull requests when all conditions are met.

1. Navigate to your Repository settings. 
2. On the left menu, open “Brand restrictions”.
3. Click “add a branch restriction“.
4. Add the same branch as used in the previous step, e.g. “develop“.
5.  Select “Only specific people or groups have write access”. Leave blank.
6. Add in the Workzone account user set up from the earlier steps, e.g. “Workzone for Bitbucket”. 
7. Click “Save“.

Note: Bitbucket Premium is no longer needed when using Workzone for Bitbucket. You can configure granular reviewers & merge checks when in the Workzone Settings in the following steps.

Workzone repository settings #

Important: Workzone Repository level settings will override the Workzone Workspace level settings. The following examples include screenshots within the Repository settings. If configured Workzone will apply these settings to all pull requests in the repository when they are created. Configurations include:

• Pull request target branch
• Merge options
• Reviewers
• Approval quota
• File/module patterns

Workzone repository settings override any workspace wide settings.

1. Navigate to your Repository settings.
2. Scroll down and open “Repository settings” in the Workzone section.
3. Add in the desired Destination, e.g. “release”.
4. Add in the desired Reviewers, e.g. “Developers”.
5. Add in the desired Quota, e.g. “50%”.
6. Add in the file pattern if required, e.g. “src/main/**”.
7. Click “Save“.

Inherit Workzone settings from Project or Workspace Level #

You can choose to inherit your repository level settings from your project level settings, and then again inherit your project level settings from your workspace level settings.

1. Navigate to your repository settings
2. Click on the “Repository settings” button in the Workzone section
3. Click the “Reset to project” button.

If you need to decouple the repository settings from project settings, click the “Decouple from Project” button.

If you need to decouple the repository settings from workspace settings, click the “Decouple from Workspace” button.

It is important to note that only Project or Workspace admins have the ability to enable inheritance at repository or project level

• If Workzone is configured at workspace level, all repositories inherit the settings
• If Workzone is configured at workspace and project level, all repos under the project inherit project settings, all other repos inherit workspace settings
• If Workzone is configured at repository level, no other settings are inherited from project or workspace level
• Decouple projects from workspace to add project settings.
• Decouple repositories from project or workspace settings to add repo settings
• Reset project settings to workspace settings to inherit workspace settings for projects
• Reset repo settings to project or workspace settings to inherit the respective settings.

You’re all set up!

To learn more detail on the features and functionality, continue on with the feature guides below.