Backstage VeeCode Gitlab Pipelines Plugin

Install the frontend package

1. Add the plugin to the app package with yarn 3.x
   Copy

   yarn workspace app add @veecode-platform/backstage-plugin-gitlab-pipelines

2. Or add it with other yarn versions
   Copy

   yarn add --cwd packages/app @veecode-platform/backstage-plugin-gitlab-pipelines

Configure GitLab integration and auth

1. Configure a GitLab integration in your Backstage app config.
2. Configure a GitLab auth provider in your Backstage backend.
3. If your GitLab is self hosted, set apiBaseUrl in the GitLab integration entry in app config. This is required.

Add the proxy config

1. Add a proxy entry in app config
   Copy

   # app-config.yaml
   proxy:
     endpoints:
       '/gitlab/api':
         target: https://gitlab.com/api/v4
         credentials: dangerously-allow-unauthenticated
         allowedHeaders: ['Authorization', 'Content-Type']
         headers:
           Accept: application/json
           Content-Type: application/json

2. If your GitLab is self hosted, change target to your instance api v4 url. Keep the same headers list.

Prepare your .gitlab_ci.yml

1. Use variables to control default jobs and specific jobs.
2. Example config
   Copy

   stages:
     - build
     - deploy
     - start
     - stop
   
   variables:
     DEFAULT_JOB: 'false'
     START_JOB: 'false'
     STOP_JOB: 'false'
   
   build-job:
     stage: build
     script:
       - echo "Compiling the code..."
       - echo "Compile complete."
     rules:
       - if: $DEFAULT_JOB == "true"
   
   deploy-job:
     stage: deploy
     environment: production
     script:
       - echo "Deploying application..."
       - echo "Application successfully deployed."
     rules:
       - if: $DEFAULT_JOB == "true"
   
   start-job:
     stage: start
     script:
       - echo "start job..."
     rules:
       - if: $START_JOB == "true"
   
   stop-job:
     stage: stop
     script:
       - echo "stop job..."
     rules:
       - if: $STOP_JOB == "true"

3. Use DEFAULT_JOB for your standard pipeline flow. Use one variable per specific job for ad hoc runs.

Add entity annotations

1. Add the GitLab project slug to your catalog entity.
   Copy

   # catalog-info.yaml
   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: Test
     description: gitlab test
     annotations:
       gitlab.com/project-slug: repo/test
       backstage.io/techdocs-ref: dir:.
   spec:
     type: service
     lifecycle: experimental
     owner: admin

2. Optional simple jobs annotation
   Copy

   metadata:
     annotations:
       gitlab.com/project-slug: repo/test
       gitlab.com/jobs: 'Deploy:DEFAULT_JOB,Start:START_JOB,Stop:STOP_JOB'

3. Optional custom jobs annotation with labels and tooltips
   Copy

   metadata:
     annotations:
       gitlab.com/project-slug: repo/test
       gitlab.com/jobs: |
         [
           { "label": "Deploy", "var": "DEPLOY_JOB", "tooltip": "Deploy application" },
           { "label": "Start",  "var": "START_JOB", "tooltip": "Start the instance" },
           { "label": "Stop",   "var": "STOP_JOB",  "tooltip": "Stop the instance" }
         ]

Add the UI components to EntityPage

1. Open this file
   Copy

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

2. Import the plugin parts
   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import { Grid } from '@material-ui/core';
   import { EntitySwitch } from '@backstage/plugin-catalog';
   import { EntityAboutCard, EntityCatalogGraphCard, EntityLinksCard } from '@backstage/plugin-catalog';
   import {
     GitlabPipelineList,
     isGitlabAvailable,
     GitlabJobs,
     isGitlabJobsAvailable,
   } from '@veecode-platform/backstage-plugin-gitlab-pipelines';

3. Show the pipelines list in your CI content section
   Copy

   const cicdContent = (
     <EntitySwitch>
       <EntitySwitch.Case if={isGitlabAvailable}>
         <GitlabPipelineList />
       </EntitySwitch.Case>
     </EntitySwitch>
   );

4. Show the jobs card in your overview section
   Copy

   const overviewContent = (
     <Grid container spacing={3} alignItems="stretch">
       <Grid item md={6}>
         <EntityAboutCard variant="gridItem" />
       </Grid>
       <Grid item md={6} xs={12}>
         <EntityCatalogGraphCard variant="gridItem" height={400} />
       </Grid>
   
       <EntitySwitch>
         <EntitySwitch.Case if={isGitlabJobsAvailable}>
           <Grid item lg={8} xs={12}>
             <GitlabJobs />
           </Grid>
         </EntitySwitch.Case>
       </EntitySwitch>
   
       <Grid item md={4} xs={12}>
         <EntityLinksCard />
       </Grid>
     </Grid>
   );

Backend setup for the proxy

The plugin itself does not ship a backend package. It calls the GitLab API through the Backstage proxy. Make sure the proxy backend is running.

Legacy backend system

1. Add the proxy backend if missing
   Copy

   yarn workspace backend add @backstage/plugin-proxy-backend

2. Create a proxy plugin file if your app does not have one
   Copy

   // packages/backend/src/plugins/proxy.ts
   import { createRouter } from '@backstage/plugin-proxy-backend';
   import { PluginEnvironment } from '../types';
   
   export default async function createPlugin(env: PluginEnvironment) {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       discovery: env.discovery,
       tokenManager: env.tokenManager,
     });
   }

3. Wire it in the backend index
   Copy

   // packages/backend/src/index.ts
   import proxy from './plugins/proxy';
   
   async function main() {
     // existing env setup here
     const env = useHotMemoize(module, createEnv);
     const router = Router();
     router.use('/proxy', await proxy(env));
     // existing server start here
   }
   
   main().catch(err => {
     process.exit(1);
   });

New backend system

1. Add the proxy backend module
   Copy

   yarn workspace backend add @backstage/plugin-proxy-backend

2. Register it in the backend entry
   Copy

   // packages/backend/src/index.ts
   import { createBackend } from '@backstage/backend-defaults';
   
   const backend = createBackend();
   
   backend.add(import('@backstage/plugin-proxy-backend'));
   
   backend.start();

How it works at runtime

1. The UI reads gitlab.com/project-slug from the entity.
2. The UI talks to the Backstage proxy at the path set in app config.
3. The proxy forwards requests to the GitLab API v4 target.
4. The GitLab auth provider supplies the Authorization header through Backstage.