We Cut Our Engineering Onboarding Time by 50% in 2026 Using Backstage 2.0 and Internal Docs

// backstage-docs-hub.config.ts
// Configuration for Backstage 2.0 Docs Hub plugin, validated at startup
// Implements our internal docs governance rules: all docs must be in-repo, versioned, and linked to Software Catalog components

import { createDocsHubConfig } from '@backstage/plugin-docs-hub-backend';
import { ConfigReader } from '@backstage/config';
import { Logger } from 'winston';

// Define required environment variables for docs hub setup
const requiredEnvVars = ['GITHUB_DOCS_ORG', 'DOCS_BUCKET_NAME', 'CATALOG_API_BASE'] as const;

// Validate all required environment variables are present before initializing config
function validateEnv(logger: Logger): void {
  const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);
  if (missingVars.length > 0) {
    const errorMsg = `Missing required environment variables for Docs Hub: ${missingVars.join(', ')}`;
    logger.error(errorMsg);
    throw new Error(errorMsg);
  }
}

// Define custom doc validation rules matching our internal governance policy
interface DocValidationRule {
  id: string;
  check: (docPath: string, content: string) => boolean;
  errorMessage: string;
}

const internalDocRules: DocValidationRule[] = [
  {
    id: 'no-external-links',
    // Disallow links to external doc sites (e.g., old Confluence) in internal docs
    check: (_, content) => !/(https?:\/\/confluence\.ourcorp\.com|https?:\/\/gitbook\.ourcorp\.com)/.test(content),
    errorMessage: 'Internal docs cannot link to legacy Confluence or GitBook instances'
  },
  {
    id: 'required-frontmatter',
    // All docs must have title, owner, and last-reviewed date in frontmatter
    check: (_, content) => {
      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
      if (!frontmatterMatch) return false;
      const frontmatter = frontmatterMatch[1];
      return /title:/.test(frontmatter) && /owner:/.test(frontmatter) && /last-reviewed:/.test(frontmatter);
    },
    errorMessage: 'All docs must include title, owner, and last-reviewed date in YAML frontmatter'
  },
  {
    id: 'catalog-link',
    // Docs must link to at least one Software Catalog component
    check: (_, content) => /backstage:\/\/catalog\//.test(content),
    errorMessage: 'Docs must link to at least one Backstage Software Catalog component'
  }
];

export async function createDocsHubConfig(logger: Logger) {
  validateEnv(logger);

  try {
    // Initialize base config from Backstage's default Docs Hub factory
    const baseConfig = createDocsHubConfig({
      // Mount docs hub at /docs instead of default /docs-hub
      mountPath: '/docs',
      // Use GitHub as primary doc source, synced every 5 minutes
      sources: [
        {
          type: 'github',
          org: process.env.GITHUB_DOCS_ORG!,
          repo: 'internal-docs',
          path: 'docs',
          branch: 'main',
          syncInterval: 300000 // 5 minutes in ms
        }
      ],
      // Enable versioning based on git tags
      versioning: {
        strategy: 'git-tags',
        fallback: 'main'
      }
    });

    // Add custom validation middleware using our internal rules
    baseConfig.addMiddleware({
      id: 'internal-doc-validation',
      validate: async (docPath, content) => {
        for (const rule of internalDocRules) {
          if (!rule.check(docPath, content)) {
            logger.warn(`Doc validation failed for ${docPath}: ${rule.errorMessage}`);
            return { valid: false, error: rule.errorMessage };
          }
        }
        return { valid: true };
      }
    });

    // Configure search indexing with custom boost for onboarding docs
    baseConfig.configureSearch({
      boostRules: [
        {
          pattern: /\/onboarding\//,
          boost: 2.5 // Boost onboarding docs in search results by 2.5x
        },
        {
          pattern: /\/api-reference\//,
          boost: 1.8 // Boost API docs by 1.8x
        }
      ]
    });

    logger.info('Docs Hub config initialized successfully with internal governance rules');
    return baseConfig;
  } catch (error) {
    logger.error(`Failed to initialize Docs Hub config: ${error.message}`);
    throw error;
  }
}

// sync-docs-to-catalog.ts
// Cron job script to sync internal doc metadata to Backstage Software Catalog
// Runs every 15 minutes, updates doc links, staleness status, and owner info for all components

import { CatalogClient } from '@backstage/catalog-client';
import { GitHub } from '@octokit/rest';
import { Logger } from 'winston';
import { createLogger, transports, format } from 'winston';

// Initialize logger with JSON format for production tracing
const logger = createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: format.combine(
    format.timestamp(),
    format.json()
  ),
  transports: [new transports.Console()]
});

// Initialize Backstage Catalog client pointing to our self-hosted Backstage instance
const catalogClient = new CatalogClient({
  baseUrl: process.env.BACKSTAGE_BASE_URL || 'https://backstage.ourcorp.com'
});

// Initialize GitHub client with read-only token for internal docs org
const github = new GitHub({
  auth: process.env.GITHUB_DOCS_TOKEN,
  baseUrl: 'https://api.github.com'
});

// Define interfaces for type safety
interface DocMetadata {
  path: string;
  title: string;
  owner: string;
  lastModified: string;
  stale: boolean;
  catalogComponentSlug: string;
}

interface CatalogComponent {
  apiVersion: string;
  kind: string;
  metadata: {
    name: string;
    annotations?: Record;
  };
  spec: {
    type: string;
    owner: string;
    docs?: {
      url: string;
      stale: boolean;
      lastModified: string;
    };
  };
}

// Fetch all doc files from internal-docs repo, parse metadata
async function fetchDocMetadata(): Promise {
  try {
    const { data: files } = await github.repos.getContent({
      owner: process.env.GITHUB_DOCS_ORG!,
      repo: 'internal-docs',
      path: 'docs',
      recursive: true
    });

    if (!Array.isArray(files)) {
      throw new Error('Expected array of files from GitHub API');
    }

    // Filter only markdown files, exclude draft docs (prefixed with _)
    const mdFiles = files.filter(file => file.name.endsWith('.md') && !file.name.startsWith('_'));

    const docMetadata: DocMetadata[] = [];

    for (const file of mdFiles) {
      try {
        // Fetch raw file content to parse frontmatter
        const { data: rawContent } = await github.repos.getContent({
          owner: process.env.GITHUB_DOCS_ORG!,
          repo: 'internal-docs',
          path: file.path,
          mediaType: { format: 'raw' }
        });

        const content = rawContent as string;
        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
        if (!frontmatterMatch) continue;

        const frontmatter = frontmatterMatch[1];
        const titleMatch = frontmatter.match(/title:\s*["']?([^"'
]+)["']?/);
        const ownerMatch = frontmatter.match(/owner:\s*["']?([^"'
]+)["']?/);
        const componentSlugMatch = frontmatter.match(/catalog-component:\s*["']?([^"'
]+)["']?/);

        if (!titleMatch || !ownerMatch || !componentSlugMatch) {
          logger.warn(`Skipping ${file.path}: missing required frontmatter fields`);
          continue;
        }

        // Check if doc is stale: last-reviewed date is older than 90 days
        const lastReviewedMatch = frontmatter.match(/last-reviewed:\s*["']?([^"'
]+)["']?/);
        let stale = false;
        if (lastReviewedMatch) {
          const lastReviewed = new Date(lastReviewedMatch[1]);
          const ninetyDaysAgo = new Date();
          ninetyDaysAgo.setDate(ninetyDaysAgo.getDate() - 90);
          stale = lastReviewed < ninetyDaysAgo;
        }

        docMetadata.push({
          path: file.path,
          title: titleMatch[1],
          owner: ownerMatch[1],
          lastModified: file.sha, // Use git SHA as last modified identifier
          stale,
          catalogComponentSlug: componentSlugMatch[1]
        });
      } catch (fileError) {
        logger.error(`Failed to process file ${file.path}: ${fileError.message}`);
      }
    }

    logger.info(`Fetched metadata for ${docMetadata.length} docs`);
    return docMetadata;
  } catch (error) {
    logger.error(`Failed to fetch doc metadata from GitHub: ${error.message}`);
    throw error;
  }
}

// Update Backstage Catalog components with doc metadata
async function updateCatalogComponents(docs: DocMetadata[]): Promise {
  for (const doc of docs) {
    try {
      // Fetch existing component from catalog
      const { data: component } = await catalogClient.getEntityByRef({
        kind: 'Component',
        namespace: 'default',
        name: doc.catalogComponentSlug
      });

      if (!component) {
        logger.warn(`Component ${doc.catalogComponentSlug} not found in catalog, skipping`);
        continue;
      }

      // Update component spec with doc info
      const updatedComponent: CatalogComponent = {
        ...component,
        spec: {
          ...component.spec,
          docs: {
            url: `https://backstage.ourcorp.com/docs/${doc.path.replace('.md', '')}`,
            stale: doc.stale,
            lastModified: doc.lastModified
          }
        },
        metadata: {
          ...component.metadata,
          annotations: {
            ...component.metadata.annotations,
            'docs.ourcorp.com/owner': doc.owner,
            'docs.ourcorp.com/last-modified': doc.lastModified
          }
        }
      };

      // Validate updated component before pushing
      if (!updatedComponent.spec.docs) {
        throw new Error('Updated component missing docs spec');
      }

      await catalogClient.updateEntity(updatedComponent);
      logger.info(`Updated component ${doc.catalogComponentSlug} with doc link ${doc.path}`);
    } catch (error) {
      logger.error(`Failed to update component ${doc.catalogComponentSlug}: ${error.message}`);
    }
  }
}

// Main execution
async function main() {
  try {
    logger.info('Starting doc to catalog sync job');
    const docs = await fetchDocMetadata();
    await updateCatalogComponents(docs);
    logger.info('Doc to catalog sync job completed successfully');
  } catch (error) {
    logger.error(`Sync job failed: ${error.message}`);
    process.exit(1);
  }
}

// Run if this is the main module
if (require.main === module) {
  main();
}

// OnboardingDashboard.tsx
// Custom Backstage 2.0 plugin component for new hire onboarding dashboard
// Displays personalized onboarding tasks, doc links, and progress tracking

import React, { useState, useEffect } from 'react';
import { useApi, configApiRef, catalogApiRef } from '@backstage/core-plugin-api';
import { Progress, Table, Button, Typography, Alert } from '@backstage/core-components';
import { Entity } from '@backstage/catalog-model';
import { useAsync } from 'react-use';

const { Title, Text } = Typography;

// Define onboarding task interface
interface OnboardingTask {
  id: string;
  name: string;
  description: string;
  docLink: string;
  required: boolean;
  completed: boolean;
  dueDate: string;
}

// Define new hire interface
interface NewHire {
  id: string;
  name: string;
  email: string;
  startDate: string;
  team: string;
  tasks: OnboardingTask[];
  progress: number; // 0-100
}

// Fetch new hire data from internal HR API
async function fetchNewHireData(email: string, catalogApi: any, config: any): Promise {
  try {
    const hrApiBase = config.getString('hrApi.baseUrl');
    const response = await fetch(`${hrApiBase}/new-hires?email=${encodeURIComponent(email)}`, {
      headers: {
        'Authorization': `Bearer ${process.env.HR_API_TOKEN}`
      }
    });

    if (!response.ok) {
      throw new Error(`HR API returned ${response.status}: ${response.statusText}`);
    }

    const hireData = await response.json();

    // Fetch team's catalog component to get team-specific onboarding docs
    const teamComponent = await catalogApi.getEntityByRef({
      kind: 'Group',
      namespace: 'default',
      name: hireData.team
    });

    // Map HR tasks to onboarding tasks with doc links
    const tasks: OnboardingTask[] = hireData.tasks.map((task: any) => {
      // Find matching doc link from team's catalog component
      const docLink = teamComponent?.spec?.docs?.url 
        ? `${teamComponent.spec.docs.url}/${task.docSlug}`
        : `https://backstage.ourcorp.com/docs/onboarding/${task.docSlug}`;

      return {
        id: task.id,
        name: task.name,
        description: task.description,
        docLink,
        required: task.required,
        completed: task.completed,
        dueDate: task.dueDate
      };
    });

    return {
      id: hireData.id,
      name: hireData.name,
      email: hireData.email,
      startDate: hireData.startDate,
      team: hireData.team,
      tasks,
      progress: hireData.progress
    };
  } catch (error) {
    throw new Error(`Failed to fetch new hire data: ${error.message}`);
  }
}

// Mark task as completed via HR API
async function completeTask(taskId: string, newHireId: string, config: any): Promise {
  try {
    const hrApiBase = config.getString('hrApi.baseUrl');
    const response = await fetch(`${hrApiBase}/new-hires/${newHireId}/tasks/${taskId}/complete`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HR_API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`Failed to complete task: ${response.statusText}`);
    }
  } catch (error) {
    throw new Error(`Error completing task: ${error.message}`);
  }
}

export const OnboardingDashboard = () => {
  const config = useApi(configApiRef);
  const catalogApi = useApi(catalogApiRef);
  const [newHireEmail, setNewHireEmail] = useState('');
  const [selectedHire, setSelectedHire] = useState(null);

  // For demo purposes, pre-fill with test new hire email
  useEffect(() => {
    setNewHireEmail('test.newhire@ourcorp.com');
  }, []);

  const { value: newHire, loading, error } = useAsync(async () => {
    if (!newHireEmail) return null;
    return fetchNewHireData(newHireEmail, catalogApi, config);
  }, [newHireEmail, catalogApi, config]);

  const handleCompleteTask = async (taskId: string) => {
    if (!newHire) return;
    try {
      await completeTask(taskId, newHire.id, config);
      // Refetch data to update progress
      setNewHireEmail(''); // Trigger re-fetch
      setTimeout(() => setNewHireEmail(newHire.email), 0);
    } catch (err) {
      alert(`Failed to complete task: ${err.message}`);
    }
  };

  if (loading) return ;
  if (error) return {error.message};
  if (!newHire) return No new hire data found. Enter email to search.;

  const requiredTasks = newHire.tasks.filter(task => task.required);
  const optionalTasks = newHire.tasks.filter(task => !task.required);

  return (
    <div style={{ padding: '2rem' }}>
      <Title level={2}>Onboarding Dashboard: {newHire.name}</Title>
      <Text>Team: {newHire.team} | Start Date: {newHire.startDate} | Progress: {newHire.progress}%</Text>

      <div style={{ margin: '2rem 0', height: '10px', backgroundColor: '#e0e0e0', borderRadius: '5px' }}>
        <div 
          style={{ 
            width: `${newHire.progress}%`, 
            height: '100%', 
            backgroundColor: '#1976d2', 
            borderRadius: '5px' 
          }} 
        />
      </div>

      <Title level={3}>Required Tasks ({requiredTasks.filter(t => t.completed).length}/{requiredTasks.length})</Title>
      <Table
        options={{ search: false, paging: false }}
        columns={[
          { title: 'Task', field: 'name' },
          { title: 'Description', field: 'description' },
          { title: 'Due Date', field: 'dueDate' },
          { 
            title: 'Status', 
            field: 'completed',
            render: (row: OnboardingTask) => row.completed ? '✅ Completed' : '⏳ Pending'
          },
          {
            title: 'Actions',
            render: (row: OnboardingTask) => (
              <div>
                <Button 
                  href={row.docLink} 
                  target="_blank" 
                  variant="text" 
                  color="primary"
                  style={{ marginRight: '1rem' }}
                >
                  View Doc
                </Button>
                {!row.completed && (
                  <Button 
                    variant="contained" 
                    color="primary" 
                    onClick={() => handleCompleteTask(row.id)}
                  >
                    Mark Complete
                  </Button>
                )}
              </div>
            )
          }
        ]}
        data={requiredTasks}
      />

      <Title level={3}>Optional Tasks ({optionalTasks.filter(t => t.completed).length}/{optionalTasks.length})</Title>
      <Table
        options={{ search: false, paging: false }}
        columns={[
          { title: 'Task', field: 'name' },
          { title: 'Description', field: 'description' },
          { title: 'Due Date', field: 'dueDate' },
          { 
            title: 'Status', 
            field: 'completed',
            render: (row: OnboardingTask) => row.completed ? '✅ Completed' : '⏳ Pending'
          },
          {
            title: 'Actions',
            render: (row: OnboardingTask) => (
              <div>
                <Button 
                  href={row.docLink} 
                  target="_blank" 
                  variant="text" 
                  color="primary"
                  style={{ marginRight: '1rem' }}
                >
                  View Doc
                </Button>
                {!row.completed && (
                  <Button 
                    variant="contained" 
                    color="primary" 
                    onClick={() => handleCompleteTask(row.id)}
                  >
                    Mark Complete
                  </Button>
                )}
              </div>
            )
          }
        ]}
        data={optionalTasks}
      />
    </div>
  );
};

// github-actions-validate-docs.yml
name: Validate Doc Frontmatter
on:
  pull_request:
    paths:
      - 'docs/**'
      - 'packages/**/docs/**'
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate frontmatter
        run: |
          for file in $(find docs -name '*.md'); do
            if ! grep -q 'title:' $file; then
              echo "::error::$file missing title frontmatter"
              exit 1
            fi
            if ! grep -q 'owner:' $file; then
              echo "::error::$file missing owner frontmatter"
              exit 1
            fi
            if ! grep -q 'last-reviewed:' $file; then
              echo "::error::$file missing last-reviewed frontmatter"
              exit 1
            fi
          done

// Search boost config snippet from backstage-docs-hub.config.ts
baseConfig.configureSearch({
  boostRules: [
    {
      pattern: /\/onboarding\//,
      boost: 2.5 // Boost onboarding docs in search results by 2.5x
    },
    {
      pattern: /\/api-reference\//,
      boost: 1.8 // Boost API docs by 1.8x
    },
    {
      pattern: /\/local-dev\//,
      boost: 4.0 // Boost local dev setup docs by 4x
    }
  ]
});

// Stale doc alert snippet from sync-docs-to-catalog.ts
if (stale) {
  await catalogClient.sendNotification({
    recipients: [{ type: 'user', ref: `user:${doc.owner}` }],
    title: `Stale doc: ${doc.title}`,
    message: `Your doc ${doc.path} is stale (last reviewed > 90 days ago). Click here to update: https://backstage.ourcorp.com/docs/${doc.path}`,
    severity: 'warning'
  });
}