This article will lead you through getting your first feature(s) from your Dev Sandbox into your pipeline, and then promoting these features through your pipeline environments.

Once you have completed a feature in your dev sandbox, navigate to the Deployment pipelines page and click on your Dev Sandbox org.
​
Then select the "New feature" button: , like so:

If you have Jira or Azure work items linked then you can select a ticket.

Gearset will automatically fill in the name of the feature branch. you can edit feature branch name to fit any naming convention needed.

If you have no ticketing system linked with your Gearset Pipeline (e.g. Jira or Azure work items), then you can create and name your feature branch manually.

Once branch is named, under COMPARISON FILTER dropdown you can amend the metadata filter for your Dev org > feature branch comparison.

Optionally, you can also configure comparison date range. Before you use this setting, please check known behaviors and limitations of this feature.

In the comparison results, find the feature(s) that you have created, select the items for deployment, click on Next and go through the compare and deploy steps.

Add the changes to your feature branch via Commit changes button.

The changes are now committed in the feature branch.

Gearset will automatically take you to the Deployment pipelines page where you can see (below screenshot):

Let's dive into more details on why "changes in this branch" may display more items than the number of items you've actually committed to your feature branch.

On below example, the change committed to the feature branch (highlighted in black) contains the new field (Number1__c) initially selected for deployment.

However, Gearset's Problem Analyzers (PAs) detected that this field belongs to Account1__c object, which was new in the Dev org and didn't exist in your Main/Master branch (off which the feature branch was created), which means the object also didn't exist in the feature branch either.
​
So Gearset's intelligent Problem Analyzers automatically included Account1 object in the deployment - this object is highlighted in red in the New items section (see image below).
​
Also, Gearset detected that for a successful org deployment of the field, various Profiles and Profile: field level security components had to be included in the deployment package (these are highlighted in red under Changed items section), and our PAs did that for you! So you don't need to worry about if you miss some items crucial for a successful deployment and/or validatin.
​
Lastly, if you want to inspect further, you can find the history of your commit made to the feature branch in our Deployment history page.

After you've selected button on your Dev Sandbox, you'll see a pop up window where you can:

Once you're happy with the changes, proceed with creating the PR:

The description for your PR may be configured as a mandatory field. If so, it needs to be filled in before Pipelines UI allows you to select Create pull request.
​
This setting is controlled by Pipeline owner(s) and can be amended in the Pipeline settings, like so:

Deployment pipelines page will show you the number of PRs open against your first Pipeline environment.

Click on that icon or on the environment itself to preview the pull requests.
​

Allow some time for Gearset to run merge conflict check and validate the metadata components in the PR.

Click on the PR button and you can see its details auto populate on the side bar (highlighted in green are the optional settings):

Select the pull request (or multiple pull requests) and click Promote changes to promote your PR into the next environment.

Clicking the Promote changes button will start the CI job on the Gearset side, to:

Completed and successful org deployment (via CI job targeting INT org) is confirmed with a tick icon on the environment to which the PR was promoted.

This is also indicated by the environment changing colour from blue to green.

You can now continue to promote the changes down the pipeline, in this example into UAT and then eventually towards Production.

If there are multiple PRs opened against your environment (e.g. INT in this example), clicking the Promote changes button will initiate the promotion of the PR only if there aren't any other other pull requests already in the queue for promotion

Read more about our feature of queuing PRs for promotion in Gearset Pipeline.
​
On below video there's a PR with feature Number3.field being promoted while other PRs are pending in the queue. Any new PR that is promoted against INT will be added to the bottom of the queue.

Pipeline owners (or Team Owners in case of a team-shared Pipeline) can rearrange the PRs in the queue either by dragging PRs up and down the list (as shown on the video).

Pipeline owners (or Team Owners in case of a team-shared Pipeline) can rearrange the PRs in the queue either by dragging PRs up and down the list (as on video above), or by selecting the three dots icon: and clicking on Promote next button to move a given PR to the top of the existing queue.

While users with a Member status can remove only their own PRs from the queue (to find out more check our FAQs section related to this feature).

After your feature has made it to Production, before you start creating new PRs, Gearset recommends to always keep your environment branches in sync.

You can do it by opening sync pull requests from your Prod environment in the Pipeline. These type of pull requests sync the metadata differences and Git commit histories between your Main/Master branch and the long-lived environment branches in the Pipeline (e.g. INT and UAT branches in this example).

If you have a hotfix that needs to be quickly deployed to Prod, and want to skip promoting it through the entire Pipeline, Gearset has a solution for you!

For this type of scenario, you should have a Dev org (to serve as a Hotfix environment) added to your Pipeline that will link directly to your Production environment.

Once this is set up, you can follow a similar promotion process to when you deploy brand new features. With the only difference being that your hotfix feature is promoted directly from the dedicated Hotfix environment.

Example below shows a Hotfix environment and a feature branch that will be used for hotfix deployment.

Below steps will lead you through creating a hotfix PR:

1. Click on your dedicated Hotfix environment.

2. Click on New feature (if you haven't created your feature branch for hotfix), add your feature branch on the pop up window, select the metadata filter, and hit Compare now.
after you've run a comparison and committed your changes, you can move into the final step where you create a pull request.

Continue these steps if a feature branch where hotfix will be deployed already exists:

3. If you've already created your feature branch for hotfix, select it from the dropdown.

4. Click Commit more changes once you have the right feature branch selected.

5. Finally, click Create pull request...

Once your hotfix is merged into Main/Master branch, CI job will deploy it to Prod.

After CI job deployment is completed, Gearset will trigger back propagation PRs to your lower static environments (CI jobs in the Pipeline), such as INT or UAT (in this example).

If you've enabled Updates to Dev Sandboxes in your Pipeline, the Sandboxes for which updates are enabled will also receive updates of the hotfix deployed to Prod.

Both Jira or Azure work items integrate seamlessly with Gearset Pipelines. Gearset can update the status of a Jira ticket or your Azure work item.

When creating a new feature, you can select a a ticket that will be linked to the feature in the pipeline. It can be configured to follow all PR promotions until the feature has reached the final environment.

Details on how to configure one of the above services can be found in our documentation on: