@marcel.amirault - where do you think would be the best place to add the documentation of what is a component? I was thinking perhaps as a submenu item in Pipelines? or under Customize pipeline configuration?
Thanks for including me in this discussion @lauraX - I think all of your suggestions are good ones. One other option that I'm curious about your and @marcel.amirault's thoughts on is whether to incorporate a new submenu item called Components under https://docs.gitlab.com/ee/ci/ so that the association is still present with CI/CD but has its own dedicated section.
I like that idea! When doing the docs for spec:inputs and include:with I was struggling a lot with how to place all of the information in an isolated way.
@lauraX @marknuzzo Yes, I think we should start with a whole new place for this. It's going to be a completely new paradigm, and will work differently than other keywords. For example, there will be keywords that you'd only use when defining components, and others you'd only use when using components (at least, I think that'll be the case?)
If we start with a doc/ci/components/index.md, it'll give us a place to document it, while at the same time giving us flexibility to think about how to incorporate things into the main reference page over time.
It also means we can throw on the Alpha flag on the whole page (and any subpages we create initially), again giving us flexibility to tweak the feature in a breaking way before declaring it generally available. WDYT? cc @dhershkovitch@sunjungp
@lauraX @avielle@marcel.amirault@marknuzzo Thanks for leading us in this space! We have accrued questions (in our CI Alpha Assignment 1) from users that we should address in the Documentation (full report here):
“Will it be possible to have instance level components on self hosted instances?”
"I have a default set of templates used by my team. If I were to break them down to individual components, could I then build a template that calls the components?”
“Will users be able to extend component functionality, e.g. by adding before_script or script?”
"When I try to include any pipeline into mine and try to customize the variables will it work?”
'What's the publishing process if I create new components for my team?'
**We also know that uses would like concrete examples**
- “Was missing things about developing these kind of components. There were a few mentions about testing but no real examples on what kind of test strategies for the components there could be. Maybe some static analysis for the YAML in the component and some examples on how one could test the components.” (Participant 4)
- “I'm a visual learner, so I would love to see concrete examples of what component code looks like, and maybe see them in action, once the MVC is complete.”(Participant 9)
- “I think having more examples would up my answer [to the question of how satisfied I am] to "Strongly agree" (Participant 5)
Users want to use CI Components to: (1) break down a monolithic build process to discrete steps, (2) for releases / deployments, (3) to clean up environmental variables and (4) to solve problems related to maintenance and inheritance of CI templates. Those could be good use cases to keep in mind.
I think we should also address some of their concerns around versioning and upkeep. Maybe that has it's own section.
Let me know if you have any questions on that. Go team.
We're sending out our next CI Alpha Assignment on 2023-04-13. I'd like to link to the draft that you have so we can get early and low-stakes feedback on that.
May I have a link?
Ping me here when we have one ready and I'll work into our Alpha program when it is.
New Questions coming in from CI Alpha Assignment 3:
Can this be expanded to have variables in the job names it includes?
Do users need to have reporter+ on the component repo in order to use them?
Why are there not customer-viewable error logs of what happened when jobs don't get added? or at least a way to figure it out without as much trial & error?
What should be done when the image I want is only accessible to runners owned by the component, and the job including the component cannot reach that image? (i have a use-case for this solution)
@marcel.amirault - would you be comfortable with taking lead on getting an FAQ MR up for us to iterate on the answers for? I think this would go a long way to helping provide some guidance to users on some of these questions.
@marknuzzo Sorry for the delay, getting back to older pings now. I'm not sure where we would document these questions, it wouldn't go in the components doc (and I don't have the answers to the questions). Perhaps @fabiopitino could put it in the blueprint, but i wonder if it's more that we need to keep track of these in an issue or something?
Thanks @marcel.amirault - since we are trying to point users away from blueprints because it may not always accurately represent what's available yet vs engineering or user docs that define what is available, IMO it may not be ideal for that information to be stored there. I'm not sure how we have handled managing FAQ related material in the past @dhershkovitch@fabiopitino but any thoughts here?
Can this be expanded to have variables in the job names it includes?
For components' job names you could use inputs. We added support for inputs everywhere instead of adding support for variables (which is very expensive) everywhere.
recommendation: Use inputs over variables whenever possible.
Do users need to have reporter+ on the component repo in order to use them?
Yes. Users that create a pipeline need to have read access to the component project.
Why are there not customer-viewable error logs of what happened when jobs don't get added? or at least a way to figure it out without as much trial & error?
This is orthogonal problem to components and more related to debugging rules.
What should be done when the image I want is only accessible to runners owned by the component, and the job including the component cannot reach that image?
I'm not sure what's the use case here and whether there is a better way to design the component. Maybe we should get more info from the customer.
@marknuzzo I remember seeing some grouppipeline authoring issues around debugging pipelines and debugging rules was a recurrent issue. I can't find them though.
Hi @gitlab-com/pipeline-authoring-group/backend @gitlab-com/pipeline-authoring-group/frontend - does anyone recall issues related to debugging pipelines and rules? I could only find #36115 but if there are others, I would like to account for them in the larger CI Catalog GA effort, if possible.
@lauraX Yes please! We need to document the "bare minimum", meaning only the things that are in the code and testable now. Basically, if I can go into my GDK, flip a feature flag and test something, then we should have it in the MVC page. If some functionality is in dev right now, but not yet merged, we can wait, and add that to the docs. It'll be much easier after we have the initial doc, as we can just expand as needed, with the Beta warning at the top of the page
@marcel.amirault great! I've paired it down and am getting @avielle to double check it, and then I will send it along to you. Once that's done, should I assign you this issue as well?