From 6d338681394f514f1672a389c35c43f004dc6abd Mon Sep 17 00:00:00 2001 From: antedotee Date: Thu, 29 Jan 2026 10:41:27 +0530 Subject: [PATCH 1/2] docs: add preview feature functionality with GitHub workflows - Add docs preview check workflow - Add docs preview deploy workflow - Add docs preview cleanup workflow Signed-off-by: antedotee --- .github/workflows/dco.yaml | 23 +++++ .github/workflows/docs-preview-check.yaml | 107 ++++++++++++++++++++ .github/workflows/docs-preview-cleanup.yaml | 39 +++++++ .github/workflows/docs-preview-deploy.yaml | 82 +++++++++++++++ 4 files changed, 251 insertions(+) create mode 100644 .github/workflows/dco.yaml create mode 100644 .github/workflows/docs-preview-check.yaml create mode 100644 .github/workflows/docs-preview-cleanup.yaml create mode 100644 .github/workflows/docs-preview-deploy.yaml diff --git a/.github/workflows/dco.yaml b/.github/workflows/dco.yaml new file mode 100644 index 0000000000..d3c0b7daa8 --- /dev/null +++ b/.github/workflows/dco.yaml @@ -0,0 +1,23 @@ +name: DCO Check + +on: + pull_request: + branches: + - master + - "release-v*" + - "feat/*" + +permissions: + contents: read + +jobs: + dco: + runs-on: ubuntu-24.04 + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + + - name: Check DCO sign-off + run: ./hack/ensure-dco.sh diff --git a/.github/workflows/docs-preview-check.yaml b/.github/workflows/docs-preview-check.yaml new file mode 100644 index 0000000000..5087539fe0 --- /dev/null +++ b/.github/workflows/docs-preview-check.yaml @@ -0,0 +1,107 @@ +# This workflow checks that PRs modifying docs include a preview link in the PR description. +# It enforces documentation PR best practices for PipeCD. + +name: Docs Preview Check + +on: + pull_request: + types: [opened, edited, synchronize] + paths: + - 'docs/**' + - '*.md' + +permissions: + contents: read + pull-requests: read + +jobs: + check-preview-link: + runs-on: ubuntu-24.04 + steps: + - name: Checkout code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Check for Preview Link in PR Description + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + BRANCH: ${{ github.head_ref }} + run: | + set -e + + # Get PR body + BODY=$(gh pr view "$PR_NUMBER" --json body -q '.body') + + # Get owner and repo name for the head repository (fork or main) + OWNER=$(gh pr view "$PR_NUMBER" --json headRepositoryOwner -q '.headRepositoryOwner.login') + REPO_NAME=$(gh pr view "$PR_NUMBER" --json headRepository -q '.headRepository.name') + + # Expected GitHub Pages URL format + GITHUB_PAGES_URL="https://${OWNER}.github.io/${REPO_NAME}/${BRANCH}" + + # Check if branch starts with 'docs-' + DOC_BRANCH_REGEX='^docs-' + + # Color codes for output + GREEN=$'\033[0;32m' + RED=$'\033[0;31m' + YELLOW=$'\033[1;33m' + NC=$'\033[0m' # No Color + + echo "Checking PR #$PR_NUMBER for docs preview link..." + echo "Branch: $BRANCH" + echo "Expected preview base URL: $GITHUB_PAGES_URL" + echo "" + + # Check if the PR description contains a preview link + if ! PREVIEW_LINE=$(echo "$BODY" | grep -iE '^[[:space:]]*[Pp]review.*https?://' || true); then + # Branch doesn't start with 'docs-' - provide guidance + if [[ ! "$BRANCH" =~ $DOC_BRANCH_REGEX ]]; then + echo "${YELLOW}[INFO] This branch does not start with 'docs-'. For automatic preview deployment:${NC}" + echo "" + echo "1. Create a branch with 'docs-' prefix (e.g., docs-update-readme)" + echo "2. Push your changes to trigger the preview deployment" + echo "3. Add the preview link to your PR description" + echo "" + echo "Example PR description format:" + echo " Preview: https://YOUR_USERNAME.github.io/pipecd/docs-your-branch/" + echo "" + echo "${YELLOW}Skipping check since branch doesn't follow docs- convention.${NC}" + exit 0 + fi + + echo "${RED}[ERROR] Docs PR: No preview link found in PR description.${NC}" + echo "" + echo "Please include a line starting with 'Preview' and a valid GitHub Pages URL." + echo "" + echo "Steps to add a preview:" + echo "1. Ensure your branch name starts with 'docs-'" + echo "2. Push your changes to trigger the preview deployment workflow" + echo "3. Add the following to your PR description:" + echo "" + echo " Preview: $GITHUB_PAGES_URL/" + echo "" + exit 1 + else + # Found a preview line, check if it matches expected format + if [[ "$PREVIEW_LINE" == *"$GITHUB_PAGES_URL"* ]]; then + if [[ "$BRANCH" =~ $DOC_BRANCH_REGEX ]]; then + echo "${GREEN}[OK] Docs PR: Branch starts with 'docs-' and preview link matches expected format.${NC}" + echo "Preview URL found: $GITHUB_PAGES_URL/" + else + echo "${YELLOW}[WARN] Docs PR: Preview link found but branch does not start with 'docs-'.${NC}" + echo "Consider renaming your branch to enable automatic preview deployment." + fi + else + PREVIEW_URL=$(echo "$PREVIEW_LINE" | grep -oE 'https?://[^ )"'"'"']*' || true) + echo "${YELLOW}[WARN] Docs PR: Preview link found but doesn't match expected GitHub Pages URL.${NC}" + echo "" + echo "Expected: $GITHUB_PAGES_URL/" + echo "Found: $PREVIEW_URL" + echo "" + echo "This might be fine if you're using a different preview method." + fi + fi + + echo "" + echo "Check completed successfully." diff --git a/.github/workflows/docs-preview-cleanup.yaml b/.github/workflows/docs-preview-cleanup.yaml new file mode 100644 index 0000000000..4e8bbe3e4d --- /dev/null +++ b/.github/workflows/docs-preview-cleanup.yaml @@ -0,0 +1,39 @@ +# This workflow cleans up docs preview deployments when branches are deleted. +# It removes the preview directory from gh-pages when a 'docs-*' branch is deleted. + +name: Docs Preview Cleanup + +on: + delete: + +permissions: + contents: write + +jobs: + cleanup-preview: + runs-on: ubuntu-24.04 + # Only run for branch deletions + if: github.event.ref_type == 'branch' && startsWith(github.event.ref, 'docs-') + steps: + - name: Checkout gh-pages branch + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: gh-pages + fetch-depth: 0 + + - name: Remove preview directory + run: | + BRANCH_NAME="${{ github.event.ref }}" + echo "Cleaning up preview for deleted branch: $BRANCH_NAME" + + if [ -d "$BRANCH_NAME" ]; then + rm -rf "$BRANCH_NAME" + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add -A + git commit -m "chore: remove docs preview for deleted branch '$BRANCH_NAME'" || echo "No changes to commit" + git push + echo "✅ Successfully removed preview directory: $BRANCH_NAME" + else + echo "ℹī¸ Preview directory '$BRANCH_NAME' does not exist. Nothing to clean up." + fi diff --git a/.github/workflows/docs-preview-deploy.yaml b/.github/workflows/docs-preview-deploy.yaml new file mode 100644 index 0000000000..1ea2d81242 --- /dev/null +++ b/.github/workflows/docs-preview-deploy.yaml @@ -0,0 +1,82 @@ +# This workflow builds and deploys docs preview to GitHub Pages for branches prefixed with 'docs-'. +# Each branch gets its own subdirectory at https://.github.io/pipecd// + +name: Docs Preview Deploy + +on: + push: + branches: + - 'docs-*' + paths: + - 'docs/**' + - '*.md' + - '.github/workflows/docs-preview-deploy.yaml' + +permissions: + contents: write + pages: write + id-token: write + +# Prevent multiple deployments to the same branch from running simultaneously +concurrency: + group: docs-preview-${{ github.ref_name }} + cancel-in-progress: true + +jobs: + build-and-deploy: + runs-on: ubuntu-24.04 + steps: + - name: Checkout code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + + - name: Setup Hugo + uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0 + with: + hugo-version: '0.148.2' + extended: true + + - name: Setup Node + uses: actions/setup-node@v3 + with: + node-version: '14' + + - name: Get branch name + id: branch + run: echo "name=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT + + - name: Get repository owner + id: repo + run: | + echo "owner=${GITHUB_REPOSITORY_OWNER}" >> $GITHUB_OUTPUT + echo "name=$(echo '${{ github.repository }}' | cut -d'/' -f2)" >> $GITHUB_OUTPUT + + - name: Build docs for preview + run: | + cd docs + npm install autoprefixer + npm install postcss-cli + # Build with custom baseURL for the preview deployment + env HUGO_ENV="production" \ + RELEASE="$(grep '^tag:' ../RELEASE | awk '{print $2}')" \ + hugo --baseURL "https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/" + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/public + destination_dir: ${{ steps.branch.outputs.name }} + keep_files: true # Keep other preview directories + + - name: Output preview URL + run: | + echo "## 📚 Docs Preview Deployed!" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Preview URL: https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Add this to your PR description:" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + echo "Preview: https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY From 38c311e3fbea02f8d15c93b892ea0079091063e8 Mon Sep 17 00:00:00 2001 From: antedotee Date: Thu, 29 Jan 2026 10:58:38 +0530 Subject: [PATCH 2/2] mistakenly added wrong file Signed-off-by: antedotee --- .github/workflows/dco.yaml | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 .github/workflows/dco.yaml diff --git a/.github/workflows/dco.yaml b/.github/workflows/dco.yaml deleted file mode 100644 index d3c0b7daa8..0000000000 --- a/.github/workflows/dco.yaml +++ /dev/null @@ -1,23 +0,0 @@ -name: DCO Check - -on: - pull_request: - branches: - - master - - "release-v*" - - "feat/*" - -permissions: - contents: read - -jobs: - dco: - runs-on: ubuntu-24.04 - steps: - - name: Checkout repository - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - with: - fetch-depth: 0 - - - name: Check DCO sign-off - run: ./hack/ensure-dco.sh