Backend: More user-friendly error messages for CI includes

Release notes

Problem to solve

We don't provide clear error messages to help developers troubleshoot problems with CI includes. See the proposal section with the details of the errors to improve.

This issue originated in this discussion

Proposal

Problem	Current error screenshot	Proposed new error text
We have these include types: local, file, remote, and template. All of them have their own structure and syntax. Your "include" does not match any of our include types.		abc is not a valid subkey for include. Valid subkeys are local, file, remote, or template. Learn more.
When a user includes different types of includes in the same entry (like project and template in this case), we show the same error.		Each include must use only one of local, file, remote, or template. Learn more.

Intended users

• Priyanka (Platform Engineer)
• Sasha (Software Developer)

Feature Usage Metrics

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.

added backend featureenhancement grouppipeline authoring labels

added typefeature label

cc @mbobin @dhershkovitch @marknuzzo

@furkanayhan Can you provide some examples of the messages and a bit more context about the problem so I can understand what UX changes might help here? 🙏

@nadia_sotnikova I guess the problem here is that we don't have a clear message here:

https://gitlab.com/furkanayhan/test-project/-/blob/cc071a7e59c54b4b10c6de89121ab4826d4a6d68/.gitlab-ci.yml

@mbobin Please correct me if I'm wrong here.

Agreed, the error message is unclear to me as well. 💯

@marcel.amirault Would you have any suggestions for improving the error text here? I'm not sure what we're trying to say with the current error message.

@furkanayhan Thanks for the context! I have a couple more questions.

For this particular error, what's the problem with the includes and how should the user resolve the error?

Is this error the only one that we need to fix? Are there other similar instances? The issue title says "more user-friendly messages for CI includes", I wonder if there's other includes related errors that we should look at.

@nadia_sotnikova Actually, I'm not sure what we're trying to say here either...

@furkanayhan Should it be something like this? "abc is not a valid type for include"?

@marcel.amirault @nadia_sotnikova We are trying to say this;

• We have these include types: local, file, remote, and template.
• And all of them have their own structure.
• Your "include" does not match any of our include types.

@furkanayhan @nadia_sotnikova How about:

• abc is not a valid subkey for include. Valid subkeys are local, file, remote, or template. Learn more.

@marcel.amirault @furkanayhan

This error is also shown when a user includes different types in the same entry(like project and template in this case). Should we change this one as well?

@mbobin Hrm, that one is a bit more tricky. How about:

• Each include must use only one of local, file, remote, or template. Learn more.

I think that would work, thanks! 🙇🏻

Thanks for the collaboration here! 🤝

I added a proposal to the issue description and moved this to workflowplanning breakdown to be weighted. cc @marknuzzo @dhershkovitch

Thanks @nadia_sotnikova for the ping and everyone for the great collaboration here. 🙇

@dhershkovitch - I'm going to place a candidate15.2 label on this issue so that it can be weighted start on June 1. Please let me know if there is a different timing for this work to be prioritized.

changed title from More user-friendly error messages for CI includes to Backend: More user-friendly error messages for CI includes

changed the description

added devopsverify sectionops workflowplanning breakdown + 1 deleted label

removed workflowplanning breakdown label

added UX label

Adding UX here - @nadia_sotnikova - should this go into workflowready for design or workflowproblem validation? 🤔

@marknuzzo Thanks, I pinged Furkan in a comment above to get more context about the problem. I'll move the issue to ready for design if the problem is clear. ☺

added workflowproblem validation label

added Technical Writing UI text labels

added workflowready for design label and removed workflowproblem validation label

added 1 deleted label

All SUS-impacting issues need to have a proper severity label set. Please add those to this issue and remove the automation:ux-missing-labels label.

@nadia_sotnikova can you help get a severity label added? Thanks.

added automation:ux-missing-labels label

added severity3 label

changed the description

added GitLab Free GitLab Premium GitLab Ultimate direction documentation labels

changed the description

assigned to @nadia_sotnikova

added workflowdesign label and removed workflowready for design label

changed the description

unassigned @nadia_sotnikova

added workflowplanning breakdown label and removed workflowdesign label

added needs weight label

removed automation:ux-missing-labels label

added candidate15.2 label

added priority3 label

assigned to @lauraX

set weight to 2

added workflowready for development label and removed workflowplanning breakdown label

added backend-weight2 label

unassigned @lauraX

removed needs weight label

added candidate15.4 label and removed candidate15.2 label

changed milestone to %Backlog

added [deprecated] Accepting merge requests label

added candidate15.5 label and removed candidate15.4 label

added candidate15.6 label and removed candidate15.5 label

changed milestone to %15.5

mentioned in issue gitlab-org/quality/triage-reports#9292 (closed)

mentioned in issue gitlab-org/quality/triage-reports#9363 (closed)

mentioned in issue gitlab-org/quality/triage-reports#9506 (closed)

added onboarding label

removed [deprecated] Accepting merge requests label

changed milestone to %15.7

added [deprecated] Accepting merge requests label

mentioned in issue gitlab-org/quality/triage-reports#9584 (closed)

mentioned in issue gitlab-org/quality/triage-reports#9684 (closed)

mentioned in issue gitlab-org/quality/triage-reports#9754 (closed)

mentioned in issue gitlab-org/quality/triage-reports#9866 (closed)

removed [deprecated] Accepting merge requests label

assigned to @lma-git

Hi @furkanayhan @marcel.amirault! I'm taking a look at this issue from 5 months ago 😄 There is a third scenario that I'd like to get your input on. (Please let me know if this would need Product input too 🙏)

What should the error message be if the user includes only the "file" keyword without "project"? Currently the BE code considers it as not a "matching" keyword, so it defaults to the error message: needs to match exactly one accessor!. And with the proposed changes in this issue, it would end up looking like:

file is not a valid subkey for include. Valid subkeys are local, file, remote, or template.

which doesn't seem fitting 😅. So I think a different kind of error message might be best here.

For further context, it looks like "project" is required to be used with the "file" subkey. -> Doc ref: https://docs.gitlab.com/ee/ci/yaml/#includefile

@lma-git Hrm, it looks like we've documented that wrong. It should be a docs section about include:project, not include:file, I think? I think I'm going to open up a docs MR to fix that right now. 🙇

And the error should therefore be:

• file is not a valid subkey for include. Valid subkeys are local, project, remote, or template. (changing file to project in the second sentence)

It should be a docs section about include:project, not include:file, I think? I think I'm going to open up a docs MR to fix that right now.

@marcel.amirault I am not sure if either of them is true 😅 Both are required for a valid syntax. I guess we just chose file when implementing it for a random reason 🤔 However, I'd like to have include:project to make it consistent with the code.

@lma-git I guess "file is not a valid subkey for include. Valid subkeys are local, file, remote, or template." is a great start for now. You can create an MR with this and we can discuss in that MR. WDYT?

also cc @dhershkovitch

Thanks for the feedback! @furkanayhan That's a good idea--I'll start off the MR first then and we can discuss there :)

I also created !103488 (merged) to address the docs, which I think can be done independently 🤞

created branch 357844-backend-more-user-friendly-error-messages-for-ci-includes to address this issue

created branch 357844-update-ci-include-error-msgs to address this issue

mentioned in merge request !103390 (merged)

added workflowin dev label and removed workflowready for development label

mentioned in merge request !103430 (closed)

mentioned in merge request !103488 (merged)

changed milestone to %15.6

added workflowproduction label and removed workflowin dev label

closed

removed workflowproduction label

added Category:Pipeline Composition label