Refactor Backstage templates: improve UX and simplify service naming by mashkovd · Pull Request #10 · mctlhq/mctl-gitops

mashkovd · 2026-02-20T18:16:54Z

Summary

This PR refactors two Backstage scaffolder templates to improve user experience, clarify terminology, and simplify the service naming workflow. The changes consolidate form sections, enhance descriptions, and derive the service name automatically from the repository name instead of requiring manual input.

Key Changes

deploy-component/template.yaml:

Removed the rocket emoji (🚀) from the template title for consistency
Added presentation configuration with custom button labels ("Release Service", "Review & Release")
Consolidated "Component Info" and "Source Repository" sections into a single "Service & Source" section
Removed the manual serviceName input field — service name is now derived from the dockerfileRepo using a repoName filter
Reorganized form fields for better logical flow (team, repo, version, then networking, environment)
Renamed section titles for clarity: "Network Configuration" → "Networking", "Environment Variables" → "Environment", "Secrets" → "Secure Variables"
Improved field descriptions with more concise, user-friendly language
Updated Vault path and workflow inputs to use dockerfileRepo | repoName instead of serviceName
Enhanced output section with summary information (Type, Version, Preview URL) and additional links (ArgoCD Dashboard)

update-component-config/template.yaml:

Renamed section titles for consistency: "Component" → "Service", "Component Name" → "Service Name"
Updated descriptions to use "service" terminology instead of "component"
Improved field descriptions for environment variables and secrets with clearer guidance
Renamed "Environment Variables (non-secret)" → "Environment" and "Secrets" → "Secure Variables"
Updated output summary to reference "Service" instead of "Component"

Notable Implementation Details

The service name is now automatically extracted from the repository name (e.g., owner/my-app → my-app), reducing user input and potential naming inconsistencies
Form sections are now organized by workflow stage (service info → networking → environment → secrets) rather than by data type
Descriptions emphasize security best practices (e.g., "do not put secrets here" for plaintext variables, "never exposed in Git" for Vault-stored secrets)
Output section now provides immediate feedback about the deployment type and preview URL

https://claude.ai/code/session_014HDsuEikXzZ8SDZxwebsuc

…ted output - Rename wizard steps: Service & Source, Networking, Environment, Secure Variables - Remove serviceName field (auto-derived from dockerfileRepo via repoName filter) - Add presentation.buttonLabels: "Release Service" / "Review & Release" - Add structured output with Type, Version, Preview URL + action links - Update field descriptions for host, secretEnvVars, envVars - Rename Component → Service in update-component-config template https://claude.ai/code/session_014HDsuEikXzZ8SDZxwebsuc

Copilot

Pull request overview

This PR refactors two Backstage scaffolder templates to improve UX and simplify service naming by automatically deriving the service name from the repository name instead of requiring manual input. It also consolidates form sections, improves field descriptions, and standardizes terminology from "component" to "service" throughout.

Changes:

Automatic service name derivation from repository name using a repoName filter, eliminating the manual serviceName input field
Consolidated form sections with improved organization and clearer field descriptions
Consistent terminology changes from "component" to "service" across both templates

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
platform-gitops/backstage-templates/deploy-component/template.yaml	Major refactoring: removed manual service name input, consolidated sections, added presentation config, reorganized fields, updated to derive service name from repo name
platform-gitops/backstage-templates/update-component-config/template.yaml	Terminology and description updates: "Component" → "Service", improved field descriptions for consistency

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-20T18:30:39Z

      input:
        method: POST
-        path: /proxy/vault/v1/secret/data/teams/${{ parameters.teamName | parseEntityRef | pick('name') }}/${{ parameters.serviceName }}/repo-pat
+        path: /proxy/vault/v1/secret/data/teams/${{ parameters.teamName | parseEntityRef | pick('name') }}/${{ parameters.dockerfileRepo | repoName }}/repo-pat


The repoName filter is not a standard Backstage scaffolder filter. This will cause the template to fail at runtime when trying to process this expression.

If this is intended to extract the repository name from "owner/repo" format (e.g., "dmitriimashkov/my-app" → "my-app"), you'll need to either:

Define a custom filter in the Backstage app configuration, or

Use a different approach to extract the repo name

Additionally, even if the filter exists, there's a validation mismatch: the GitHub Actions workflow expects component_name to match the pattern ^[a-z0-9][a-z0-9-]{0,62}$ (lowercase alphanumeric with hyphens), but repository names can contain uppercase letters, dots, and underscores according to the dockerfileRepo pattern. The filter would need to normalize the extracted name to be Kubernetes-compatible.

Copilot · 2026-02-20T18:30:39Z

-            owner/repo containing the Dockerfile (e.g. dmitriimashkov/my-app).
-            For private repos: install the GitHub App at https://github.com/apps/mctl-me/installations/new
-            or provide a PAT below.
+          description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name."


The description states "The repo name will be used as the service name" but doesn't warn users about naming constraints. Since Kubernetes resource names must be lowercase alphanumeric with hyphens only (max 63 chars), and GitHub repository names can contain uppercase, dots, and underscores, this could lead to confusing failures if users provide repos with incompatible names (e.g., "owner/My.Service").

Consider adding a warning to the description, such as: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name and must be lowercase with hyphens only."

Suggested change

description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name."

description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name and must be lowercase with hyphens only to be a valid Kubernetes service name."

Copilot · 2026-02-20T18:30:39Z

+        repoPat:
+          title: Repository PAT (optional)
+          type: string
+          description: >-
+            Only needed if the GitHub App is not installed on this repo.
+            Fine-grained PAT with 'Contents: Read' scope.
+          ui:field: Secret


The repoPat field has been moved within the same section but is now positioned between dockerfileRepo and dockerfilePath, which breaks the logical flow. The PAT is an authentication credential, while dockerfilePath is a path configuration related to dockerfileRepo.

Consider moving repoPat after dockerfilePath to maintain better logical grouping: repository → path → version tag → authentication.

Copilot · 2026-02-20T18:30:40Z

          action: onboard
          team_name: ${{ parameters.teamName | parseEntityRef | pick('name') }}
-          component_name: ${{ parameters.serviceName }}
+          component_name: ${{ parameters.dockerfileRepo | repoName }}


The same repoName filter issue applies here. This filter is not a standard Backstage scaffolder filter and will cause runtime failures. The component_name value passed to the GitHub Actions workflow must match the pattern ^[a-z0-9][a-z0-9-]{0,62}$ as validated in the workflow, but there's no guarantee that extracting the repo name from dockerfileRepo will produce a valid value.

Copilot · 2026-02-20T18:30:40Z

-            For private repos: install the GitHub App at https://github.com/apps/mctl-me/installations/new
-            or provide a PAT below.
+          description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name."
          pattern: "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$"


The removal of the serviceName parameter and its validation pattern is a breaking change that eliminates an important safeguard. The previous pattern ^[a-z0-9][a-z0-9-]{0,62}$ ensured the service name would be valid for Kubernetes resource names and DNS labels.

With the automatic derivation from dockerfileRepo, there's no validation to ensure the extracted repo name will be Kubernetes-compatible. Repository names can contain uppercase letters, dots, and underscores (per the pattern on line 38), which are not valid in Kubernetes resource names.

Consider either:

Keeping the serviceName field as an editable field with a default value derived from the repo name, or

Adding validation/transformation logic to ensure the derived name is Kubernetes-compatible

Suggested change

pattern: "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$"

pattern: "^[a-zA-Z0-9._-]+/[a-z0-9][a-z0-9-]{0,62}$"

Copilot · 2026-02-20T18:30:40Z

+          type: string
+          description: >-
+            Only needed if the GitHub App is not installed on this repo.
+            Fine-grained PAT with 'Contents: Read' scope.


The updated description removes the helpful link to create a PAT (previously included: "Create at: https://github.com/settings/tokens?type=beta"). While the new description is more concise, it would be helpful to retain this link or mention where users can create the PAT, as finding the correct settings page can be non-obvious for users unfamiliar with GitHub's fine-grained tokens.

Suggested change

Fine-grained PAT with 'Contents: Read' scope.

Fine-grained PAT with 'Contents: Read' scope. Create at: https://github.com/settings/tokens?type=beta

Copilot · 2026-02-20T18:30:40Z

-            owner/repo containing the Dockerfile (e.g. dmitriimashkov/my-app).
-            For private repos: install the GitHub App at https://github.com/apps/mctl-me/installations/new
-            or provide a PAT below.
+          description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name."


The repository description previously included a helpful link to install the GitHub App ("install the GitHub App at https://github.com/apps/mctl-me/installations/new"). This link has been removed in favor of a more concise description. Consider retaining the installation link in the repoPat field description or in the dockerfileRepo description, as it helps users understand the alternative to providing a PAT.

Copilot · 2026-02-20T18:30:40Z

 metadata:
  name: release-service
-  title: 🚀 Release Service
+  title: Release Service


The rocket emoji has been removed from the template title. While the PR description mentions this is for "consistency", it would be helpful to verify this aligns with the actual convention. The provision-database template still uses an emoji (🗄️) and update-environment uses ⚙️. If the goal is to remove emojis for consistency, those templates should be updated as well, or this template should retain its emoji.

Suggested change

title: Release Service

title: 🚀 Release Service

Per codex finding on PR #86: CVE-2026-32237 is actually fixed in @backstage/plugin-scaffolder-backend 3.1.5, not 3.1.1. The GitHub advisory pins 3.1.5 as the minimum patched version; 3.1.1-3.1.4 remain vulnerable. Project's existing ^3.4.0 caret already satisfies >=3.1.5, so the implementer will likely still close as no-op (same as PR #10), but the note should be correct for any future operator reading it.

…stency test

mashkovd requested a review from Copilot February 20, 2026 18:24

Copilot started reviewing on behalf of mashkovd February 20, 2026 18:25

View session

mashkovd merged commit 8628865 into main Feb 20, 2026

Copilot AI reviewed Feb 20, 2026

View reviewed changes

This was referenced Apr 29, 2026

chore(mctl-agents): bump 1.4.0 → 1.7.0 (3 features in one cycle) #66

Merged

fix(workflows): bump mctl-agents image to 1.7.0 in implement CWFT #70

Merged

chore(agents): accept W18 Group A+B proposals (5) #86

Merged

mashkovd mentioned this pull request May 3, 2026

[daily-report] 2026-05-03 pipeline summary #108

Closed

mashkovd deleted the claude/backstage-release-service-DS62K branch May 19, 2026 04:55

mashkovd mentioned this pull request Jul 4, 2026

[daily-report] 2026-07-04 pipeline summary #507

Open

2 tasks

github-actions Bot mentioned this pull request Sep 6, 2026

feat(skills): add governed roadmap authoring skills #1067

Open

claude Bot mentioned this pull request Sep 9, 2026

docs(proposal): correct #585 modern MCP assumptions #1106

Merged

mashkovd mentioned this pull request Sep 29, 2026

newton#10 proposal: docs-consistency test, cited Archetype pages, 512 MB, task-verification wording #1462

Merged

mashkovd added a commit that referenced this pull request Sep 29, 2026

docs(proposal): wrap newton #10 task text

a490a30

mashkovd added a commit that referenced this pull request Sep 29, 2026

docs(proposal): align newton #10 rollback rationale

c46ab6f

mashkovd added a commit that referenced this pull request Sep 29, 2026

docs(proposal): newton #10 alternatives and risks name the docs-consi…

69af17a

…stency test

Navigation Menu

Repository navigation

Refactor Backstage templates: improve UX and simplify service naming - #10

Refactor Backstage templates: improve UX and simplify service naming#10
mashkovd merged 1 commit into
mainfrom
claude/backstage-release-service-DS62K

mashkovd commented Feb 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name."
	description: "Repository containing the Dockerfile (e.g. dmitriimashkov/my-app). The repo name will be used as the service name and must be lowercase with hyphens only to be a valid Kubernetes service name."

	pattern: "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$"
	pattern: "^[a-zA-Z0-9._-]+/[a-z0-9][a-z0-9-]{0,62}$"

	Fine-grained PAT with 'Contents: Read' scope.
	Fine-grained PAT with 'Contents: Read' scope. Create at: https://github.com/settings/tokens?type=beta

Conversation

mashkovd commented Feb 20, 2026

Summary

Key Changes

Notable Implementation Details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants