aws-samples / aws-samples/appmod-blueprints

feat(backstage): GitLab-backed catalog and scaffolder with GitHub chart source

Open
#698 0 comments 0 reactions 0 assignees View on GitHub
agentic-platform
Dominant language
Shell
Stars
105
Forks
62
Avg merge
11h 17m
Merged PRs (30d)
76

Description

## Context

In the `feature/cloudfront-exposure` branch, Backstage catalog was switched from GitLab to GitHub (`aws-samples/appmod-blueprints`) to remove the GitLab dependency for template discovery. However, the scaffolder fails with `401 Unauthorized` when fetching template skeletons because the GitHub API requires authentication even for public repos (rate limiting).

Requiring every workshop participant to provide a GitHub PAT is not feasible.

## Goal

Use **GitLab** (deployed in-cluster) for Backstage catalog and scaffolder operations, while keeping **GitHub** as the source of truth for addon Helm charts (per #574 multi-repo architecture).

## Architecture

```
GitHub (aws-samples/appmod-blueprints)
├── gitops/addons/charts/ → ArgoCD fetches charts directly (public, no auth)
├── gitops/addons/registry/ → ArgoCD fetches addon definitions
├── gitops/bootstrap/ → ArgoCD root-appset source
└── platform/backstage/templates/ → Mirrored to GitLab at init time

GitLab (in-cluster)
├── user1/platform-on-eks-workshop/
│ ├── platform/backstage/templates/ → Backstage catalog location (read)
│ └── gitops/overlays/ → Per-participant value overrides (#574)
└── user1// → Scaffolder creates new repos here
```

## Backstage Configuration Changes

### When GitLab is NOT ready (fallback)
- Catalog: `type: url` pointing to GitHub (read-only, templates visible but scaffolder won't work)
- Integration: GitHub (placeholder token, catalog browsing only)

### When GitLab IS ready (full workshop mode)
- Catalog: `type: url` pointing to GitLab repo
- Integration: GitLab (`GIT_PASSWORD` = GitLab token, `GIT_HOSTNAME` = GitLab domain)
- Scaffolder: fetches skeletons from GitLab, publishes new repos to GitLab
- System-info entity: `gitlab_hostname` populated with actual GitLab domain

### Conditional logic in `install.yaml`
```yaml
integrations:
{{- if .Values.gitlab_domain_name }}
gitlab:
- token: ${GIT_PASSWORD}
host: ${GIT_HOSTNAME}
{{- else }}
github:
- host: github.com
{{- end }}

catalog:
locations:
{{- if .Values.gitlab_domain_name }}
- type: url
target: https://${GIT_HOSTNAME}/${GIT_USERNAME}/${WORKING_REPO}/-/blob/main/platform/backstage/templates/catalog-info.yaml
{{- else }}
- type: url
target: https://github.com/aws-samples/appmod-blueprints/blob/${WORKSHOP_GIT_BRANCH}/platform/backstage/templates/catalog-info.yaml
{{- end }}
```

## Implementation Steps

1. **Enable GitLab addon** in `enabled-addons.yaml`
2. **Add template mirroring step** to Taskfile (`gitlab:seed-templates`)
- Clones templates from GitHub
- Creates GitLab repo via API
- Pushes templates + catalog-info.yaml to GitLab
- Also pushes `gitops/overlays/` for participant customization (#574)
3. **Update Backstage chart** with conditional integration/catalog config (GitLab vs GitHub fallback)
4. **Update `git-credentials` ExternalSecret** to populate `GIT_HOSTNAME`, `GIT_USERNAME`, `WORKING_REPO` from Secrets Manager once GitLab is ready
5. **Seed GitLab credentials** into Secrets Manager (`peeks-hub/secrets` → `git_token`, `git_hostname`)
6. **Restart Backstage** after GitLab is seeded so it picks up the new integration

## Acceptance Criteria

- [ ] GitLab deployed and accessible via CloudFront (`/gitlab`)
- [ ] Templates mirrored from GitHub to GitLab at bootstrap
- [ ] Backstage catalog loads templates from GitLab
- [ ] Scaffolder can fetch skeletons and publish repos to GitLab (no GitHub PAT needed)
- [ ] Participants only need GitLab credentials (auto-provisioned)
- [ ] If GitLab is disabled, Backstage falls back to GitHub (read-only catalog, no scaffolder)

## References

- #574 (Multi-Repo Values Overlay Architecture)
- #690 (CloudFront exposure mode)
- PR #680

Contributor guide

Open the contributing guide

Research direction

Start with enabled-addons.yaml and the Taskfile entry point gitlab:seed-templates, then read install.yaml and the Backstage chart configuration. Trace the git-credentials ExternalSecret and the listed Secrets Manager values. Done means GitLab is available, templates are mirrored at bootstrap, Backstage uses GitLab when configured, and the GitHub fallback remains read-only.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, gitlab, shell, yaml
Domain
cloud, developer-experience, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.