What determines what shows up in the "Commits in this branch" panel?
The Commits in this branch panel shows the net new commits in the feature branch selected on your Dev Sandbox. These are commits that don't exist yet in the next downstream branch.
For example, the panel below says "No commits were detected in this branch". The feature/Account.updates branch is in sync with the INT branch (the next environment in the Pipeline), so there are no new commits to show.
After you commit more changes to feature/Account.updates, and before those changes reach INT, the new commits show in the Commits in this branch panel.
How can I check that the webhooks for pipelines are configured?
Gearset's pipeline functionality relies on webhooks from your Git provider. These webhooks tell Gearset when to trigger jobs.
To check if the webhook for a CI job in the pipeline is set up, click Webhook setup... for that job on the CI dashboard.
You can also check the setup in your Git provider. Example from GitHub:
The individual webhooks that Git sends to Gearset also show in the Recent Deliveries section. In GitHub, go to Webhooks, click Edit, then open Recent Deliveries.
If a job hasn't triggered, start by checking whether your Git provider sent the webhook. If it did, send the webhook's timestamp to our support team. We can then check what happened after Gearset received it.
Note: Any new CI job set up after August 2023 tries to join an existing webhook pool, instead of always creating a new 1-to-1 mapping. When you troubleshoot, make sure you find the webhook for your job.
For more information, see CI job and pipeline webhooks.
Check Pipeline webhook errors
On the Deployment pipelines page, select View webhook errors. This shows a list of new and previous webhook errors for your Pipeline.
Note: If the webhook didn't fire, the error doesn't show in these logs. That is an issue on the Git side, not the Gearset side.
What is the purpose of the Developer Sandbox compared to static environments?
A Developer Sandbox is an environment that lets you and your teammates get changes into the Pipeline.
It's one of three entry points. The other two are the Compare and deploy flow, and creating a pull request directly in your version control system (for example, GitHub or Azure DevOps).
The typical workflow is one of these:
You work on your feature (for example, in VS Code) and push the changes to a feature branch.
You make the changes directly in a Dev Sandbox org, then push them to a feature branch from the Developer Sandbox environment in the Pipeline.
To create a new branch, select New feature. To add more changes to an existing feature branch, select Commit more changes....
Creating a pull request
When your changes are in a feature branch, select Create a pull request... in the Developer Sandbox environment. This opens a pull request that targets the next static environment in your Pipeline (for example, the INT environment above).
Note: You can swap the feature branch on the Dev Sandbox at any time. Think of feature branches as "short-lived" branches. They're deleted after the feature goes through the entire Pipeline to the Prod environment.
Static environments and "long-lived" branches
Static environments use "long-lived" branches, and your CI jobs use these branches. A long-lived branch represents the current state of an environment, for example STG (Staging), INT (Integration), UAT (User Acceptance Testing), or Production.
Can Gearset propagate changes through a Pipeline using the original pull request author?
Yes. Gearset can keep the original PR author when it propagates changes through a pipeline.
This feature supports GitHub, Azure DevOps, Bitbucket, and GitLab. For more, see Why are my PRs showing the pipeline owner?
Note: If you have a long-standing pipeline, re-authenticate your Git provider on the Source control and services page for this to work.
Can I use "Squash" or "Rebase" merge methods with Pipelines?
No. Gearset Pipelines only supports merge commits.
Depending on your version control system (VCS), you can merge changes into target branches (the source branches of your CI jobs) in different ways. These are usually "merge commit", "squash", and "rebase", as explained in the GitHub article About pull request merges.
Squash combines your pull request's commits into a single new commit hash, then layers it onto your target branch.
Rebase creates new commits to layer onto the target, so you can't tell when a feature was merged. For more detail, see the Atlassian article Merging vs. rebasing.
Gearset Pipelines is compatible only with merge commits
Gearset Pipelines keeps an accurate comparison of the commit differences between your feature branches and your long-lived environment branches. This allows back propagation and makes drift easy to find as new features pass through. Because of this, merge commits are the only method compatible with Pipelines.
Merge commits are the default for most version control systems. If you think your repo uses a different setting, check it before you use Pipelines. Other merge methods can cause unexpected behavior with Pipelines synchronization.
What about fast-forward merging?
Some version control systems also offer "fast-forward" merging, as explained in the Atlassian article Git merge.
A fast-forward merge moves the tip of the target branch (an environment branch, like main) to the tip of the source branch. It's only available if the two branches haven't diverged. That means no extra commits were added to the target after the feature branch was created.
Why fast-forward merging isn't supported in Pipelines
Fast-forward merging breaks the isolation between the commits in the original feature branch and any other commits on the target branch. This can back-propagate unexpected commits and files to other environments.
Can I see who owns the Pipeline?
Yes. On the Deployment pipelines page, click the Pipeline dropdown icon. You can see both user-owned and team-shared Pipelines:
User-owned Pipelines show who the Pipeline owner is.
Team-shared Pipelines aren't owned by a single Gearset user. All the team Owners on your Gearset team own them.
Why can't I select the "Promote changes" button in the Pipeline?
The Promote changes button is usually disabled because of one of these:
The Gearset license assigned to the user
The org access given to the user
The user's permission on the CI job used in the Pipeline
When you try to promote changes, you may see this message:
"You can't promote changes because you haven't been assigned Run permission to this job, or one or more connections have been deleted".
Note: Promote changes also triggers PR validation. Only pull requests that pass validation can be promoted. To trigger PR validation again, a Gearset user needs at least the Validate permission on the CI job for that Pipeline environment.
Expand the resolution for your Pipeline type below.
Resolution for team-shared Pipelines
Resolution for team-shared Pipelines
This usually happens because the user who tries to promote changes doesn't have the Run permission for the CI job (Pipeline environment) that the PR is open against.
To fix it, go to the Pipelines & CI job page and select the team-shared Pipeline that the CI job belongs to.
Then find the CI job (in this example, the UAT job). Make sure the user who tried to promote changes is added to the job and has the Run permission.
The video below shows how to add a new user to the CI job and assign the Run permission.
Resolution for user-owned Pipelines
Resolution for user-owned Pipelines
A team member who isn't the Pipeline owner may try to promote a PR to an environment. The Promote changes button is then grayed out, and this message shows:
"You can't promote changes for one of the following reasons: You may not have an Enterprise license, the org connection could have been removed, or you do not have delegated access to the org."
To fix it, the owner of the org connection must give Deployment level access to the org to the user who wants to promote the PR. Do this on the Delegate org access page. In most cases, the Pipeline owner also owns the org connection used for the environment (CI job).
For more, see Sharing org credentials with team members.
Note: "Comparison" or "Validation" level access doesn't let other users promote PRs to Pipeline environments.
Why is the "Commit changes" button grayed out?
The Commit changes button may be grayed out because a team setting requires issue tracking. When this happens, you can't commit more items to an existing feature branch.
To continue, link your commit to an issue (for example, a Jira ticket). Or a Team Owner can turn off the Issue Tracking setting if your team doesn't need it.
Why is the "New feature" button disabled for some users on the team?
The New feature button may be disabled (grayed out) for some colleagues who work on the same Pipeline. This is usually because of the user's permission level for the Pipeline environment. When they hover over New feature, they see this message:
"You can't create a new feature for one of the following reasons: the org connection could have been removed, or you do not have delegated access to the org."
Resolution for a user-owned Pipeline
Check whether the user is trying to create a new feature from a Dev Sandbox that belongs to another member. Users can create a new feature from the Dev org assigned to them, but may be blocked for all other Dev orgs.
To let a user create features from a given Dev org, the Pipeline owner (or the owner of the Dev org connection) must delegate org access to the user and give them Deployment access to the org.
Note: "Comparison" or "Validation" permissions aren't enough. For more, see Sharing org credentials with team members.
Resolution for team-shared Pipelines
Any Team Owner on your Gearset team can go to the Delegate org access page and give the affected Member Deployment level access to the Dev org.
Note: By default, any Member on your Gearset team should be able to select New feature in Pipelines. This doesn't depend on their access level to the team-shared Pipeline (for example, "View" or "Edit"), or their permissions on the CI job linked to their Dev org (for example, "Edit" or "Run").
Why is my Pipeline environment highlighted in red or yellow?
This usually means the most recent deployment to the org failed. It doesn't block your Pipeline from future PR merges or CI deployments.
What is the default behavior?
The status clears after the next successful deployment to the org.
Can I manually clear this notification?
No. You can't manually clear the yellow or red status from a Pipeline environment.
Do you see a yellow exclamation mark on your environment?
Do you see a yellow exclamation mark on your environment?
This usually means the deployment was partially successful.
For example, a PR promotion includes both metadata and CPQ config data. The CI job deploys the metadata, but doesn't deploy all the CPQ data.
Do you see a red cross on your environment?
Do you see a red cross on your environment?
This usually means the most recent deployment failed, and nothing was deployed to the target org.
A common example is a CI job that tried to deploy only metadata items.
Why is my open PR not automatically validating?
Your PRs aren't automatically validated because the CI job for that Pipeline environment doesn't have the Validate pull requests targeting the source branch setting turned on. This can affect the first environment in the Pipeline or any downstream environment.
In this case, you see this message under Manual validation:
"PRs aren't automatically validated in this environment".
How to turn on automatic validation
Pipeline owners can change this setting on the Deployment pipelines page (for example, for the INT environment below):
You can also turn it on from the CI dashboard. Click Edit settings, then open the Deployment behavior tab.
After you turn on the setting, Gearset automatically validates the next PR opened against that Pipeline environment. For PRs that are already open, trigger the validation manually.
Why aren't pull requests in "Promotion history" sorted by the date and time they were merged?
This usually happens only when some PRs were merged directly in your VCS (for example, GitHub, Azure DevOps, or Bitbucket), instead of in the Gearset Pipeline.
When you merge PRs in your VCS, delays in webhook processing can make Gearset merge your PRs in a different order from the order they were promoted to the Pipeline environment. The PRs then show in an unexpected order on the Promotion history tab.
Note: When you promote a PR through Gearset, Gearset locks the target environment. No other user can take actions on that environment (for example, PR merges) until your PR is deployed or fails validation.
To keep the Promotion history tab consistent, promote PRs only in Gearset.
Why does the "Promotion history" tab not show all the merged PRs?
The Promotion history tab for a Pipeline environment shows a PR only if both of these are true:
The PR was promoted in Gearset.
The PR wasn't deleted from your VCS (for example, GitHub, Azure DevOps, or Bitbucket) after it was merged.
Why shouldn't I delete merged PRs from my VCS?
Gearset needs merged PRs to stay in your VCS to show them on the Promotion history tab. If you delete a PR from your VCS, it no longer shows in the history of any environment it was promoted to.
Can I edit the pipeline settings while a CI job is running?
No. You can't edit Pipeline settings while CI jobs are in progress. You can still view the Pipeline details:
Note: You shouldn't need to update your Pipeline details while work is in progress (for example, while CI deployments run against the target orgs).
What happens if a CI job is paused during a PR merge?
If a CI job is disabled while a PR merges, the PR merges into the branch, but Gearset doesn't validate it or deploy it to the target org.
Don't disable CI jobs while PR validations, PR merges, or CI job deployments are in progress.
What do the different "gs-" branch prefixes Gearset creates in my repository mean?
Gearset creates and manages branches with a gs- prefix as part of various Pipeline features. Each prefix is described below.
Note: Don't commit directly to gs- prefixed branches. Gearset handles their lifecycle for you, and direct commits can cause unexpected behavior.
gs-pipeline/
Promotion branches in the standard (expanded) branching model. When you promote a feature to an environment, Gearset creates one of these branches. This lets you resolve merge conflicts without affecting the original feature branch or other downstream environments.
Format: gs-pipeline/<feature-branch-name>_-_<env-branch-name>
Example: gs-pipeline/add-field-to-account_-_staging
For more, see The Gearset Pipelines branching model.
gs-bundle/ and gs-bundle-base/
Used by the Releases (Bundles) feature in Pipelines:
gs-bundle-base/<guid>_-_<env>represents the pure state of a release bundle.gs-bundle/<guid>_-_<env>is the promotion branch used to promote that bundle to an environment. Gearset keeps it in sync with its base branch.
Note: Don't commit directly to either branch. Manage and promote releases in Gearset. For more, see Releases in Pipelines.
gs-gitflow-release/ and gs-gitflow-baseline-release
Gearset creates both branches when you use a Gitflow Pipeline, but they have different roles:
gs-gitflow-release/<GUID>is a short-lived release branch. Gearset creates one automatically each time you open a release from yourdevelop/integrationbranch. It's used for validation, testing, and any required hotfix commits before it's merged intoMain. Several of these can exist over time (one per release).gs-gitflow-baseline-releaseis a single, permanent baseline branch. Gearset creates it the first time you add a static environment to the Release & Testing stage of a Gitflow Pipeline. Gearset uses it to run a baseline CI job, so release-branch deployments can use Delta CI. There is only ever one of these, and it doesn't follow a/<GUID>pattern.
Note: Don't edit or delete gs-gitflow-baseline-release manually. If you need to recreate the release environment, delete this branch in your VCS first, then create the new CI job.
For more, see the Gitflow in Gearset Pipelines collection.
gs-project/
A project release branch created by the Long term projects in Pipelines feature.
When you create a release from a long-term project, Gearset creates a gs-project/<GUID> branch for that slice of accumulated work. The branch then moves through the rest of the Pipeline like any other release. It goes through your testing environments, then it's merged into Main and back-propagated.
This branch is not a permanent parallel to Main. It only exists for the lifetime of a given long-term project release.
Format: gs-project/<GUID>
Example: gs-project/ef0a254d-778d-4386-93cd-713024fefbcf
You may also see composite promotion branches like gs-pipeline/gs-project/<GUID>_-_<TargetEnvironment> as the release moves through environments.
For more, including a workflow diagram of the release flow, see Long term projects in Gearset Pipelines.
gs-sandbox/
Created by the Developer Sandbox Updates feature to track sandbox state when you sync Developer Sandboxes against a target. You may see child branches like gs-sandbox/target and gs-sandbox/current.
For more, see Getting started with developer sandbox updates in Pipelines.
How do I add metadata types that already exist in my orgs, but aren't tracked in Git, to my Pipeline without redeploying?
For step-by-step guidance, see Adding previously missing metadata types into Gearset Pipelines.
What else should I be aware of?
Merges done outside Gearset (in your source control) don't show in the Pipeline's promotion history.
Pipelines (and their CI jobs) don't work with forked repositories where feature branches are raised from the fork to the main repo. Gearset needs the source branch to be in the same repository to track commits.
If you get stuck, please send a message to our support team, who will be happy to help.