example-config-gitlab

GitLab Example Configuration

This example demonstrates building GitLab plugins from a non-standard repository structure using overlays to modify source files.

Table of Contents

• GitLab Example Configuration
  • Table of Contents
  • Overview
  • Example Config Directory Structure
    • Configuration Files
  • Understanding Overlays
    • How Overlays Work
  • Quick Start
    • Container Execution (Recommended)
    • Local Development
  • Expected Output
  • Publishing the package
  • Next Steps

Overview

This example builds the frontend and backend GitLab plugins from the immobiliare/backstage-plugin-gitlab repository. It uses overlays to replace specific source files with custom versions needed for proper dynamic plugin export.

Example Config Directory Structure

example-config-gitlab/
├── packages/
│   └── gitlab-backend/
│       └── overlay/
│           └── src/
│               ├── bundle.ts         # Custom bundle configuration
│               └── index.ts          # Custom plugin export
├── plugins-list.yaml                 # List of plugins to build
└── source.json                       # Source repository configuration

Configuration Files

• source.json: Specifies the GitLab plugin repository and git reference to clone from. The repo-ref field is optional; when omitted, the repository's default branch is used. The workspace-path field can also be set here instead of using --workspace-path.
• plugins-list.yaml: List of path to the GitLab frontend and backend packages to build
• packages/gitlab-backend/overlay/: Contains replacement source files

Understanding Overlays

Overlays allow you to replace/add entire files in the plugin source code before building.

The overlay directory structure mirrors the plugin's source structure. Files in the overlay are copied over the original files at build time.

How Overlays Work

1. The factory clones the source repository
2. Before building, it copies files from config/<plugin-path>/overlay/ to the corresponding paths in <workspace-path>/<plugin-path>/
3. The overlaid files replace the original files completely if one exists, otherwise it will add the file
4. The modified source is then built and exported

Warning: Overlays are destructive - they permanently modify files in the workspace directory. Please make sure to have source control if using a local repository.

Quick Start

Container Execution (Recommended)

From the repository root, run:

podman run --rm -it \
  --device /dev/fuse \
  -v ./examples/example-config-gitlab:/config:z \
  -v ./outputs:/outputs:z \
  -v ./source:/source:z \
  quay.io/rhdh-community/dynamic-plugins-factory:latest \

Note: workspace-path is set to . in the source.json because this repository does not follow the backstage community plugins (BCP) repository structure where there are multiple yarn workspaces. Instead the plugins are stored in the main workspace, so root of the workspace is also the root of the repository in this example.

Local Development

From the repository root, run:

python -m src.rhdh_dynamic_plugin_factory \
  --config-dir ./examples/example-config-gitlab \
  --workspace-path . \
  --repo-path ./source \
  --output-dir ./outputs

Or using CLI args instead of source.json:

python -m src.rhdh_dynamic_plugin_factory \
  --source-repo https://github.com/immobiliare/backstage-plugin-gitlab \
  --source-ref v6.13.0 \
  --config-dir ./examples/example-config-gitlab \
  --workspace-path . \
  --repo-path ./source \
  --output-dir ./outputs

This will do the following:

1. The factory clones the GitLab plugin repository to ./source
2. Custom bundle.ts and index.ts files are copied to ./source/packages/gitlab-backend/src/
3. Dependencies are installed at the repository source
4. Both frontend and backend plugins are compiled
5. Plugins are exported as dynamic plugins using the RHDH CLI
6. Plugin tarballs and integrity files are created in ./outputs

Expected Output

After successful execution, you'll find these files in ./outputs:

outputs/
├── backstage-plugin-gitlab-6.13.0.tgz
├── backstage-plugin-gitlab-6.13.0.tgz.integrity
├── backstage-plugin-gitlab-backend-6.13.0.tgz
└── backstage-plugin-gitlab-backend-6.13.0.tgz.integrity

Note: Version numbers correspond to the tag specified in source.json.

Publishing the package

If you want to publish the package, you will need to add a --push-image argument and provide the following environmental variables in the /config/.env file:

REGISTRY_URL="quay.io"
REGISTRY_USERNAME="your-username"
REGISTRY_PASSWORD="your-password" 
REGISTRY_NAMESPACE="your-namespace"
REGISTRY_INSECURE="false"

Next Steps

• Try the AWS ECS example to learn about patches
• Review the TODO example for a simpler use case
• Read the main README for more configuration options