{"id":29875952,"url":"https://github.com/liatrio/ootb-backstage-gitlab","last_synced_at":"2026-05-16T18:33:55.329Z","repository":{"id":305227728,"uuid":"960146737","full_name":"liatrio/ootb-backstage-gitlab","owner":"liatrio","description":"A Backstage configuration for GitLab similar to how we would implement for a client.","archived":false,"fork":false,"pushed_at":"2025-07-30T22:21:20.000Z","size":3848,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-31T00:49:59.383Z","etag":null,"topics":["backstage","client","gitlab","tape"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liatrio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-03T23:55:53.000Z","updated_at":"2025-07-30T22:21:23.000Z","dependencies_parsed_at":"2025-07-19T01:41:30.916Z","dependency_job_id":null,"html_url":"https://github.com/liatrio/ootb-backstage-gitlab","commit_stats":null,"previous_names":["liatrio/ootb-backstage-gitlab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/liatrio/ootb-backstage-gitlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Footb-backstage-gitlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Footb-backstage-gitlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Footb-backstage-gitlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Footb-backstage-gitlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liatrio","download_url":"https://codeload.github.com/liatrio/ootb-backstage-gitlab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liatrio%2Footb-backstage-gitlab/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267979247,"owners_count":24175272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backstage","client","gitlab","tape"],"created_at":"2025-07-31T03:00:38.120Z","updated_at":"2026-05-16T18:33:55.322Z","avatar_url":"https://github.com/liatrio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003ccompnay\u003e backstage portal\n\n## Overview\n\nThis is \u003ccompnay\u003e's implementation of [Backstage](https://backstage.io), an open platform for building developer portals.\n\n[Official Backstage Architecture Overview](https://backstage.io/docs/overview/architecture-overview)\n\n[\u003ccompnay\u003e Backstage Architecture](https://gitlab.com/\u003ccompnay\u003e/ccis/tech-infrastructure-can/sdp/elevate-devx/backstage/design-doc/-/blob/main/docs/diagrams.md)\n\n[Strategies for Adoption](https://backstage.io/docs/overview/adopting)\n\n## Local Development\n\n### Required Software (install locally)\n\n\u003e **Important**: Using the exact versions specified below is crucial for Backstage to work properly.\n\n- Node.js 20 (required)\n  - Recommended: Install via [nvm](https://github.com/nvm-sh/nvm)\n  - Run: `nvm install lts/iron`\n  - Verify version: `node --version` should show `v20.x.x`\n- Yarn 4.4.1 (required)\n  - Run: `corepack enable \u0026\u0026 yarn set version 4.4.1`\n  - Verify version: `yarn --version` should show `4.4.1`\n- Git\n- Podman\n\n## Local Development Setup\n\nYou can run on your machine or in a container.\n\n\u003e from root of repo \u003ccompnay\u003e-backstage\n\n### environment variables\n\n\u003e to start, you must set the following environment variables, but will later define more:\n\n```.env\nBACKSTAGE_ENVIRONMENT=local\nNODE_OPTIONS=--no-node-snapshot\n```\n\n### Machine\n\n1. Install dependencies:\n\n```bash\nyarn install --immutable\nyarn tsc\n```\n\n1. Build the application:\n\n```bash\nyarn build:backend\n```\n\n1. Start the application:\n\n```bash\nyarn start\n```\n\nThe app will be available at `http://localhost:3000`. This will be a locally ran Backstage without ANY auth (no read access to GitLab, no GitLab auth) or techdocs rendering.\n\n#### Local TechDocs Rendering\n\nTo ensure TechDocs documentation renders correctly when triggered in the Backstage UI, you must set up Python and the required mkdocs dependencies in a virtual environment—just like our Docker image does.\n\n**1. Install Python 3**\n\nMake sure you have Python 3.11+ installed (matching the version in the Dockerfile).\n\n**2. Create a Python Virtual Environment**\n\nFrom the root of your repo (or wherever you want):\n\n```bash\npython3 -m venv .techdocs-venv\nsource .techdocs-venv/bin/activate\n```\n\n**3. Install TechDocs Python Packages**\n\nInstall the same mkdocs dependencies as the Dockerfile:\n\n```bash\npip install --no-cache-dir mkdocs-techdocs-core mkdocs-mermaid2-plugin\n```\n\n**4. Start Backstage as Usual**\n\nStart your Backstage app with:\n\n```bash\nyarn start\n```\n\nWhen you visit an entity’s TechDocs tab in the UI, Backstage will use your local Python environment and mkdocs installation to build and render the documentation on demand.\n\n**Notes:**\n- Always activate your `.techdocs-venv` before starting Backstage if you want to use your local Python/mkdocs for TechDocs builds.\n- This setup matches the Python environment used in our Docker image, ensuring consistency between local and containerized TechDocs builds.\n- You do **not** need the TechDocs CLI for normal UI-driven doc rendering.\n\n### Container Build and Run\n\n```bash\n# Set up podman machine (macOS only)\npodman machine init\npodman machine start\npodman machine list\n```\n\n```bash\nexport TMP_TKN=\u003cyour-gitlab-token\u003e\npodman build -f Dockerfile -t localhost/\u003ccompnay\u003e-backstage:latest --env BACKSTAGE_ENVIRONMENT=ci .\npodman run -d -p 7008:7008 --name backstage-app --env BACKSTAGE_ENVIRONMENT=ci --env BACKSTAGE_GITLAB_TOKEN=$TMP_TKN localhost/\u003ccompnay\u003e-backstage:latest\n```\n\n### GitLab Authentication Setup Local Development\n\n1. **Create a GitLab Personal Access Token** with at least \"read_api\" scope. See: [GitLab Personal Access Tokens Docs](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)\n2. **Set up the tokens and secrets for local development**:\n   - Add the required environment variables, e.g.:\n\n     ```bash\n     export BACKSTAGE_GITLAB_TOKEN=your-gitlab-token-here\n     export GITLAB_CLIENT_SECRET=your-gitlab-client-secret-here\n     export GITLAB_CLIENT_ID=your-gitlab-client-id-here\n     ```\n\n   - Or add them to your `.env` file in the project root:\n\n     ```env\n     BACKSTAGE_GITLAB_TOKEN=your-gitlab-token-here\n     GITLAB_CLIENT_SECRET=your-gitlab-client-secret-here\n     GITLAB_CLIENT_ID=your-gitlab-client-id-here\n     ```\n\n3. Ensure your `app-config.local.yaml` or `app-config.yaml` includes the following:\n\n   ```yaml\n   integrations:\n     gitlab:\n       - host: gitlab.com\n         token: ${BACKSTAGE_GITLAB_TOKEN}\n   ```\n\nFor more details, see [Backstage GitLab Integration Docs](https://backstage.io/docs/integrations/gitlab/).\n\n### How container is built\n\n- The Backstage app is built from source code locally on the host machine.\n- The Dockerfile copies the built app and backend files into the container.\n- The Dockerfile points to the configuation file `app-config.yaml`.\n- The container image is tagged as `localhost/\u003ccompnay\u003e-backstage:latest`.\n- The container is run with the following command: `podman run -d -p 7008:7007 --name backstage-app localhost/\u003ccompnay\u003e-backstage:latest`.\n- The container is accessible at `http://localhost:7008`.\n\n## Understanding Backstage Repo\n\n### Project Structure\n\nThe Backstage app will have the following structure:\n\n```text\n\u003ccompnay\u003e-backstage\n├── app-config.yaml     # Main configuration file\n├── app-config.local.yaml # Local development configuration file\n├── app-config.dev.yaml # Development environment configuration file\n├── app-config.qa.yaml # QA environment configuration file\n├── app-config.ci.yaml # CI environment configuration file (for pipeline build)\n├── catalog-info.yaml   # Catalog entities descriptors\n├── package.json        # Root package.json (don't add dependencies here)\n└── packages/\n    ├── app/           # Frontend application\n    └── backend/       # Backend services\n```\n\n#### app-config.*.yaml\n\n##### How configs are loaded by yarn\n\n- The main app-config.yaml uses the $include keyword and ${BACKSTAGE_ENVIRONMENT} variable to dynamically include the correct environment-specific config file (e.g., app-config.dev.yaml, app-config.qa.yaml, etc.).\n- When you run yarn start or build with yarn build:backend, the Backstage CLI reads app-config.yaml, resolves $include statements, and loads the appropriate config based on the value of BACKSTAGE_ENVIRONMENT.\n\n##### Use of BACKSTAGE_ENVIRONMENT\n\n- The BACKSTAGE_ENVIRONMENT environment variable determines which config file is loaded.\n- Example: If BACKSTAGE_ENVIRONMENT=dev, then app-config.yaml will include app-config.dev.yaml.\n- This enables seamless switching between environments (local, dev, qa, ci, prod) without changing code.\n\n##### Why config files must live with the code\n\n- These config files are tightly coupled to the codebase: they define plugin settings, integrations, and secrets that are required for the app to function.\n- They must be version-controlled alongside the code to ensure consistency, reproducibility, and traceability across environments and deployments.\n- Keeping configs with the code ensures that builds are portable and can be reliably reproduced in CI/CD pipelines and local development.\n\n##### How the Dockerfile includes and uses the correct config\n\n- The Dockerfile copies all app-config*.yaml files into the container.\n- At runtime, the container is started with the appropriate BACKSTAGE_ENVIRONMENT variable (passed via --env).\n- The Backstage process (node packages/backend --config app-config.yaml) loads the main config, which dynamically includes the correct environment config based on BACKSTAGE_ENVIRONMENT.\n- This approach allows a single container image to support multiple\n\n## Troubleshooting\n\n### Node.js Version Conflicts\n\nIssue: Build errors due to incompatible Node.js version\n\nSolution: Use Node.js 20 or later. You can use nvm to manage Node.js versions:\n\n```bash\nnvm install 20\nnvm use 20\n```\n\n### 2. Yarn Dependencies\n\nIssue: Dependency resolution errors\n\nSolution: Clear yarn cache and reinstall:\n\n```bash\nyarn cache clean\nrm -rf node_modules\nyarn install\n```\n\n## Available Scripts\n\n- `yarn start` - Start the frontend and backend in development mode\n- `yarn build` - Build the project\n- `yarn lint` - Run linting\n- `yarn test` - Run tests\n- `yarn clean` - Clean up dependencies\n\n## Contributing\n\n1. Create a new branch from `main`\n2. Make your changes\n3. Submit a merge request\n\n## Additional Resources\n\n- [Backstage Documentation](https://backstage.io/docs)\n- [Backstage GitHub](https://github.com/backstage/backstage)\n- [Backstage Discord](https://discord.gg/backstage-687207715902193673)\n\n## Backstage Configuration\n\n### Current State\n\n\u003e statements listed here are not end state goals of the app but should reflect the current iteration of the app\n\n- Backend is currently running with authentication as optional (`dangerouslyDisableDefaultAuthPolicy: true`), allowing all requests without user or service authentication.\n  - This no-auth backend should be removed once real authentication providers (Microsoft SSO \u0026 GitLab SSO) are enabled and tested.\n- Allowing guest sign-in\n  - this should be disabled in production after auth for SSO is setup\n- Localized sql database in use\n  - this should be changed to use an approved external database\n\n### Future Plans - Next Steps for Backstage\n\n\u003e ordered by priority\n\n#### Authentication and User Catalog Management\n\n- **Auth provider summary:**\n  - ⏭️ `todo:` Microsoft authentication (default login)\n    - Current there are servicenow tickets (and associated jira tickets) for dev and qa Azure App registraiont for SSO with the new domain\n      - `what's left to do:` The azure team who is assigned to the tickt will give us the Client ID and Client secrets for each environment\n        - we need to update the app-config.*.yaml files with the new Client ID and Client secrets for a [microsoft provider configuration](https://backstage.io/docs/auth/microsoft/provider/)\n        - we then need to update the App.tsx file to add the new provider to the auth providers list\n  - GitLab authentication (for accessing GitLab project information and pipeline views via the GitLab plugin)\n\n- **Short-term workaround:**\n  - We will maintain a hard-coded catalog of all current users, matching their emails to catalog `User` entities. This allows GitLab authentication and scaffolder actions to work, but requires manual updates as users change.\n    - This catalog of users is currently the Azure Access GitLab Group.\n    - This catalog can be automatically generated using this [backstage-users](https://gitlab.com/\u003ccompnay\u003e/ccis/tech-infrastructure-can/sdp/elevate-devx/backstage/backstage-users) project.\n    - ⏭️ `todo:` if Microsoft SSO is enabled, we need to make a new list of users that includes other non-gitlab technology employees since the current one is only Gitlab users. (or just switch to planned solution - org provider)\n  - This is necessary because neither the Azure (Microsoft) nor GitLab auth providers support the `create` sign-in resolver, which would allow automatic user creation on first login.\n  - Attempted workarounds using custom resolvers are not compatible with the new modular backend system, as only built-in resolvers (such as `catalog` or `email`) are supported for these providers.\n\n- **Planned solution:**\n  - ⏭️ `todo:` Integrate the [Microsoft Entra Tenant Data](https://backstage.io/docs/integrations/azure/org) to automatically sync all Azure AD users and groups into the Backstage catalog.\n  - This will eliminate the need for manual user catalog maintenance, ensure all users can sign in with Microsoft SSO, and allow seamless mapping between Microsoft and GitLab identities (as long as emails match).\n  - Once the org provider is in place, we will remove the hard-coded user catalog and rely on automated user management.\n\n### Database\n\n- ⏭️ `todo:` [Setup PostgreSQL database](https://backstage.io/docs/getting-started/config/database) for dev and qa\n  - requires persistant storage for the dev and qa deployments\n  - Backstage docs for deploying a database](https://backstage.io/docs/deployment/k8s#creating-the-postgresql-database)\n\n### Health Monitoring\n\n- ⏭️ `todo:` Setup health monitoring/alerting for dev and qa\n  - [configure health endpoints](https://backstage.io/docs/plugins/observability#health-checks)\n  - configure alerting is someway to know when health of environments has been impacted based on health endpoint\n  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliatrio%2Footb-backstage-gitlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliatrio%2Footb-backstage-gitlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliatrio%2Footb-backstage-gitlab/lists"}