Shared GitHub Actions

A repository providing reusable GitHub Actions workflows and composite actions for kubev2v projects.

Overview

This repository contains:

• Reusable Workflows: Workflows that can be called from other repositories
• Composite Actions: Reusable action definitions that can be referenced by other projects

Available Workflows and Actions

1. OpenAPI Client Generator Workflow

Path: .github/workflows/generate-and-publish.yml

A reusable workflow that generates TypeScript clients from OpenAPI specifications and publishes them to npm.

Features

• Reusable Workflow: Call from any repository using workflow_call
• Hardcoded Generator Settings: Consistent client generation with standardized configuration
• OIDC Trusted Publishing: Secure, tokenless npm publishing with provenance attestation
• Dry-Run Mode: Test client generation without publishing

Usage

Add the following workflow to your repository (e.g., .github/workflows/update-api-client.yml):

name: Update API Client Package

on:
  push:
    branches: [main]
    paths: ['api/openapi.yaml']
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to publish'
        required: true

# Required for npm Trusted Publishing (OIDC)
permissions:
  id-token: write
  contents: read

jobs:
  generate-client:
    uses: kubev2v/migration-planner-workflows/.github/workflows/generate-and-publish.yml@main
    with:
      openapi-spec-url: "https://raw.githubusercontent.com/your-org/your-repo/main/api/openapi.yaml"
      package-name: "@your-scope/api-client"
      package-version: ${{ inputs.version || '0.0.1' }}
    # Required: passes OIDC permissions to the reusable workflow
    secrets: inherit

Inputs

Input	Required	Default	Description
openapi-spec-url	Yes	-	URL to the OpenAPI specification file
package-name	Yes	-	npm package name (e.g., @scope/package-name)
package-version	Yes	-	Package version to publish (semver)
npm-registry	No	https://registry.npmjs.org	npm registry URL
dry-run	No	false	Skip npm publish (for testing)

npm Publishing Authentication

This workflow uses npm Trusted Publishing (OIDC) exclusively — no long-lived tokens:

• No npm tokens needed — OIDC provides short-lived, workflow-specific credentials
• Requires id-token: write permission in calling workflow
• Requires Trusted Publisher configured on npmjs.com
• Use secrets: inherit to pass OIDC permissions to the reusable workflow
• Provenance attestation is automatically generated by npm Trusted Publishing

Generator Configuration

The workflow uses hardcoded generator settings that cannot be modified by callers:

Setting	Value
Generator	typescript-fetch
Output Directory	generated-client
ensureUniqueParams	true
supportsES6	true
withInterfaces	true
importFileExtension	.js

These settings match the configuration in kubev2v/migration-planner-ui.

---

2. Determine Version Action

Path: .github/actions/determine-version/action.yml

Composite action that computes a semantic version for the current ref. This is useful for versioning packages and artifacts based on git tags and commits.

Usage

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for tag history

      - name: Determine version
        id: version
        uses: kubev2v/migration-planner-workflows/.github/actions/determine-version@main

      - name: Use the version
        run: |
          echo "Version: ${{ steps.version.outputs.version }}"

Outputs

Output	Description
version	Semver version string (e.g. 1.0.0 or 1.0.0-abc123def456)

Versioning Logic

• On tag push: Uses tag name without leading 'v' (e.g. v1.0.0 → 1.0.0)
• On main branch: Latest tag + short SHA (e.g. 1.0.0-abc123def456)
• On release- branches*: Latest reachable tag + short SHA
• No tags found: Defaults to 0.0.0-abc123def456

---

Local Development

Testing the OpenAPI Client Generator with act-cli

Use act to test the OpenAPI workflow locally:

# Install act (macOS)
brew install act

# Run test workflow (dry-run mode - no npm publishing)
make test

# Cleanup generated files
make clean

Note: OIDC Trusted Publishing does not work locally with act-cli. Local testing is limited to dry-run mode. To test actual npm publishing, use the CI feature toggle described below.

Make Targets

Command	Description
make test	Run workflow in dry-run mode via act (tests generation/build only)
make test-verbose	Run workflow with verbose output
make clean	Remove generated artifacts

CI Feature Toggle

The test workflow runs in dry-run mode by default to avoid npm rate limits.

To enable actual npm publishing in CI:

1. Go to Settings > Secrets and variables > Actions > Variables
2. Add: TEST_NPM_PUBLISH = true
3. Bump TEST_PACKAGE_VERSION in test.yml before each test

When enabled, test packages are automatically unpublished after successful publish.

Repository Structure

.
├── .github/
│   ├── actions/
│   │   └── determine-version/         # Composite action for version computation
│   │       └── action.yml
│   └── workflows/
│       ├── generate-and-publish.yml   # Reusable workflow for OpenAPI clients
│       └── test.yml                   # CI test workflow
├── .actrc                             # act-cli configuration
├── .gitignore
├── Makefile                           # Local testing commands
├── AGENTS.md                          # AI agent guidelines
├── LICENSE                            # Apache-2.0
└── README.md                          # This file

Related

• ECOPROJECT-3956 - Jira issue for this project
• kubev2v/migration-planner-ui - UI monorepo using this workflow
• kubev2v/migration-planner - Backend API repository
• openapi-generator - OpenAPI Generator documentation

License

Apache-2.0