Docs Backport Action

A GitHub Action to backport documentation changes between folders in Docusaurus projects. This action is specifically designed for the loft-sh/vcluster-docs repository structure.

How It Works

This action automatically backports changes from main documentation folders (vcluster, platform) to versioned documentation folders when PRs are merged or labeled with version-specific labels.

Usage

Create a workflow file in your repository:

name: Backport Documentation

on:
  pull_request:
    types: [closed, labeled]
    paths:
      - 'vcluster/**'
      - 'platform/**'

jobs:
  backport:
    runs-on: ubuntu-latest
    if: github.event.pull_request.merged == true || 
        (github.event.action == 'labeled' && startsWith(github.event.label.name, 'backport-v'))
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Backport Docusaurus Changes
        uses: loft-sh/docs-backport-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
## Inputs

- `github_token`: GitHub token to authenticate API requests (required)

## Outputs

A file whose versioned copy has diverged from what the PR changed is left unchanged and reported as a conflict. So is a file the version has no matching place for: a modified or renamed file that doesn't exist at the same path in the version, or an added file whose folder the version lacks. After a docs restructure, those pages live at different paths in older versions, and copying them by path would publish duplicate pages. Conflicts get a comment on the original PR, but the run still succeeds, so use these outputs to alert someone:

- `conflicts`: JSON array with one entry per version that has conflicts, for example `[{"folder":"vcluster","version":"0.37","files":["vcluster_versioned_docs/version-0.37.0/guide.mdx"],"comment_url":"https://github.com/..."}]`. Empty when every file applied cleanly.
- `summary`: plain-text lines naming each version that needs a person: its conflicting files and the comment URL, or why its backport failed. Empty when nothing needs attention.

Both outputs are set on failed runs too, so a notification step can report what was done before the failure:

```yaml
      - name: Backport Docusaurus Changes
        id: backport
        uses: loft-sh/docs-backport-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Notify on conflicts or failure
        if: failure() || steps.backport.outputs.conflicts != ''
        run: echo "$SUMMARY"
        env:
          SUMMARY: ${{ steps.backport.outputs.summary }}

Labels

Add labels to PRs to specify which version(s) to backport to:

• backport-v0.22 - Backport to vcluster v0.22
• backport-v4.2 - Backport to platform v4.2

Development

Prerequisites

• Node.js 20.x
• npm

Setup

# Install dependencies
npm install

# Run tests
npm test

# Build the action
npm run build

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Releasing

1. Changes pushed to the main branch are automatically tested.
2. To create a new release, use the "Release" GitHub workflow with the desired version number.
3. After a release is created, the major version tag (e.g., v1) is automatically updated.

Manually updating the v1 tag

If you need to manually update the v1 tag to point to the current commit:

# Update the local v1 tag to point to the current commit
git tag -f v1

# Force push the updated tag to the remote repository
# Use --no-verify if you have pre-push hooks that would block the push
git push -f origin v1 --no-verify

License

MIT