Description
Learn to tackle common Gearset pipeline challenges and the easy steps to prevent them.
Transcript
Awesome. Let's get going. Well, hello, everyone, and welcome to the final session in the GearSat pipeline accelerator series. As a quick introduction, I'm Maroof, and I'm here with Charlie today. We're part of your customer success team here at GearSat.
We're also joined by Antonio, who's one of the onboarding managers, and Antonio is here to answer some questions you folks might have for us. Today, we're gonna be talking about keeping your pipeline in good working condition and some frequently asked questions. So I'll let Charlie speak about that in more detail.
But in the meantime, I just wanna say, if you folks have any questions, please do drop them in the chat today. We'll be taking some short breaks in between each slide, so, that will allow you to ask any, questions you might have on the topics that we cover. So please do throw them in, and we'll do our best to answer you. Now before we get going, just a quick announcement.
Some of you folks might have heard this last week, but our product team are currently working on making the pipeline setup process easier. Now you may have already heard from them, but if you're interested in chatting with us, then please do get in touch. If you haven't received an email from them yet, then please do let us know. And if you're interested, we'd love to hear from you as your input will play a huge part in helping improve gear set for everybody.
And with that, let me hand over to Charlie.
Hello.
Let me share my screen quickly.
Can we all say, see that alright?
Good stuff. Okay. So as we've said, I'm Charlie.
Today, we'll be covering kind of FAQs and common issues that we often see within pipelines.
By the end of the session today, you should feel confident in working out why these common issues are happening, how to resolve them, and, keep the pipeline in good working condition.
This is the, final session of the webinar series. We've covered the setup of the gear set pipeline, effective pipeline use, and also now how to resolve those kind of common issues that we often see. This session is aimed to be slightly more interactive, as Marouf said, than the last two. So if you do have any questions, do please let us know.
And with that, let's make a start.
So to begin with, this is the list of all the questions that we're gonna answer today, and talk through as a bit of an agenda. If you can think of any questions immediately about these ones, be sure to let us know in the chat, as I said, and we'll try and answer them throughout. So what are the questions? Firstly is, why are there other user stories in my pull request? Why am I seeing extra commits in my pull requests? Why are PRs not opening against the next environment?
Why have some other items in my PR not been deployed? What are the extra PRs that I see in my version control provider? And finally, how to fix a feature that is already in flight?
Okay. So let's make a start.
First issue that we're going to cover is as a result of the question at the top there. So why are there other user stories in my pull request?
So this is as a result of not opening, your feature branches from main.
Now why would you open your feature branches from main? So main is your source of truth, which is in sync with production. It doesn't include untested features or work in progress. Let's say you've worked on feature a, which is now in your QA environment for testing. If you create a feature branch from a lower environment to work on feature b, for example, in your QA branch, when this feature branch is merged into UAT, it will include all of the work in progress on feature a that still might be untested.
Now organizational best practices and what they are. So feature branches should be small features and short lived, split into small deliverable chunks of work. If the work is too large and it spans a few weeks, perhaps, then it may need splitting down into further, kinda chunks to streamline the usage.
In the case of kinda common metadata, types across across multiple stories, user stories should be grouped depending on the metadata types so they can be assigned to a particular team or a particular developer who will have more visibility of changes that have gone into each feature or story and will have more control on managing merge conflicts themselves.
The result of both of these points is that you will be what building new work only on features that have been tested already as you have branched from main, which is the most up to date version of the metadata.
And, also, merge conflicts and other kind of inconveniences will be limited due to user stories being focused on small deliverable chunks, which are easier to test and review.
Were there any questions about that? Maroof, did we have anything in the chat?
Haven't had anything come through, but we can give give folks a few seconds if they've got any, questions they'd like to pop in at this stage.
No worries.
As you can see on the kind of screenshot on the right, that's within the pipeline settings. So you can see default base branch from new feature for new feature branches, and that is selected as my main branch.
We'll see how long I can leave it before I Yeah.
We're not seeing anything come through, Charlie, so I think we're good to continue. That.
Okay.
So the second question that we often get is why am I seeing extra commits in my pull request?
So to start with, as I mentioned, main should be the source of truth as we've discussed in the previous webinars. You might you might notice that it's quite important because I keep banging on about it. But once, main's kind of seeded from production, needed changes should pass from it first, and then the environment branches are created as clones of main.
So the branching strategy behind pipelines is based on opening PRs always from the original feature branch. That means that the same change, for example, a new field, is merged into different branches with different commits.
Commit numbers are unique.
So Git will consider different commits as branches drifting apart, meaning that within gear set, the branches are not in sync with main. I'll show a screenshot on the next slide to kinda understand that further.
So these extra commits and metadata in each PR could lead to merge conflicts, which are avoidable as these metadata items should not be in the PR in the first place. They kinda create extra work that is unnecessary and could cause confusion.
So what we we recommend at the end of each release domain is to use the sync button in each environment to realign those commits. This will automatically open a PR from main into the environment branch. The CI jobs will be triggered, but you shouldn't actually expect any file changes to show as the metadata will not be deployed as it's already present in each environment and environment branch.
What you can see here is that particular, commit. So that is unique and id identifiable, kind of mixture of number and letters.
As I said on this slide, I'm gonna kinda dive into this a bit deeper.
What you can see here is the branching strategy behind gearset pipelines.
So I've opened my feature branch off of main right here at the start, and then I've made a commit from my dev sandbox.
I've then opened a PR against the QA branch, which is what you can see here. And once those kind of validations and checks have taken place, the PR is then merged into the QA branch. But with this merge, there is a merge commit as you can see by the c one in the green.
After the CI job is kinda kicked off and runs, those changes are then deployed into the QA environment.
This PR is then opened against the UAT branch. The validations and things happen again. But what you can see here is from a git behaviour, c two is another additional merge commit because it's seen as a new commit.
This process is then carried on throughout here, until you reach the main branch where you'll see that final kind of c three commit as well.
So at each stage of the process, an additional commit is being made throughout the, environment branches.
So what you can see is that c two and c three will not be found in the QA branch as they've been made after, this merge has happened, and c three will not be in the UAT branch because, it's happened after that merge has been, carried out.
So what I'm gonna do now is to try and, like, bring this to life and give you an example, of what this does look like within Gear Set. I'm gonna show you a little video, and I'll skip to about forty seconds.
So just a bit of context, what I've done here is I've opened a feature branch off of main. I've made a commit, and this is what it looks like in the pre deployment summary.
So as you can see, I've only made a change to one custom object. So that is AI evaluation, quite kind of, relevant at the moment, and then I'm gonna add my commit message and then commit those changes.
Apologies for my slow movement on the on the video.
What I'm doing here is creating the pull request, for that feature branch, and then I am going to refresh the page, hopefully. Yeah.
So if I just pause it there, as you can see in this PR here, what I did before was only make a change to that one individual custom object. But you can see that the changes in this PR are showing, another change that I didn't actually make in that commit.
Additionally, you're also going to see extra commits in the PR as well. So this is because following kind of a release to production, I didn't sync those environment branches, and therefore, the commits and, commit histories are out of sync as they are from a different feature branch.
So I'm gonna go on to the next slide.
So what I've gone ahead and done following this is press the environment sync button, which you can see here at the top. And after, as you can see from this PR, the only changes that you can see in the PR is that AI evaluation, custom object, which is now open against the UAT environment.
Whilst nothing's changed on the metadata side of things, the commit histories of the two branches have been aligned, and, everything should look how you expect it to look like.
Did we have any questions on that?
We we had a question a little earlier on, around so the question was best strategy to sync main branch with changes made in production, like adding validation rules or fields. Antonio, do you wanna expand on that?
Yep.
Ricardo was also asking for a follow-up, asking a follow-up, question. So, if there are changes that for some reason I had to make directly into production, I need to then identify those changes, commit them to a feature branch, and then I can merge that feature branch into main. That will trigger the back propagation to the lower environment. The sync button that you have shown now can also be used to speed up the process because we'll open a pull request from main into the lower environment. So back propagation works one, environment at a time. The sync button will take those changes, into the lower environments, with a will open up a request into the lower environments altogether.
The result, if the change is made directly in production, is that the back propagation or the sync button when merged will trigger the CI job. They will take those changes those changes also to the, orgs.
So that is a way to propagate the changes both in the branches, but also in the orgs.
One extra note on that is that if, you have metadata types that you change mostly live into the org, it can be list views, it can be dashboards, reports, and they are changed directly from the from ten, from the salespeople, for example, it means that probably you might not want them to be part of the pipeline because, they are not changed with that ticket or user story. They have changed just by the front end. So if that is happening frequently, it means that you might want to remove those type of changes from the pipeline directly.
And just as you're speaking, Antonio, we had another question come in asking, so after each PR deployment in each environment, we need to push the sync?
Just when you merge into main. So you go through the all the environments.
When you merge into main, you can click on the sync button.
Are all the branches in all environments will be synced? Yes.
Only when you, finally in the diagram that we've seen before, when you do the merging domain, that is when you click on the sync button. So, basically, after every release domain, we recommend to click on the sync button to rebring the pipeline to an ideal condition when all the pipe when all the branches are in sync in terms of commits.
Thank you, Antonio.
Not seeing anything else come through, but, folks, please do continue to send in any questions you have. But, Charlie, I think it's fair enough to hand of hand this back to you.
Fantastic. Thanks for the questions both, and thank you, Antonio.
So onto the next slide. So the next slide is why are my PRs not opening against the next environment?
So remember when we set up the CI jobs last week, they were set up the CI job webhook, sorry, last week, they were set up automatically.
However, as we spoke about in the first webinar, if my user did not have the relevant permissions within our chosen Git provider, the webhooks will not have been automatically created. And in turn, you will only have the instructions for how to do it manually as shown in the screenshot on the screen there.
So if a PR does not open automatically, it may be that the webhooks were not created automatically or manually. Do bear in mind that doing it manually may have some kind of human error, and therefore, it may not work. So we recommend to set them up automatically if that is possible.
So the slide I'm showing you now is essentially there are kind of three troubleshooting steps that you need to carry out if a PR is not opening against your next environment.
Firstly, check if the webhooks were created on setup of the CI jobs and the pipeline.
Secondly, check that your user within your version control has the permissions to set up webhooks.
And finally, if not, create the webhooks automatically or manually depending on the outcome of the first two.
Were there any questions on that?
Bit of a quicker slide.
Haven't had anything come through just yet, Charlie.
Just give people folks a few seconds if they'd like to pop anything in the chat.
There we go.
So we've just had a question come through. So we have CICD pipeline. It works fine, but after each deployment, we have to activate Velocity data pack. Can that be auto activated?
It is possible to activate Velocity data pack. But probably before this, it's better to reach out to the team and see specifically what element of the velocity data pack you need to, activate. But, yeah, probably this requires a bit more investigation on what exactly you need to activate.
Yeah. So thank thank you for your question. Yeah, we want to as Antonio mentioned, we want to give this, answer the the justice it deserves. So before prediagnosing anything, we'd love to chat to you further, understand what's happening, and, be able to solutionize for you off the back of that understanding. So we'll keep a note of this and reach out to you separately after the call. But thank you for your question.
Okay. Okay. Yep. Charlie, go ahead.
It's good to go.
Okay. So the next point is, why have some of the items in my PR not been deployed? So there's a few reasons for this.
Firstly, we're gonna talk about filters.
As we discussed in the first webinar, you want your CI job filters to include all the metadata types that you know you will be working on. If you do not do this, the result of which is that item will not be deployed even if it is in the PR.
An example of this is you include a custom object in your initial commit. And if you do not have, your CI jobs filters set up to include custom objects, then that metadata item will not be retrieved or included in the CI job. This applies the same for managed packages. If they're not included in the CI job filter, then they will not be picked up.
So on the right hand side, you can see a screenshot of the CI job settings.
Let's say I didn't have custom object ticked there and I made a commit with, custom objects, within that initial commit, then this CI job is not going to include those custom objects and therefore not be deployed.
Additionally, if I don't have if I have include managed packages selected to none and I am trying to, commit those managed packages, then the CI job will not pick those up either.
A kind of a second or, well, third, facet of this point is that if you do not tick one of the boxes in the CI job settings, as you can see on the screenshot in the bottom right, what I've highlighted in the screenshot is the category of changes that you can include in a CI job.
For example, if you want new changes to be included, things that are in your source and not in your target, then you will tick this box.
However, the most common example we see of this is with deleted items.
If you do not tick this box on CI job creation, then destructive changes will not be carried out throughout the pipeline.
Meaning, often we see people trying to push destructive changes through the pipeline. However, they end up not being deployed, as they do not have this object, this option selected. So that's just something worth noting.
So part two of this slide, it of why have some of the items in my PR not being deployed.
So the first bit of this is, as you can see, is the dot force ignore slash git ignore files. Now this is a slight more technical issue, but one that we see every now and then. So when the source of your CI job is a git branch, like within pipelines, it's possible that the metadata you're expecting to be deployed is referenced in the dot force ignore file within your git repository.
Removing that metadata from the dot force ignore file will allow you to it will allow the CI job to deploy that metadata component to the target org org on your net next CI job run.
As I said, this is a less common, kinda issue. But if you are aware of a dot force ignore file, then this could be a possible reason as to why this is happening.
And then as you can see here, the final reason or, that the issue could be caused is problem analyzers.
So problem analyzers are Gearset's kind of intel intelligent suggestions for your deployment package. Their intention is to suggest you to add or remove any components that will help to make your deployment and its validation more likely to succeed.
Within a manual compare and deploy, you can choose to untick or tick any of these suggestions in order to modify your package. However, within CI jobs, the suggestions will always be accepted, which may add or remove components to the final deployment package.
If you would like to verify that problem analyzers are the reason that your item is not being deployed via the CI job, you can view the problem analysis results for the CI job run as shown in the screenshot below.
If it's a kind of recurring issue in the CI job settings, there's an option for you to change the problem analyzer used by the CI job through editing the problem analyzer custom template, or you can also choose to not apply any problem analysis fixes. Just be aware of doing this because they are there for a reason. But editing the problem analyzer custom template should be, should work okay.
Have we had any questions on this, Maroof?
Haven't had anything come in just yet.
Give, give folks couple of seconds if they'd like to throw anything in at this point.
What I'm gonna do in the meantime is just to kind of get started.
I'm gonna post a link to answer one of the questions. Of course, as we mentioned, we will, reach out to you to discuss this further. But in the meantime, we're gonna post a link in the chat, and, this should hopefully give you some sort of answers so you can get started.
So there, hopefully, I'm hoping you folks can see something in the chat.
If you can't, do let me know.
I can see it, Marif, so I think we should be okay.
Awesome. That's a good start.
Oh, okay.
Well, I in that case, how about now? Has that answered?
Hopefully, that's visible to everyone.
Awesome. Well, we haven't had anything come in in the meantime. If that document isn't with you by now, please do let me know again, and we'll be sure to get that out to you ASAP. But, back to you, Charlie.
Thank you.
Okay. So the next issue is, what are the extra PRs that I see in my version control provider? So kinda why speak about this?
What you can see in the first screenshot is the actual behind the scenes branching strategy that Gear Set carries out. So these dotted lines are promotion branches, which I'll explain shortly.
Now for those that like to follow what is happening from your version control provider, you'll notice that Gearset creates PRs, from the feature branch as you can see here. You'll be able to tell if we've created it because it says GS pipeline there. So that is what you'll see within your version control provider.
I'll just go on to the next slide. So I'll briefly explain why this happens. So if a merge conflict does happen and it needs to be resolved, following the resolution, the source branch changes, I e, the feature branch as well as the target.
This is because a reverse commit a reverse merge commit is created when a merge conflict is resolved as shown by the screenshot.
So you can see in the screenshot with the purple commits, these aren't meant to be in the feature branch at the bottom. However, because there's been a conflict here, there's been a reverse merge commit, and these, these purple commits have polluted this feature branch here. Meaning, if I move this feature branch forwards quicker than this here, that will then kind of pollute and move those untested changes potentially, before they're meant to be moved on.
So to solve this, we created this feature branch here.
So regardless of whether they were opened in Gearset or in version control, As soon as you open a PR target targeting an environment branch, Gearset kinda does three things.
It creates a promotion branch, as I said, which is a direct copy of the source feature branch. It then opens a PR between the promotion branch and the target environment branch, and then it checks for any merge conflicts between the promotion branch and the target environment branch.
If these can be automatically resolved, Gearset will do that in the promotion branch. If they need manual intervention, Gearset will flag this up for resolution in the promotion branch. And once the promote, the pull request is merged, Gearset automatically deletes this promotion branch regardless of whether it was merged in Gearset or in your version control.
So as I said before, you often can see if, the the promotion branch is what what it looks like is because it looks like the GS dash pipeline. So that's why that will be, showing up in your screen on on your version control. So as a kind of summary of that, essentially, what is happening here is to avoid pollution of the feature branch, with reverse merge commits from the merge conflict resolutions, Gearset create creates a promotion branch so that this feature branch can move through the pipeline without being polluted, and therefore, it showed in your version control provider.
I appreciate that is quite a lot to digest, and kinda understand. So is there any questions that people may have around that?
Oh, well, we've had nothing come through yet, but we can keep this open for thirty seconds or so in case folks would like to take some time to digest and, pop in any questions they might have.
Yeah.
But quite often, what we see is people are slightly confused as to why, there is a PR being opened by GearSet. So it's good just to kinda understand the background and the context of that.
That.
Okay. So we've had a question come through.
Question is, if promotional branch is deleted, how can we roll back?
Roll back? You mean, if the promotion branch is deleted, it means that it has not been merged yet or so what is that you are going to roll back? Is it the the deletion or, the changes that were in that?
Because the promotion branch remains open until it's merged into the target branch. So, if it's been deleted, it can be reopened again. But, if you are talking about rolling back the changes that were in that feature branch, there is, two step there are two steps that need to be followed. They need to be reversed, rolled back from the org because they were being taken there from the CI to the from the CI job, and then they need to be reverted from the branch because the promotion branch has been merged. So every rollback in pipeline is made of two steps, reverting the changes from the org and reverting the changes from the branch so that they can stay in sync.
If this does not answer your question and you want to add more context, we can have a follow-up on this.
Thank you, Antonio. Cool. That's the only question that's come through, Charlie, so I'll hand back over to you.
Good stuff. Thank you.
Oh, next slide.
So the the less kinda common issue or this is less of an issue and more of a kinda frequently asked question is how to fix a feature that is already in flight.
So this often happens.
A team may have a scenario where they have a few in flight changes where different features are currently merged in different environment branches, but they want to make amends to a change already in progress. So they need to consider at which stage the user story is at already.
For all scenarios, however, the initial step is always the same. You should develop in your sandbox as that first point says and add the changes to the correct feature branch. So you should start with developing your fix within the right developer sandbox here, which is the same org, that you originally made your feature. And when it's ready, you need to commit this fix to the same feature branch as shown here and then, commit more changes as well.
So for this using pipelines, as I said, you select your, developer sandbox environment. Then in the drop down box, make sure to use the same feature branch that you originally used. Click commit more changes as you see in the top right, and run through the same comparison flow as before, making sure to select and commit the changes that are needed.
Now if the feature branch already has an open PR against the first environment, say it's just here, you will only need to add the changes to the correct branch, and then the existing open PR will get automatically updated following the commit to the existing feature branch. And you will not need to open a new PR against the first environment. This will happen automatically, and then any validations and merge conflict checks will rerun, and you'll be able to promote your updated user story.
There are a couple more scenarios that there is to think about. They're a bit more complicated, but nothing that is like Outlook's world.
So that is for if the, user story is open against that first environment.
Did we have any questions on that?
Nothing in the chat so far, Charlie.
Okay.
Cool.
Yeah.
I think you're good to yep.
Yeah.
You're good to go on.
K.
Oh, I've got confused. That was the last slide.
So so thank you for listening.
Those are kind of few of the common issues and frequently asked questions that we kinda get, and, I was happy to talk you through those. Do we have any more questions, Marif or Antonio, just while we're waiting?
Yeah. That's yeah. Thank you, Charlie, for kinda taking us through, some of these issues that commonly come up. We'll give folks a couple of seconds if they wanna ask us any questions, any additional questions while we're here. But there is one that I think we should address, which is, so what if in a scenario with in flight changes where someone needs to fix and then continue to test, test on the feature in the same environment, what's, what's the play there?
Charlie, if you can go, to the next slide.
So let's say that, I have merged a feature in UAT.
And, after I test it, something come up and need to be fixed. I can go back on my, original feature branch, the one where I working on that I worked on that feature, and add an extra commit there. So fix the issue, basically, that was found during UAT.
Then, I have two options. Either I enter the pipeline again from integration in this case, or I open a pull request manually from version control directly into UAT so that I can go on and test.
And then, once I'm satisfied with that, I can just merge the pull request that is currently open against production. So modifying the original feature branch will already update pull requests that are open. So you don't need to worry about that. You can, just add extra commit in the feature branch, then reopen the pull request if you need to, continue testing. But then once you are done and satisfied, you can, merge into production in this in this example.
Thank you very much, Antonio.
And it looks like we've had no further questions, through the q and a. So I can, I can start to bring a wrap us up? So, folks, thank you so much for joining us.
Yeah. What three weeks it's been has flown by pretty quickly, but, we hope we really hope you found today's session and the previous two useful. We hope you've learned quite a lot from it, and, we'd we'd love some feedback from you as well. So if you get a chance, please do let us know how you felt this has gone.
Appreciate there may be some questions, or as always is the way as you sign off a call, you think, oh, why didn't I ask that, then please do not hesitate to reach out to us. You can reach Charlie and myself and the rest of your customer success team by emailing success at gearset dot com, or by dropping us a message in the in app chat. So thanks for joining. If you did miss the start of this call, just a quick reminder that our product team is actually doing some research on making this whole process of setting up and using pipelines as easy as possible for you.
So we'd love to hear from you. If you'd like to talk to us, then please also drop us a message about this, and we can get this coordinated for you. But with that, thank you so much for joining us over the last few weeks. We enjoy hope you enjoy the rest of your day, and thanks again.
