{"id":13527451,"url":"https://github.com/immobiliare/backstage-plugin-gitlab","last_synced_at":"2026-04-02T19:44:37.913Z","repository":{"id":64383380,"uuid":"497891862","full_name":"immobiliare/backstage-plugin-gitlab","owner":"immobiliare","description":"Backstage plugins to interact with GitLab","archived":false,"fork":false,"pushed_at":"2025-03-31T12:48:27.000Z","size":8314,"stargazers_count":122,"open_issues_count":10,"forks_count":44,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-31T20:05:29.308Z","etag":null,"topics":["backstage","backstage-plugin","gitlab","gitlab-ci","hacktoberfest","plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"loblaw-sre/backstage-plugin-gitlab","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/immobiliare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-30T10:21:07.000Z","updated_at":"2025-03-31T12:48:11.000Z","dependencies_parsed_at":"2023-01-15T14:45:37.028Z","dependency_job_id":"f5dc7657-4be8-486c-9a23-d5f231cf3997","html_url":"https://github.com/immobiliare/backstage-plugin-gitlab","commit_stats":{"total_commits":386,"total_committers":42,"mean_commits":9.19047619047619,"dds":0.5854922279792747,"last_synced_commit":"829e522cfef1281b1f98b6f5363f2f357056cce0"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fbackstage-plugin-gitlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fbackstage-plugin-gitlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fbackstage-plugin-gitlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Fbackstage-plugin-gitlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immobiliare","download_url":"https://codeload.github.com/immobiliare/backstage-plugin-gitlab/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247730068,"owners_count":20986404,"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","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","backstage-plugin","gitlab","gitlab-ci","hacktoberfest","plugin"],"created_at":"2024-08-01T06:01:48.270Z","updated_at":"2026-04-02T19:44:37.908Z","avatar_url":"https://github.com/immobiliare.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://avatars.githubusercontent.com/u/10090828?s=200\u0026v=4\" width=\"200px\" alt=\"logo\"/\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eBackstage GitLab\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Backstage-%3E%3D%201.48.3-%239c27b0?style=flat-square\u0026logo=backstage\" alt=\"Backstage Version Support\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/@immobiliarelabs/backstage-plugin-gitlab-backend?style=flat-square\" alt=\"npm (scoped)\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/immobiliare/backstage-plugin-gitlab?style=flat-square\" alt=\"license\" /\u003e\n\u003c/p\u003e\n\n\u003e [Backstage](https://backstage.io/) plugins to interact with [GitLab](https://gitlab.com/)\n\n\u003e **Note:** This version works on Backstage 1.48+. If you are using an older version of Backstage, please use the older v4 of this plugin.\n\n## Table of contents\n\n\u003c!-- toc --\u003e\n\n- [Features](#features)\n- [Screenshots](#screenshots)\n- [Setup](#setup)\n  - [Requirements](#requirements)\n  - [Setup Frontend Plugin](#setup-frontend-plugin)\n    - [New Frontend System (Alpha)](#new-frontend-system-alpha)\n  - [Setup Backend Plugin](#setup-backend-plugin)\n  - [Extra OIDC/OAuth](#extra-oidcoauth)\n  - [Register To The New Backend System](#register-to-the-new-backend-system)\n- [Annotations](#annotations)\n  - [Code owners file](#code-owners-file)\n- [Old/New GitLab Versions](#oldnew-gitlab-versions)\n- [Migration guides](#migration-guides)\n- [Support \u0026 Contribute](#support--contribute)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## Features\n\n- List top 20 builds for a project\n- List top 20 Merge Requests for a project\n- List top 20 Issues for a project\n- List last releases\n- View Code Owners for a project\n- View Contributors for a project\n- View Languages used for a project\n- View Pipeline status for a project\n- View README for a project (with partial support for GLFM)\n- Works for both project and personal tokens\n- Pagination for builds\n- Pagination for Merge Requests\n- Merge Requests Statistics\n- Support for Olds/New GitLab APIs version\n- Support for multi GitLab Instance\n\n## Screenshots\n\n\u003cimg src=\"https://raw.githubusercontent.com/immobiliare/backstage-plugin-gitlab/main/assets/backstage_gitlab_pipeline_information.png\"  alt=\"Contributors Languages Pipeline Status\"/\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/immobiliare/backstage-plugin-gitlab/main/assets/backstage_gitlab_mr_and_issues.png\"  alt=\"Merge Request Information\"/\u003e\n\n## Setup\n\n1. Install packages:\n\n```bash\n# From your Backstage root directory\nyarn --cwd packages/app add @immobiliarelabs/backstage-plugin-gitlab\nyarn --cwd packages/backend add @immobiliarelabs/backstage-plugin-gitlab-backend\n```\n\n### Requirements\n\n| Tool       | Version                             | Notes                                                        |\n| ---------- | ----------------------------------- | ------------------------------------------------------------ |\n| Node.js    | \u003e=24.0.0 (pinned 24.14.1 via Volta) | See `engines` and `volta` in root `package.json`             |\n| Yarn       | 4.3.1 (Berry)                       | `node-modules` linker — not PnP                              |\n| TypeScript | ~6.0.2                              | Strict mode; `noUnusedLocals`, `noUnusedParameters` enforced |\n\n### Setup Frontend Plugin\n\n1. Add a new GitLab tab to the entity page.\n\n\u003e NOTE: By default the EntityGitlabContent does not load the README, see the Optional section.\n\n`packages/app/src/components/catalog/EntityPage.tsx`\n\n```tsx\n// packages/app/src/components/catalog/EntityPage.tsx\n\nimport {\n  isGitlabAvailable,\n  EntityGitlabContent,\n} from \"@immobiliarelabs/backstage-plugin-gitlab\";\n\n// Farther down at the serviceEntityPage declaration\nconst serviceEntityPage = (\n  \u003cEntityLayout\u003e\n    {/* Place the following section where you want the tab to appear */}\n    \u003cEntityLayout.Route if={isGitlabAvailable} path=\"/gitlab\" title=\"Gitlab\"\u003e\n      \u003cEntityGitlabContent /\u003e\n    \u003c/EntityLayout.Route\u003e\n  \u003c/EntityLayout\u003e\n);\n```\n\n\u003e NOTE: CI uses **Node 24.x** (GitHub Actions `actions/setup-node`). Update `test.yml` when the Node version changes.\n\n2. (**Optional**) Add the GitLab cards to the Overview tab on the entity page.\n\n`packages/app/src/components/catalog/EntityPage.tsx`\n\n```tsx\n// packages/app/src/components/catalog/EntityPage.tsx\n\nimport {\n  isGitlabAvailable,\n  EntityGitlabContent,\n  EntityGitlabLanguageCard,\n  EntityGitlabMergeRequestsTable,\n  EntityGitlabMergeRequestStatsCard,\n  EntityGitlabPeopleCard,\n  EntityGitlabPipelinesTable,\n  EntityGitlabReadmeCard,\n  EntityGitlabReleasesCard,\n} from \"@immobiliarelabs/backstage-plugin-gitlab\";\n\n//Farther down at the overviewContent declaration\n//You can add only selected widgets or all of them.\nconst overviewContent = (\n  \u003cGrid container spacing={3} alignItems=\"stretch\"\u003e\n    \u003cEntitySwitch\u003e\n      \u003cEntitySwitch.Case if={isGitlabAvailable}\u003e\n        \u003cGrid item md={12}\u003e\n          \u003cEntityGitlabReadmeCard /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item sm={12} md={3} lg={3}\u003e\n          \u003cEntityGitlabPeopleCard /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item sm={12} md={3} lg={3}\u003e\n          \u003cEntityGitlabLanguageCard /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item sm={12} md={3} lg={3}\u003e\n          \u003cEntityGitlabMergeRequestStatsCard /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item sm={12} md={3} lg={3}\u003e\n          \u003cEntityGitlabReleasesCard /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item md={12}\u003e\n          \u003cEntityGitlabPipelinesTable /\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item md={12}\u003e\n          \u003cEntityGitlabMergeRequestsTable /\u003e\n        \u003c/Grid\u003e\n      \u003c/EntitySwitch.Case\u003e\n    \u003c/EntitySwitch\u003e\n  \u003c/Grid\u003e\n);\n```\n\n3. Add the integration:\n   `app-config.yaml` add the integration for gitlab:\n\n```yaml\nintegrations:\n  gitlab:\n    - host: gitlab.com\n      token: ${GITLAB_TOKEN}\n```\n\n**Note:** You can have more than one GitLab instance.\n\n#### New Frontend System (Alpha)\n\nThe Gitlab plugin currently support the New Frontend System via an `/alpha` export, here's how to use it:\n\n1. Install the frontend plugin:\n\n   ```bash\n   # From your Backstage root directory\n   yarn --cwd packages/app add @immobiliarelabs/backstage-plugin-gitlab\n   ```\n\n2. If you have [Feature Discovery](https://backstage.io/docs/frontend-system/architecture/app#feature-discovery) enabled, no additional configuration is required. Otherwise, you should be able to enable the plugin in your `packages/app(-next)/src/App.tsx`:\n\n   ```diff\n   + import gitlabPlugin from '@immobiliarelabs/backstage-plugin-gitlab/alpha';\n\n     export const app = createApp({\n         features: [\n             catalogPlugin,\n             catalogImportPlugin,\n             userSettingsPlugin,\n   +         gitlabPlugin,\n             // ...\n         ],\n     });\n   ```\n\n   3. To display specific GitLab cards on the overview page, list them in your `app-config.yaml` under the `app.extensions` section. For example:\n\n   ```yaml\n   app:\n     extensions:\n       - entity-card:gitlab/people\n       - entity-card:gitlab/languages\n       - entity-card:gitlab/merge-requests-stats\n       - entity-card:gitlab/releases\n       - entity-card:gitlab/coverage\n       - entity-card:gitlab/readme\n   ```\n\n   Add or remove cards as needed to customize your overview page.\n\n### Setup Backend Plugin\n\n\u003e NOTE: Currently backstage supports a new way to register backend plugins, see the [Register To The New Backend System](#register-to-the-new-backend-system) section.\n\n1. Add the GitLab Filler Processor, this allows auto-filling of the annotations like the project id and slug:\n\n`packages/backend/src/plugins/catalog.ts`\n\n```ts\n// packages/backend/src/plugins/catalog.ts\nimport { GitlabFillerProcessor } from \"@immobiliarelabs/backstage-plugin-gitlab-backend\";\n\nexport default async function createPlugin(\n  env: PluginEnvironment,\n): Promise\u003cRouter\u003e {\n  const builder = await CatalogBuilder.create(env);\n  //...\n  // Add this line\n  builder.addProcessor(new GitlabFillerProcessor(env.config));\n  //...\n  const { processingEngine, router } = await builder.build();\n  await processingEngine.start();\n  return router;\n}\n```\n\nThis allows auto-filling of the annotations.\n\n2. Add the `gitlab` route by creating the file `packages/backend/src/plugins/gitlab.ts`:\n\n`packages/backend/src/plugins/gitlab.ts`\n\n```ts\n// packages/backend/src/plugins/gitlab.ts\nimport { PluginEnvironment } from \"../types\";\nimport { Router } from \"express-serve-static-core\";\nimport { createRouter } from \"@immobiliarelabs/backstage-plugin-gitlab-backend\";\n\nexport default async function createPlugin(\n  env: PluginEnvironment,\n): Promise\u003cRouter\u003e {\n  return createRouter({\n    logger: env.logger,\n    config: env.config,\n  });\n}\n```\n\nthen you have to add the route as follows:\n\n`packages/backend/src/index.ts`\n\n```ts\n// packages/backend/src/index.ts\nimport gitlab from \"./plugins/gitlab\";\n\nasync function main() {\n  //...\n  const gitlabEnv = useHotMemoize(module, () =\u003e createEnv(\"gitlab\"));\n  //...\n  apiRouter.use(\"/gitlab\", await gitlab(gitlabEnv));\n  //...\n}\n```\n\n3. (**Optional**): You can also add plugin configurations in `app-config.yaml` file:\n\n`app-config.yaml`\n\n```yaml\n# app-config.yaml\n# ...\ngitlab:\n  # Default path for CODEOWNERS file\n  # Default: CODEOWNERS\n  defaultCodeOwnersPath: .gitlab/CODEOWNERS\n  # Default path for README file\n  # Default: README.md\n  defaultReadmePath: .gitlab/README.md\n  # Entity Kinds to which the plugin works, if you want to render gitlab\n  # information for one Kind you have to add it in this list.\n  # Default: ['Component']\n  allowedKinds: [\"Component\", \"Resource\"]\n  # This parameter controls SSL Certs verification\n  # Default: true\n  proxySecure: false\n  # Activate Oauth/OIDC\n  # Default: false\n  useOAuth: false\n  # Cache configuration\n  cache:\n    # Enable caching for the Gitlab plugin\n    # Default: false\n    enabled: true\n    # Cache TTL for the Gitlab plugin in seconds\n    # Default: 300\n    ttl: 300\n```\n\n### Extra OIDC/OAuth\n\nBy default, this plugin utilizes the token specified in the configuration file `app-config.yaml` under the key: `integrations.gitlab[i].token`. However, you can opt out of using this token by activating OIDC as shown below:\n\n```yaml\ngitlab:\n  useOAuth: true\n```\n\n**Note:**: To use OIDC you have to configure the `@backstage/plugin-auth-backend-module-gitlab-provider` plugin.\n**Note:**: OIDC does not allow multi GitLab instances!\n\n### Register To The New Backend System\n\nIf you're already using the [New Backend System](https://backstage.io/docs/backend-system/), registering backend plugins will become much easier:\n\n`packages/backend/src/index.ts`\n\n```ts\n// packages/backend/src/index.ts\nimport {\n  gitlabPlugin,\n  catalogPluginGitlabFillerProcessorModule,\n} from \"@immobiliarelabs/backstage-plugin-gitlab-backend\";\n\nasync function start() {\n  const backend = createBackend();\n\n  // ...\n  backend.add(gitlabPlugin);\n  backend.add(catalogPluginGitlabFillerProcessorModule);\n\n  // ...\n}\n```\n\n## Annotations\n\nBy default, the plugin automatically shows the project info corresponding to the location of the `catalog.yaml` file. But you could need some time to force another project, you can do it with the annotations `gitlab.com/project-id` or `gitlab.com/project-slug`:\n\n```yaml\n# Example catalog-info.yaml entity definition file\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  # ...\n  annotations:\n    gitlab.com/project-id: \"project-id\" #1234. This must be in quotes and can be found under Settings --\u003e General\n    # or\n    gitlab.com/project-slug: \"project-slug\" # group_name/project_name\n    # or\n    gitlab.com/instance: gitlab.internal.abcd # abcd, represents local instance used\nspec:\n  type: service\n  # ...\n```\n\nIt's possible to disable the GitLab plugins and cards by setting these annotations to an empty string.\n\nThis is useful if the entity (catalog-info.yaml) is hosted on GitLab but the actual source code is hosted\nsomewhere else or GitLab isn't used for issue tracking.\n\n```yaml\n# Example catalog-info.yaml entity definition file\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  # ...\n  annotations:\n    gitlab.com/instance: \"\" # don't show the issue and merge requests cards\n    gitlab.com/project-slug: \"\"\nspec:\n  type: service\n  # ...\n```\n\n### Code owners file\n\nThe plugins support also the `gitlab.com/codeowners-path` annotation:\n\n```yaml\n# Example catalog-info.yaml entity definition file\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  # ...\n  annotations:\n    # You can change the CODEOWNERS path\n    # if it is not passed default specified in `app-config.yaml` is used\n    gitlab.com/codeowners-path: \"somewhere/CODEOWNERS\"\nspec:\n  type: service\n  # ...\n```\n\n## Old/New GitLab Versions\n\nIf you have an old GitLab version, or a new one, we allow you to extend the GitLab Client as follows:\n\n`packages/app/src/api.ts`\n\n```ts\nimport { GitlabCIApiRef } from \"@immobiliarelabs/backstage-plugin-gitlab\";\nimport { CustomGitlabCIClient } from \"@immobiliarelabs/backstage-plugin-gitlab\";\nimport { discoveryApiRef, configApiRef } from \"@backstage/core-plugin-api\";\nimport { CustomGitlabCIClient } from \"packages/app/src/myCustomClient.ts\";\n\nexport const apis: AnyApiFactory[] = [\n  createApiFactory({\n    api: GitlabCIApiRef,\n    deps: { configApi: configApiRef, discoveryApi: discoveryApiRef },\n    factory: ({ configApi, discoveryApi }) =\u003e\n      CustomGitlabCIClient.setupAPI({\n        discoveryApi,\n        codeOwnersPath: configApi.getOptionalString(\n          \"gitlab.defaultCodeOwnersPath\",\n        ),\n        readmePath: configApi.getOptionalString(\"gitlab.defaultReadmePath\"),\n      }),\n  }),\n];\n```\n\n`packages/app/src/myCustomClient.ts`\n\n```ts\nimport { GitlabCIClient } from '@immobiliarelabs/backstage-plugin-gitlab';\n\nexport class CustomGitlabCIClient extends GitlabCIClient {\n    // Override methods\n    async getPipelineSummary(projectID: string | undefined): Promise\u003cPipelineSummary | undefined\u003e {\n        this.callApi(...)\n        .\n        .\n        .\n    }\n}\n```\n\nsee [here](./packages/gitlab/src/api/GitlabCIClient.ts).\n\n## Migration guides\n\nIf you have an old gitlab-plugin version, you can consult the [migration guide](./docs/migration-guides.md).\n\n## Support \u0026 Contribute\n\nMade with ❤️ by [ImmobiliareLabs](https://github.com/immobiliare) \u0026 [Contributors](./CONTRIBUTING.md#contributors)\n\nWe'd love for you to contribute to Backstage GitLab Plugin! [Here](./CONTRIBUTING.md) some tips on how to contribute.\nIf you have any questions on how to use Backstage GitLab Plugin, bugs and enhancement please feel free to reach out by opening a [GitHub Issue](https://github.com/immobiliare/backstage-plugin-gitlab/issues).\n\n## License\n\nThis plugin is based on the original work of [loblaw-sre/backstage-plugin-gitlab](https://github.com/loblaw-sre/backstage-plugin-gitlab) by [satrox28](https://github.com/satrox28) and [balasundaram](https://github.com/Balasundaram)\n\nThis plugin is under [Apache 2.0 license](LICENSE), see [NOTICE](NOTICE) for copyright.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Fbackstage-plugin-gitlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmobiliare%2Fbackstage-plugin-gitlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Fbackstage-plugin-gitlab/lists"}