{"id":22660596,"url":"https://github.com/rsc-labs/backstage-highlights-plugin","last_synced_at":"2025-08-06T09:32:35.786Z","repository":{"id":208272963,"uuid":"717144547","full_name":"RSC-Labs/backstage-highlights-plugin","owner":"RSC-Labs","description":"Backstage Highlights Plugin is configurable and customizable plugin for viewing the most important information about your entity.","archived":false,"fork":false,"pushed_at":"2024-04-19T18:58:20.000Z","size":1438,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-04-26T00:24:35.271Z","etag":null,"topics":["backstage","highlights","plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RSC-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-11-10T16:55:55.000Z","updated_at":"2024-06-22T22:13:13.127Z","dependencies_parsed_at":"2024-06-22T22:12:10.061Z","dependency_job_id":"07e1d422-e294-450d-86cb-d11daf272efd","html_url":"https://github.com/RSC-Labs/backstage-highlights-plugin","commit_stats":null,"previous_names":["rsc-labs/backstage-highlights-plugin"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-highlights-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-highlights-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-highlights-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-highlights-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RSC-Labs","download_url":"https://codeload.github.com/RSC-Labs/backstage-highlights-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228879604,"owners_count":17985713,"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","highlights","plugin"],"created_at":"2024-12-09T11:10:37.766Z","updated_at":"2024-12-09T11:10:38.931Z","avatar_url":"https://github.com/RSC-Labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @rsc-labs/backstage-highlights-plugin\n\n\u003cimg src='./docs/highlighter.png' width='100' height='150' alt='Highlights screenshot'\u003e\n\nBackstage Highlights Plugin is configurable and customizable plugin for viewing the most important information about your entity.\n\n### Why?\n\nWe have a lot information from different plugins and also in Overview tab, but sometimes:\n\n- we want to see some short summary from couple of plugins\n- we do not want to jump to every card to get such information\n\nThe \"Highlights\" shall provide you possibility to create such small, useful view.\n\n# Getting started\n\nIf you haven't already, check out the [Backstage docs](https://backstage.io/docs/getting-started/) and create a Backstage application with\n\n```\nnpx @backstage/create-app\n```\n\nThen, you will need to install and configure the highlights plugins for the frontend and the backend.\n\n# Frontend plugin\n\nInstall:\n\n```bash\ncd packages/app\nyarn add @rsc-labs/backstage-highlights-plugin\n```\n\n### Card:\n\nAdd the card to `packages/app/src/components/catalog/EntityPage.tsx`:\n\n```jsx\n// import:\nimport { isGitlabHighlightsAvailable, EntityHighlightsCard } from '@rsc-labs/backstage-highlights-plugin';\n\n// use it in entity view\nconst overviewContent = (\n  \u003cGrid container\n  ...\n    \u003cGrid item md={12} xs={12}\u003e\n      \u003cEntitySwitch\u003e\n          \u003cEntitySwitch.Case if={isGitlabHighlightsAvailable}\u003e\n            \u003cEntityHighlightsCard /\u003e\n          \u003c/EntitySwitch.Case\u003e\n        \u003c/EntitySwitch\u003e\n    \u003c/Grid\u003e\n  \u003c/Grid\u003e\n)\n```\n\nFor the best UX we \u003cb\u003e strongly recommend \u003c/b\u003e to use as much horizontal space as possible. Thanks to that you will have your highlights on top of your page as a bar.\n\n\u003cimg src='./docs/built_in_example.PNG' alt='Built-in example'\u003e\n\nOf course, you can also make it smaller and near the other card.\n\n### Built-in fields\n\nAt this moment, \"highlights plugin\" comes with built-in support of basic information about Git. As you can see in above picture, we support following fields:\n\n- latest tag\n- number of branches\n- latest commit\n- date of latest commit\n- author of latest commit\n- clone button\n\nYou can click at the field and get more information. For example, when you click on latest tag you will get longer history:\n\n\u003cimg src='./docs/commit_table.PNG' alt='Built-in example'\u003e\n\nOther fields can have similar functionality, but it depends on the provider (Github API provides more information)\n\nAt this moment built-in fields supports Github and Gitlab (see: Configuration of Backend).\n\n## Frontend configuration\n\nBy default, you can use EntityHighlights without any parameter - it gives you above built-in fields.\nHowever, you may want change a behaviour or implement your custom fields.\nBelow you can find an interface:\n\n```typescript\n/** @public */\nexport interface EntityHighlightsProps {\n  fields?: EHighlightFields[];\n  customFields?: HighlightCustomField[];\n}\n```\n\n1. fields - this parameter describes what built-in you would like to see and in what order\n2. customFields - this parameter can let you define your own field. Every custom field contains:\n   - fieldLabel - it is a title of the field (you can see it in built-in fields). It is optional parameter as your field can be also without a title (example: Clone button in built-in fields)\n   - field - it is simple React component\n\n# Backend plugin\n\nInstall:\n\n```bash\ncd packages/backend\nyarn add @rsc-labs/backstage-highlights-plugin-backend\n```\n\nCreate a file `packages/backend/src/plugins/highlights.ts`:\n\n```typescript\nimport { createRouter } from '@rsc-labs/backstage-highlights-plugin-backend';\nimport { Router } from 'express';\nimport { PluginEnvironment } from '../types';\n\nexport default async function createPlugin(\n  env: PluginEnvironment,\n): Promise\u003cRouter\u003e {\n  return await createRouter({\n    discovery: env.discovery,\n    tokenManager: env.tokenManager,\n    logger: env.logger,\n    config: env.config,\n  });\n}\n```\n\nAdd the plugin to `packages/backend/src/index.ts`:\n\n```typescript\n// import:\nimport highlights from './plugins/highlights';\n...\n\nasync function main() {\n  ...\n  // add env\n  const highlightsEnv = useHotMemoize(module, () =\u003e createEnv('highlights'));\n  ...\n  // add to router\n  apiRouter.use('/highlights', await highlights(highlightsEnv));\n  ...\n}\n```\n\n## Catalog-info.yaml\n\nBackend plugin supports two providers - Github and Gitlab. They are providing information for built-in fields mentioned in Frontend plugin.\nPlugin uses following annotations from catalog-info.yaml:\n\n```yaml\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  name: example-website\n  annotations:\n    github.com/project-slug: rsc-labs/backstage-changelog-plugin\n    gitlab.com/project-slug: owner/project\n    gitlab.com/instance: gitlab.instance.com\n```\n\nBoth \u003cb\u003e/project-slug\u003c/b\u003e are supported (so your component can be in github or gitlab). In theory case if you have both annotations, github takes precedence.\n\n\u003cb\u003egitlab.com/instance\u003c/b\u003e annotation is used for [Multiple Gitlab instances](#multiple-gitlab-instances)\n\n## App-config\n\nTo have properly working Github or Gitlab, you need also provide information about token and potentially about base url.\nYou have two options how to provide it\n\n1. Custom highlights configuration\n2. Integration configuration\n\nBelow you can find implemented both options:\n\n```yaml\nhighlights:\n  gitlab:\n    token: ${GITLAB_TOKEN}\n    apiBaseUrl: https://gitlab.com/api/v4\n  github:\n    token: ${GITHUB_TOKEN}\n\nintegrations:\n  gitlab:\n    - token: ${GITLAB_TOKEN}\n  github:\n    - token: ${GITHUB_TOKEN}\n```\n\nIf provided, \"highlights\" configuration takes precendece over \"integrations\".\n\u003cb\u003eNote:\u003c/b\u003e \"highlights\" configuration requires providing \"apiBaseUrl\", while it is not needed in \"integrations\" (if you are using default one)\n\n### Multiple Gitlab instances\n\nWe start supporting also multiple Gitlab instances for both highlights and integrations in app-config. Below you can find instruction and example of configuration.\n\n1. If you would like to use \"highlights\" configuration, then you need to change it to a list instead of one object. Additionally, we need to be able to figure out which instance is used for which entity, so \u003cb\u003ehost\u003c/b\u003e annotation is needed (see example below). For backward compatibility, we still support single object.\n2. Similarly with \u003cb\u003eintegrations\u003c/b\u003e. We already support a list, but to use multiple Gitlab instances, you need to also provide \u003cb\u003ehost\u003c/b\u003e and \u003cb\u003eapiBaseUrl\u003c/b\u003e (see example below)\n\nExample of both options in one configuration:\n\n```yaml\nhighlights:\n  gitlab:\n    - host: gitlab.com\n      token: ${GITLAB_TOKEN}\n      apiBaseUrl: https://gitlab.com/api/v4\n    - host: gitlab1.com\n      token: ${GITLAB2_TOKEN}\n      apiBaseUrl: https://gitlab1.com/api/v4\n  github:\n    token: ${GITHUB_TOKEN}\n\nintegrations:\n  gitlab:\n    - host: gitlab.com\n      token: ${GITLAB_TOKEN}\n    - host: gitlab1.com\n      token: ${GITLAB2_TOKEN}\n      apiBaseUrl: https://gitlab1.com/api/v4\n  github:\n    - host: github.com\n      token: ${GITHUB_TOKEN}\n```\n\nAt the same time, your entity shall have proper annotations, for example:\n\n```yaml\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  name: example-website\n  annotations:\n    github.com/project-slug: rsc-labs/backstage-changelog-plugin\n    gitlab.com/project-slug: owner/project\n    gitlab.com/instance: gitlab1.com\n```\n\nTaking above example - component \u003cb\u003eexample-website\u003c/b\u003e will use \u003cb\u003egitlab1.com\u003c/b\u003e, which maps to values:\n\n- host: gitlab1.com\n- token: ${GITLAB2_TOKEN}\n- apiBaseUrl: https://gitlab1.com/api/v4\n\nPlease remember that \"highlights\" configuration (if present) takes precendence over \"integrations\".\n\n## TODO\n\n[ ] Unit tests\n\n[ ] More fields to support\n\n## Contribution\n\nContributions are welcome and they are greatly appreciated!\n\n## License\n\nLicensed under the Mozilla Public License, Version 2.0: https://www.mozilla.org/en-US/MPL/2.0/\n\n---\n\n© 2023 RSC https://rsoftcon.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsc-labs%2Fbackstage-highlights-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frsc-labs%2Fbackstage-highlights-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsc-labs%2Fbackstage-highlights-plugin/lists"}