Getting started with ScratchOrg Pooling
Salesforce snapshot is delayed by couple of releases making scratch org based Pull Request validation an incredibly painful affair after the project has grown into some size. It is also difficult when large managed packages are involved. This command presents an interim solution to reduce the time to create a just in time Scratch Org by creating a pool of scratch org's ahead in time usually using a build server.
Please note to get this solution working, additional fields, validation rules, and flows need to be deployed to DevHub. This involves storing the password of generated ScratchOrg. We recommend utilizing the 'user mode' option for additional security, where each if the listed user have to verify their email to consume the ScratchOrg. To use the generated ScratchOrg in Build servers, utilize the JWT grant method utilizing the same credentials used to authenticate devhub to authenticate to these ScratchOrgs.
Here are the steps to getting started
Visit Installation instruction
Ensure modify all permission to ScratchOrgInfo object is added to the DX permissionset or profile that is being assigned to you developers. Also ensure the required permissions are set for the new fields being deployed.
TODO: Additional review needed to align this to dxatscale/sfpowerscripts Pool Configuration Schema File. Review and align to GitBook.
A pool configuration file is required to define the shape of a scratch org pool, including its identifier, size, and expiry. For a full list of options, please refer to the table below. You can also find a detailed explanation of the schema here, and example configuration files at schemas/pool.
| Field | Type | Description |
|---|---|---|
| expiry | Number | Number of days after which the pooled scratch org will expire |
| tag | String | (Required) Identifier for the pool created |
| max_allocation | Number | (Required) Size of the pool, ignored if pool users are specified |
| config_file_path | String | (Required) Path to the scratch org definition file |
| script_file_path | String | Path to a script file to be executed e.g. to install dependencies in scratch orgs. Currently supports batch file or shell scripts which gets executed by cmd or bash respectively. The script will be passed two arguments the scratchorg username and devhub username respectively as %1 and %2 |
| relax_ip_ranges | Array | Relax IP address ranges from which clients can access created scratch orgs. |
| relax_all_ip_ranges | Boolean | Relax All IP address ranges from which clients can access created scratch orgs. |
| poolUsers | Array | List of pool users and their min/max scratch org allocation, expiry, email and priority |
If neither IP ranges or pool users are specified in the pool configuration, then pooled scratch orgs will only be accessible through JWT authentication or the AuthURL (provided pool was created by a user who has authenticated to the DevHub using sfdx:auth:sfdxurl:store).
Run the following command to create a scratch org pool by passing in the path to the pool configuration file and the DevHub. You might need to run this command in a scheduler to maintain a healthy pool for your CI server. We recommend you utilize sfdx:auth:sfdxurl:store while authenticating to DevHub to enable a seamless experience while fetching ScratchOrg from the pool
sfdx sfpowerkit:pool:create -f <config_file_path> -v Devhub
The sfpowerkit:pool:fetch command is used to fetch a scratch org from a pool.
sfdx sfpowerkit:pool:fetch --tag my_pool -v Devhub
The sfpowerkit:pool:fetch command can be used to fetch a scratch org from a pool on-behalf of a user. The scratch org details with username and password will be sent to the user email, by using -s | --sendtouser flag with devhub username of the user on-behalf the fetch is used.
sfdx sfpowerkit:pool:fetch --tag my_pool -v Devhub -s testuser@test.com
For the CI use case, the following mechanisms are available
- Authenticate to the fetched scratchorg using JWT using https://test.salesforce.com as the instance URL. Follow this Blog for more info
- Or, ensure the scratch org pools is created using a user who is authenticated to DevHub using sfdx auth:sfdxurl:store, this enables the scratch orgs to be auto authenticated
When using Free Limited Access License or developer profile in DevHub, developers may not have access to the scratch orgs created in the pool by Admin/CI user. In such case Create two public group
- CI_Admin ( Admin users/ CI users who creates scratch orgs in pool)
- Dev_pool (developers who are allowed to fetch scratch orgs from pool), Then create a below sharing rule.
Utilize further commands such as sfpowerkit:pool:list and sfpowerkit:pool:delete to manage the pool.