Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@immobiliarelabs/backstage-plugin-gitlab

immobiliare29.9kApache-2.06.11.0TypeScript support: included

null

backstage, gitlab, ci/cd, immobiliare, immobiliarelabs

readme

logo

Backstage Plugin GitLab

code style: prettier semantic-release npm (scoped) license

Backstage plugins to interact with GitLab

Table of contents

Features

  • List top 20 builds for a project
  • List top 20 Merge Requests for a project
  • List top 20 Issues for a project
  • List last releases
  • View Code Owners for a project
  • View Contributors for a project
  • View Languages used for a project
  • View Pipeline status for a project
  • View README for a project (with partial support for GLFM)
  • Works for both project and personal tokens
  • Pagination for builds
  • Pagination for Merge Requests
  • Merge Requests Statistics
  • Support for Olds/New GitLab APIs version
  • Support for multi GitLab Instance

Screenshots

Contributors Languages Pipeline Status Merge Request Information

Setup

  1. Install packages:
# From your Backstage root directory
yarn --cwd packages/app add @immobiliarelabs/backstage-plugin-gitlab
yarn --cwd packages/backend add @immobiliarelabs/backstage-plugin-gitlab-backend

Setup Frontend Plugin

  1. Add a new GitLab tab to the entity page.

NOTE: By default the EntityGitlabContent does not load the README, see the Optional section.

packages/app/src/components/catalog/EntityPage.tsx

// packages/app/src/components/catalog/EntityPage.tsx

import {
    isGitlabAvailable,
    EntityGitlabContent,
} from '@immobiliarelabs/backstage-plugin-gitlab';

// Farther down at the serviceEntityPage declaration
const serviceEntityPage = (
    <EntityLayout>
        {/* Place the following section where you want the tab to appear */}
        <EntityLayout.Route
            if={isGitlabAvailable}
            path="/gitlab"
            title="Gitlab"
        >
            <EntityGitlabContent />
        </EntityLayout.Route>
    </EntityLayout>
);
  1. (Optional) Add the GitLab cards to the Overview tab on the entity page.

packages/app/src/components/catalog/EntityPage.tsx

// packages/app/src/components/catalog/EntityPage.tsx

import {
    isGitlabAvailable,
    EntityGitlabContent,
    EntityGitlabLanguageCard,
    EntityGitlabMergeRequestsTable,
    EntityGitlabMergeRequestStatsCard,
    EntityGitlabPeopleCard,
    EntityGitlabPipelinesTable,
    EntityGitlabReadmeCard,
    EntityGitlabReleasesCard,
} from '@immobiliarelabs/backstage-plugin-gitlab';

//Farther down at the overviewContent declaration
//You can add only selected widgets or all of them.
const overviewContent = (
    <Grid container spacing={3} alignItems="stretch">
        <EntitySwitch>
            <EntitySwitch.Case if={isGitlabAvailable}>
                <Grid item md={12}>
                    <EntityGitlabReadmeCard />
                </Grid>
                <Grid item sm={12} md={3} lg={3}>
                    <EntityGitlabPeopleCard />
                </Grid>
                <Grid item sm={12} md={3} lg={3}>
                    <EntityGitlabLanguageCard />
                </Grid>
                <Grid item sm={12} md={3} lg={3}>
                    <EntityGitlabMergeRequestStatsCard />
                </Grid>
                <Grid item sm={12} md={3} lg={3}>
                    <EntityGitlabReleasesCard />
                </Grid>
                <Grid item md={12}>
                    <EntityGitlabPipelinesTable />
                </Grid>
                <Grid item md={12}>
                    <EntityGitlabMergeRequestsTable />
                </Grid>
            </EntitySwitch.Case>
        </EntitySwitch>
    </Grid>
);
  1. Add the integration: app-config.yaml add the integration for gitlab:
integrations:
    gitlab:
        - host: gitlab.com
          token: ${GITLAB_TOKEN}

Note: You can have more than one GitLab instance.

Setup Backend Plugin

NOTE: Currently backstage supports a new way to register backend plugins, see the Register To The New Backend System section.

  1. Add the GitLab Filler Processor, this allows auto-filling of the annotations like the project id and slug:

packages/backend/src/plugins/catalog.ts

// packages/backend/src/plugins/catalog.ts
import { GitlabFillerProcessor } from '@immobiliarelabs/backstage-plugin-gitlab-backend';

export default async function createPlugin(
    env: PluginEnvironment
): Promise<Router> {
    const builder = await CatalogBuilder.create(env);
    //...
    // Add this line
    builder.addProcessor(new GitlabFillerProcessor(env.config));
    //...
    const { processingEngine, router } = await builder.build();
    await processingEngine.start();
    return router;
}

This allows auto-filling of the annotations.

  1. Add the gitlab route by creating the file packages/backend/src/plugins/gitlab.ts:

packages/backend/src/plugins/gitlab.ts

// packages/backend/src/plugins/gitlab.ts
import { PluginEnvironment } from '../types';
import { Router } from 'express-serve-static-core';
import { createRouter } from '@immobiliarelabs/backstage-plugin-gitlab-backend';

export default async function createPlugin(
    env: PluginEnvironment
): Promise<Router> {
    return createRouter({
        logger: env.logger,
        config: env.config,
    });
}

then you have to add the route as follows:

packages/backend/src/index.ts

// packages/backend/src/index.ts
import gitlab from './plugins/gitlab';

async function main() {
    //...
    const gitlabEnv = useHotMemoize(module, () => createEnv('gitlab'));
    //...
    apiRouter.use('/gitlab', await gitlab(gitlabEnv));
    //...
}
  1. (Optional): You can also add plugin configurations in app-config.yaml file:

app-config.yaml

# app-config.yaml
# ...
gitlab:
    # Default path for CODEOWNERS file
    # Default: CODEOWNERS
    defaultCodeOwnersPath: .gitlab/CODEOWNERS
    # Default path for README file
    # Default: README.md
    defaultReadmePath: .gitlab/README.md
    # Entity Kinds to which the plugin works, if you want to render gitlab
    # information for one Kind you have to add it in this list.
    # Default: ['Component']
    allowedKinds: ['Component', 'Resource']
    # This parameter controls SSL Certs verification
    # Default: true
    proxySecure: false
    # Activate Oauth/OIDC
    # Default: false
    useOAuth: false
    # Cache configuration
    cache:
        # Enable caching for the Gitlab plugin
        # Default: false
        enabled: true
        # Cache TTL for the Gitlab plugin in seconds
        # Default: 300
        ttl: 300

Extra OIDC/OAuth

By 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:

gitlab:
    useOAuth: true

Note:: To use OIDC you have to configure the @backstage/plugin-auth-backend-module-gitlab-provider plugin. Note:: OIDC does not allow multi GitLab instances!

Register To The New Backend System

If you're already using the New Backend System, registering backend plugins will become much easier:

packages/backend/src/index.ts

// packages/backend/src/index.ts
import {
    gitlabPlugin,
    catalogPluginGitlabFillerProcessorModule,
} from '@immobiliarelabs/backstage-plugin-gitlab-backend';

async function start() {
    const backend = createBackend();

    // ...
    backend.add(gitlabPlugin);
    backend.add(catalogPluginGitlabFillerProcessorModule);

    // ...
}

Annotations

By 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:

# Example catalog-info.yaml entity definition file
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
    # ...
    annotations:
        gitlab.com/project-id: 'project-id' #1234. This must be in quotes and can be found under Settings --> General
        # or
        gitlab.com/project-slug: 'project-slug' # group_name/project_name
        # or
        gitlab.com/instance: gitlab.internal.abcd # abcd, represents local instance used
spec:
    type: service
    # ...

It's possible to disable the GitLab plugins and cards by setting these annotations to an empty string.

This is useful if the entity (catalog-info.yaml) is hosted on GitLab but the actual source code is hosted somewhere else or GitLab isn't used for issue tracking.

# Example catalog-info.yaml entity definition file
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
    # ...
    annotations:
        gitlab.com/instance: '' # don't show the issue and merge requests cards
        gitlab.com/project-slug: ''
spec:
    type: service
    # ...

Code owners file

The plugins support also the gitlab.com/codeowners-path annotation:

# Example catalog-info.yaml entity definition file
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
    # ...
    annotations:
        # You can change the CODEOWNERS path
        # if it is not passed default specified in `app-config.yaml` is used
        gitlab.com/codeowners-path: 'somewhere/CODEOWNERS'
spec:
    type: service
    # ...

Old/New GitLab Versions

If you have an old GitLab version, or a new one, we allow you to extend the GitLab Client as follows:

packages/app/src/api.ts

import { GitlabCIApiRef } from '@immobiliarelabs/backstage-plugin-gitlab';
import { CustomGitlabCIClient } from '@immobiliarelabs/backstage-plugin-gitlab';
import { discoveryApiRef, configApiRef } from '@backstage/core-plugin-api';
import { CustomGitlabCIClient } from 'packages/app/src/myCustomClient.ts';

export const apis: AnyApiFactory[] = [
    createApiFactory({
        api: GitlabCIApiRef,
        deps: { configApi: configApiRef, discoveryApi: discoveryApiRef },
        factory: ({ configApi, discoveryApi }) =>
            CustomGitlabCIClient.setupAPI({
                discoveryApi,
                codeOwnersPath: configApi.getOptionalString(
                    'gitlab.defaultCodeOwnersPath'
                ),
                readmePath: configApi.getOptionalString(
                    'gitlab.defaultReadmePath'
                ),
            }),
    }),
];

packages/app/src/myCustomClient.ts

import { GitlabCIClient } from '@immobiliarelabs/backstage-plugin-gitlab';

export class CustomGitlabCIClient extends GitlabCIClient {
    // Override methods
    async getPipelineSummary(projectID: string | undefined): Promise<PipelineSummary | undefined> {
        this.callApi(...)
        .
        .
        .
    }
}

see here.

Migration guides

If you have an old gitlab-plugin version, you can consult the migration guide.

Support & Contribute

Made with ❤️ by ImmobiliareLabs & Contributors

We'd love for you to contribute to Backstage GitLab Plugin! Here some tips on how to contribute. If 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.

License

This plugin is based on the original work of loblaw-sre/backstage-plugin-gitlab by satrox28 and balasundaram

This plugin is under Apache 2.0 license, see NOTICE for copyright.

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

6.11.0 (2025-03-31)

Note: Version bump only for package root

6.11.0-alpha.0 (2025-03-28)

Features

6.10.0 (2025-03-19)

Features

  • added possibility to disable members list (5ddb5bf)

6.10.0-alpha.0 (2025-03-18)

Bug Fixes

  • Fix RepositoryMemberSchema type error (59a06b0)

Features

  • add members list in people card (84c3b18)
  • api: added api request for all tags from repository (f3bb023)

6.9.0 (2025-03-03)

Note: Version bump only for package root

6.9.0-alpha.0 (2025-03-03)

Features

  • upgrade backstage dependecies (2b063a6)

6.8.0 (2025-01-30)

Note: Version bump only for package root

6.8.0-alpha.1 (2025-01-29)

Bug Fixes

  • disable cache by default (dd63bfd)

6.8.0-alpha.0 (2025-01-28)

Bug Fixes

  • Add readme_path to the dependencies of ReadmeCard (9dc9978)
  • added missing ttl (6b8dd38)
  • forget await in case of string (c17edcf)
  • Re-render when the GitlabIds change (3082892)

Features

  • backstage deps and caching (55c2c44)

6.7.0 (2024-10-18)

Features

  • backend: add support for empty string annotations (704620f)

6.6.1 (2024-10-15)

Bug Fixes

  • Update CODEOWNERS parsing to align to Gitlab's official username regex (1f5a62a)

Features

  • updating the initial contributors (9279f70)

6.6.0 (2024-07-23)

Note: Version bump only for package root

6.6.0-alpha.0 (2024-07-23)

Features

  • bump dependencies to 1.29.1 (d481b34)
  • readme: ✨ adds partial support for GLFM (bfce13b)

6.5.1 (2024-05-16)

Note: Version bump only for package root

6.5.1-alpha.0 (2024-05-16)

Note: Version bump only for package root

6.5.0 (2024-04-11)

Note: Version bump only for package root

6.5.0-alpha.0 (2024-04-11)

Features

6.4.1-alpha.0 (2024-02-08)

Note: Version bump only for package root

6.4.0 (2023-12-05)

Note: Version bump only for package root

6.4.0-alpha.1 (2023-12-01)

Features

6.4.0-alpha.0 (2023-11-29)

Features

  • support register to the new backend system (ea86e73)

6.3.0 (2023-11-24)

Note: Version bump only for package root

6.3.0-alpha.1 (2023-11-24)

Bug Fixes

  • subpath does not evaluate the right url (5ea6edc)

6.3.0-alpha.0 (2023-11-17)

Features

6.2.0 (2023-08-29)

Bug Fixes

  • coverage statistics url (45b4fa1)

6.2.0-alpha.3 (2023-08-29)

Bug Fixes

6.2.0-alpha.2 (2023-08-28)

Bug Fixes

  • path can be empty string (1195451)

6.2.0-alpha.1 (2023-08-28)

Bug Fixes

6.2.0-alpha.0 (2023-08-25)

Bug Fixes

Features

  • Add Coverage card (0946e52)
  • Add graphql query to mock (e035819)
  • Add info card variant prop (aed18ec)
  • Add tests, refactored gitlab client (8577210)

6.1.0 (2023-08-22)

Note: Version bump only for package root

6.1.0-alpha.0 (2023-08-21)

Bug Fixes

  • compatible the release name contain slashes (b159d23)
  • readme path URI encoding (2d5ecf4)

Features

  • add sorting option for release card (cc1123a)

6.0.1-alpha.0 (2023-07-03)

Note: Version bump only for package root

6.0.0 (2023-06-14)

Note: Version bump only for package root

6.0.0-alpha.1 (2023-06-13)

Note: Version bump only for package root

6.0.0-alpha.0 (2023-06-12)

Features

  • migrated all type to gitbeaker (8e644e3)

BREAKING CHANGES

  • all types are changed follow gitbeaker standards, if you are using these types you are to migrate them

5.2.1-alpha.0 (2023-06-09)

Note: Version bump only for package root

5.2.0 (2023-05-29)

Note: Version bump only for package root

5.2.0-alpha.0 (2023-05-29)

Features

  • added-secure-prop-to-proxy-config: added new parameter 'secure' to be able to handle (0aa8943)
  • load README from the project repository (3eaf058)

5.1.0 (2023-05-08)

Note: Version bump only for package root

5.1.0-alpha.0 (2023-05-08)

Features

5.0.2 (2023-04-13)

Bug Fixes

  • removeHeader throws an error (9a30295)

5.0.1 (2023-04-11)

Note: Version bump only for package root

5.0.1-alpha.1 (2023-04-11)

Bug Fixes

5.0.1-alpha.0 (2023-04-07)

Bug Fixes

  • catching the error from http-proxy-middleware (7c5f429), closes #143

5.0.0 (2023-03-09)

Note: Version bump only for package root

5.0.0-alpha.0 (2023-03-08)

Features

  • api: identify gitlab instances by hostname (dff875d), closes #118
  • releasescard: add releases widget (8f25374)

BREAKING CHANGES

  • api: Annotations gitlab.com/instance require the hostname of the gitlab instance, replacing index numbers. The processor now creates annotations with hostnames. GitLabCIApiRef calls using /api/gitlab/{number}/ are not resolved and return 404 not found.

Signed-off-by: Manuel Stein manuel.stein@nokia-bell-labs.com

  • releasescard: GitlabCIApi type has the new method getReleaseSummary

Signed-off-by: Manuel Stein manuel.stein@nokia-bell-labs.com

4.0.1 (2023-03-06)

Bug Fixes

  • handle error when target is not well formatted url (ca49ad4)

4.0.0 (2023-02-23)

Bug Fixes

  • removed backstage Authorization header to the forwarded backstage request (e72aafa)

4.0.0-alpha.0 (2023-02-22)

Features

  • Add authentication header if needed (dea3a59)
  • disable project bots from being returned from the /users get request, corrected the mock data as to what it was before (8f0be47)
  • without_project_bots to the users API call, this should exclude bots from projects and groups and in the contributors card (d8de182)

BREAKING CHANGES

  • the GitlabCIClient constructor has a new parameter identityApi

3.0.2 (2023-02-15)

Bug Fixes

  • table: added empty array to table data in mr and pipeline tables (a7c9862)

3.0.1 (2023-01-25)

Note: Version bump only for package root

3.0.0 (2023-01-25)

Bug Fixes

  • reduce gitlab groups request size (287a40e)

3.0.0-alpha.2 (2023-01-24)

Bug Fixes

  • removed baseUrl from types (878ff81)
  • yarn: fix yarn version (587a086)

Features

  • peopleCard: added groups support to ownersfile (23b6b14)

BREAKING CHANGES

  • peopleCard: Renamed Type PersonData into PeopleCardEntityData

3.0.0-alpha.1 (2023-01-24)

Features

BREAKING CHANGES

  • removed baseUrl and proxyPath

3.0.0-alpha.0 (2023-01-23)

Bug Fixes

Features

  • added the new annotation instance (22f80e6)
  • backend plugin (3597c2c)
  • processor: added indexing feature (1374ea0)
  • updated API call in client (6300447)

BREAKING CHANGES

  • proxy is not more used, you have to use backend plugin with the processor.

4.0.0-alpha.0 (2023-01-20)

Bug Fixes

Features

  • added the new annotation instance (22f80e6)
  • backend plugin (3597c2c)
  • processor: added indexing feature (1374ea0)
  • updated API call in client (6300447)

BREAKING CHANGES

  • proxy is not more used, you have to use backend plugin with the processor.