Using the includes keyword when configuring your pipeline help you break down one long pipeline file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. However, it makes your pipeline configuration hard to follow, in many cases a pipeline configuration file could look like a list of multiple lines of includes, in this release we allow you to view the merged version of your pipeline configuration, this way it would be easy to understand your pipeline flow and can make the debugging process easier
Problem to solve
Currently, the CI Linter validates your CI configuration including all of the includes. However, it's not obvious from the UI.
This page may contain information related to upcoming products, features and functionality.
It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes.
Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.
@dhershkovitch Would you like to stop the work on the CI Lint and shift focus to the Editor Lite completely? That makes sense to me.
We have several issues open for the improvements of the CI Linter. Should we look at them together and see if they are still relevant for the Editor Lite?
For example, this particular issue is to make it more obvious in the CI Lint that it not only validates the .gitlab-ci.yml but also all of the includes. From the UI it's not clear since the Linter window says "Contents of .gitlab-ci.yml" and the includes are not visible anywhere.
I'm not sure how this experience translates to Editor Lite. A few questions I have about the Editor Lite:
Does it have the same capabilities as CI Lint right now? Looks like it has some live linting (actually, not sure if it's called linting), but it's different.
Doesn't look like it validates the includes. It's just the main CI file.
We already validate the includes for the file that's being validated. In #244838 (closed) that is scheduled for this milestone we'll allow users to download the yaml with merged results. It's an MVC solution.
Once we add the button, this is what a validated file with includes will look like. You see the includes are there, but it's not possible to view them in the context of this file unless you download the whole flat file and view it locally.
Experience that will be available as of 13.5
For the next iteration to make the includes more accessible, we could make it possible to expand them in the original file. By default they'll be collapsed. It will serve as an affordance that the includes are also being validated.
We already have this capability in the linter, and just need to apply it to the individual include lines.
Here's a quick sketch of what it could look like.
In the future we should look into whether the behavior of automatically validating includes is desired, but this can be done when we work on the linting/ validating experience for the separate CI editor.
@fabiopitino Originally it was your suggestion to expand/collapse the includes, so wanted to loop you in to see if the designs I created make sense/ are feasible. ☺
@samdbeckham@dhershkovitch Could we make it this issue blocked by the issue to add the download yaml button (as from my understanding, it will be blocked)
Also since this will come after the work of the other issue, it means we just want to add the collapsible section to the includes correct?
Could we make it this issue blocked by the issue to add the download yaml button (as from my understanding, it will be blocked)
We can but is there any technical reason that one is blocking the other?
Also since this will come after the work of the other issue, it means we just want to add the collapsible section to the includes correct?
Do you mean only to add the expanded version of .gitlab-ci.yml when the validation is successful?
If this will make this issue easier to implement then i am ok with that, however i do see value of seen the expanded version of the ,gitlab-ci.yml file even if the includes are not correct
@dhershkovitch Sorry about the late response. I took some time to investigate this and make sure I understand this properly. The problem with this issue is that what we want to do, is to basically have access to the yaml of each includes file so that we can add their content under the "header" as a collapsible section. Right now, the FE doesn't have access to that data, so I had assumed that the work would come after the download merged yaml file, because then the API that gives the FE the fully merged yaml would be available, but maybe that's not what we want here?
If we want that after clicking "validate" the content is updated with the entire yaml, including the content of the merge files, then there would definitely be some BE work cc @cheryl.li
We need to establish how we want to proceed with these 2 issues:
Do we add in the API response of the validate the yaml of each included file? Are there any performance pitfalls?
Does the API endpoint that will return the fully merged yaml necessary before we can do the work here?
@furkanayhan In #244344 (closed) we're changing the current experience to automatically load the .gitlab-ci.yaml and validate it as you navigate to the Linter page.
The proposal is to make it possible to expand the includes within the original file, but by default they'll be collapsed.
Does the API endpoint that will return the fully merged yaml necessary before we can do the work here?
Are you suggesting that the backend API needs to return the full yaml (with all included content)? I assume this would be needed if we are to refine this as a ~"candidate::13.7" issue.
@cheryl.li yes, in #244344 (closed) we will add the gitlab-ci.yml content automatically. And in this issue we would like to add the includes yml content in the linter, so it looks like FE needs to receive the includes from BE.
@cheryl.li My concerns about this issue were stated in the comment thread below. So, I would prefer to make a comment about backend side of this after seeing a clear picture of the issue.
What would be the user experience in case the user will expand the includes in the linter and then try to edit its content?
Do we allow them to update the expanded includes?
In case we do will we validate the updated version, (I assume not which means that updating is possible but unnecessary, this seams problematic from the user experience POV)
The user flow the way I see, users can validate their .gitlab-ci.yml file, update it when needed until the syntax is correct, then copy-paste the .gitlab-ci.yml from the linter to the file, if we will add the includes in the linter the user will unable to complete this flow.
@dhershkovitch That's a very good point actually and I think that's why it's been so hard to wrap my head around this issue 😄
I am not sure there is an easy workaround for this. If the user resubmit the content of the newly generated content of the file with the includes lines and their content, will it passes? Probably not since includes local fetch the files in the repository, but we are adding content under it as well. And even if the BE ignores the content under the includes, then if the user modify that, and re-validates it, then it wouldn't evaluate their change, just the file of the include.
There might be other options to explore that might interesting. One very simple solution would be to simply show a banner/alert that says that "Your CI file has been validated with all of its includes" which is probably the easiest thing to communicate it to the user without getting into complex linting problems.
Another option would that instead of rendering the content under the include, we get the API endpoint
that returns the fully merged yaml and that's what we render in the editor, that way the includes are "swapped" with the content and we avoid this in-between state that only exist in the UI and cannot be validated is gone. The user that edits that content will also be able to re-validate the content so this is the ideal solution imo.
@furkanayhan Just to confirm, do you know if we send a .gitlab-ci.yml content to the lint endpoint like this:
What will happen to the jobs under the includes given that the local file exist? 🤔 Would the linter ignore the job under the includes? Would it try to parse it and fail?
There might be other options to explore that might interesting. One very simple solution would be to simply show a banner/alert that says that "Your CI file has been validated with all of its includes"
I guess this is a safe and easy bet for now, I think that we need to conduct some problem validation about the flow and the desired outcome, we should probably think beyond what is available today, but it needs to start with the user POV, i will take the followup on adding this to our workflowvalidation backlog
Given the concerns and no easy way to address them at this time, this seems like a great MVC:
There might be other options to explore that might interesting. One very simple solution would be to simply show a banner/alert that says that "Your CI file has been validated with all of its includes" which is probably the easiest thing to communicate it to the user without getting into complex linting problems.
Thanks everyone for validating, I have created a separate issue for the MVC that I can easily work on without any BE involved in %13.6. Here is the issue: #273434 (closed)
I am rethinking this issue, we know that our users would like to see a merged .gitlab-ci.yml (with the includes and extends),
Another option would that instead of rendering the content under the include, we get the API endpoint that returns the fully merged yaml and that's what we render in the editor, that way the includes are "swapped" with the content and we avoid this in-between state that only exist in the UI and cannot be validated is gone. The user that edits that content will also be able to re-validate the content so this is the ideal solution imo.
Maybe we can add a button in the linter where users could toggle between a merged/unmerge version?
We can enhance this experience by coloring the "swapped" lines (in the merge version) to indicate to our users that those are separated files. (maybe also adding a comment with the file name and the location)
I like the idea! @dhershkovitch If the Linter will show the full config with includes accessible right there in the file, would it make sense to allow to edit the whole merged config file all in one go in the Pipeline Editor? I wonder how unruly such merged config file can get.
I guess my question is, if we know that developers want to see a full config with merged includes and validate it, do they also want to edit that file and commit it all in one place rather than have to make changes in individual files?
When someone validates the config in the "Validate" tab which will have the linter in it, they will then want to save the changes as they troubleshoot. Makes no sense to have them copy the changes they made to the merged includes and go to the specific include file to save those changes. Wdyt?
We can enhance this experience by coloring the "swapped" lines (in the merge version) to indicate to our users that those are separated files. (maybe also adding a comment with the file name and the location)
👍
Also cc @mrincon because he's been working on the linter and seems like we're now at a point where the linter will validate the config continuously as you type (correct me if I'm misinterpreting). ☺
I wonder how unruly such merged config file can get.
Very! A gitlab project pipeline may have hundreds of jobs, and it make also add some templates that are not part of the project. Also, I think that the merge operation operations is not reversible, and users might not be able to work with a merged version of the yml directly.
When someone validates the config in the "Validate" tab which will have the linter in it, they will then want to save the changes as they troubleshoot.
@fabiopitino raised a very interesting question today about the lint layout: "why show it in a table?"
This tab becomes more interesting when we show the user the entire resulting file, merged with all the templates and includes.
I think this tab should not have editable text, but it would allow the user identify what the resulting config is and it might be easier to use than a Downloaded file.
I guess my question is, if we know that developers want to see a full config with merged includes and validate it, do they also want to edit that file and commit it all in one place rather than have to make changes in individual files?
@nadia_sotnikova Keeping configs in separate files has the advantage of making them reusable and/or easier to manage. Note that the include keyword allows also to include content from other projects or even from a remote URL. This means that the merged result cannot be committed in one place.
It may be ok to allow users to "play" with the merged YAML by changing and validating it but not committing it.
I guess my question is, if we know that developers want to see a full config with merged includes and validate it, do they also want to edit that file and commit it all in one place rather than have to make changes in individual files?
This is an interesting question which requires thorough validation, I can only assume that the answer is it depends on the use case, I also see technical limitation which prevents us from implementing such behavior, I think that for now when should allow users to view the merged .gitlab-ci.yml file in a view-only mode, and have conducted some problem validation prior from taking the route of allowing our users to edit the include: files
@nadia_sotnikova I do want us to move forward with an MVC to allow users to see the merged .gitlab-ci.yml file in a view-only mode.
The way i envision this, is that we should have a button on the linter that would allow our users to view the merged version of the .gitlab-ci.yml file.
@f_caplette@fabiopitino any limitation regarding the permissions to view includes in private project? (do we allow to include files from private repos)
@dhershkovitch There was an issue to allow users to download the merged YAML. It would still be the easiest option I suppose, but not ideal experience. If we can show it in the UI, here are my thoughts on this:
The way i envision this, is that we should have a button on the linter that would allow our users to view the merged version of the .gitlab-ci.yml file.
As far as I remember from the demos, the Linter in the Pipeline Editor only shows the results of the linting and not the file itself. In that case, I think viewing the merged yaml would make much more sense in the actual editor tab. Wdyt?
We could use this toggle component to toggle between two views in the editor tab. It'd be a nice intuitive interaction, easy to switch from one to the other. Would it be feasible?
I think viewing the merged yaml would make much more sense in the actual editor tab.
As long as we'll be able to present to our users the merged version I am fine with that.
Maybe we should implement the download merged yaml at the first iteration and view the merged yaml in the 2nd one, although for a user it makes more sense to see the merged file first and only then allow it to be downloaded
@dhershkovitch@nadia_sotnikova I think that displaying the merged YAML in the UI would be easier to do than downloading it because the frontend already has the data coming from the Lint controller/GraphQL, it's just not displayed anywhere.
If instead we want to make it downloadable we have to go again to the controller, lint the content again and prompt the merged YAML for download.
Dov Hershkovitchchanged title from Make it more obvious that CI Linter validates the includes as well as the .gitlab-ci.yml to Show the merged version of .gitlab-ci.yml (with include and extends)
changed title from Make it more obvious that CI Linter validates the includes as well as the .gitlab-ci.yml to Show the merged version of .gitlab-ci.yml (with include and extends)
@dhershkovitch I added a mock-up based on the latest editor demo with the buttons added in an area directly above the editor. Does the wording on the buttons make sense?
In case your CI config files is called something other than ".gitlab-ci.yml", we should either use a more generic copy for that view or change it based on the config file name. 🤔
My two cents are that hierarchically "viewing" the final YAML with merge includes should a tab be at the same level as the "visualization" tab or the "lint" tab.
In those 2 cases the user gets to see a holistic preview of their pipeline, same as the "YAML with merged includes".
I would go with something more generic view merged file or view merged yaml
In case your CI config files is called something other than ".gitlab-ci.yml", we should either use a more generic copy for that view or change it based on the config file name
Miguel idea solved that problem
Anyways I do believe that the pipeline editor is likely to change in a future iteration
@dhershkovitch The merged result should contain the content after expanding the extends keyword. So the extends keywords should not be there and their content inlined instead.
@flynneva the purpose of this issue was to view the merged CI yaml file in the UI, this is possible today by navigating into the pipeline editor, if there is a need to output the merged yaml through an API then you'll need to open a separated issue.
the purpose of this issue was to view the merged CI yaml file in the UI
@dhershkovitch I get that. My question was related to this thread that discusses the implementation and whether or not to expand the extends keyword in the merged yaml.
It appears in both the editor UI and via the API the merged yaml still includes the extends keywords...when @fabiopitino suggests it should not.
Do you or anyone else have any status on this?
Since this feature of expanding the extends in the merged yaml file is in the description of this issue...I think it relates to this issue.
@dhershkovitch ah nevermind. I realize now that the extends are merged in there but the extends keyword is left in there to show when a job was extended. Nevermind
We are a gold customer & welcome the additional visibility the feature provides.
May I suggest a few further enhancements to improve visibility of the final gitlab-ci config:
include variable values in the above so we can see what is going to be applied
retain the complete configuration from last execution
The main requirement driving these are audit related. We need to be able (somehow) to ensure that critical projects are using internal best practice CI libraries (that include code/container scanning etc) & not just doing their own thing. As a starting point, we need to pull the full/actual config, including all vars/settings, as has been/will be applied to be able to then start to check for non-compliance.
Including variable values I admit is a tricky one as it takes the capability in this issue from be a linting exercise to needing to actively run (in a reduced capacity of some sort) in order to expand/resolve variables & report what would be applied. Furthermore, some vars will be set only at execution via scripts or based on cli/job outputs, complicating the task more.
The challenges around (1) made me think it would be easier just to retain the actual yml config from each run so it can be referred to later. Also being able to tag projects would be useful, but I dont believe we can do that atm (apologies if I'm wrong & have missed it)
the mergedYaml value is null. I have tried different configuration, but I always get this. We weren't using mergedYaml value before, so I wonder if this has been this way since the beginning or if it broke along the way. @lauraMon Could you validate this for me? 🙏🏻 It can be checked by writing this simple config in our section and then checking the graphQL response in the network tab of the debugger. Feel free also send it to another BE 😄
The argument got removed in this commit !46912 (4a285e4d), but the mergedYaml field was left there, which is why you got null and didn't get an error. Luckily, it's a quick fix, given that the code that fixes it is right there ;)
Here's the MR to fix the mergedYaml issue: !53081 (merged). I checked with your content and it looks good.
With the same content provided, this is the GraphQL response:
I will take a closer look and also update the specs tomorrow and send if off to review. I don't believe there's anything you've got to do in the frontend😄
@lauraMon Thank you, this is amazing! I already have most of the FE done for the feature, so I can simply add mergedYaml to the query and it should be good to go 🙇🏼
@f_caplette Awesome 😄 The MR is ready for review so I'll send it as soon as the pipeline passes: !53081 (diffs)
I made the argument true by default, but you can always pass it as false once we have multi-file. OR we can revisit this then and change it if we need to, that's like a 1 point issue.
@nadia_sotnikova It seems our easiest option is to use the text editor to render the merged file. I have made it read-only which disable a user from editing the file, but I don't think it's clear that it's intended as is.
This raises two questions for me:
Should we show the commit form at the bottom when in that view? I am afraid users might think they are committing that merged version
I tried adding an information banner to tell the user that this is a view only section. Do we prefer with or without it? And if we want it, could you help me improve the copy 😅 Thanks!
We could do something like this. I think since you can't edit the YAML there should be no commit form. I think we shouldn't use an alert for this, it's a bit too disruptive. Just UI text with an icon.
Also, should we move this tab next to the Write tab? We kind of treat these tabs as steps and I think it makes sense to view the merged yaml as you're writing, then view visualization, then Lint...
@nadia_sotnikova Thanks, this is much better 😄 As for the order, I am a bit conflicted 🤔 In a way now that we have the real time lint validator as you write, each 3 tabs (visualize, lint, view merged yaml) are, at least to me, at the same level of importance. They each offer a deeper dive depending on what you need so I have no strong preferences in ordering 🤷🏼 Let me know if you want them moved around and I can do that too!
Here are 2 screenshots with the design for the read-only with the tabs order changed:
@f_caplette The order isn't critical, and I agree that we're not sure the tabs work as steps. They could, but most probably not in all cases.
We can go with the current order on far right of the tab group. ☺
By the way, will the editor be disabled in a way that you can't place a cursor in it? Would you be able to still select and copy the yaml to clipboard?
We can go with the current order on far right of the tab group. ☺
Thanks!
By the way, will the editor be disabled in a way that you can't place a cursor in it? Would you be able to still select and copy the yaml to clipboard?
@nadia_sotnikova You can still place your cursor in and copy paste, you just can't modify the content
@f_caplette Ideally you shouldn't be able to place the cursor inside the input area. Is it possible to make it so it looks like static text? So you can't place the cursor inside, but you can highlight text and copy it.
It'd be clear affordance that you can't edit. Think view-only Google docs. 😄 (when designer explains things...)
@nadia_sotnikova I can take a look, though I suspect the only way to do this would be to use the blob_content component we use for snippets, but using that component seems to require data we currently don't have in graphQL, so I have avoided using it so this issue could stay FE only. I will check if I can make this happen with the editor lite component and I will update my findings here 😄
@nadia_sotnikova So the short answer is that we can't hide the cursor in read only with the editor. However, the default is that the cursor will not blink while in readOnly so that's the way Microsoft (who develops Monaco, which we use for the Editor Lite!) differentiate between the 2. Here is a video of the cursor not blinking:
Merged today, here is the rollout issue to enable it by default. If all goes well, it should be enabled by default on the 16th and gets in the release for the 17th.