[reports] Add pull request Pages previews and consumer documentation (#54) (#55)

coisa · github-actions[bot] · web-flow · commit 47f7756af3ca · 2026-04-17T17:25:32.000-03:00
* Add reports previews for pull requests * Update wiki submodule pointer for PR #55 * Update the URL for the pull request report preview environment. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Update the URL for the pull request report preview environment. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Adds ways to trigger tests in pull requests. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Fix the URL for the pull request report preview environment. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Updates the workflow to include closing pull requests and improves the deployment of preview reports. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Remove pull request reports preview deployment and update main reports deployment conditions Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Adds support for additional arguments in documentation and test generation commands. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Remove keeping files and exclude assets during report deployments Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Fix tests Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Adds steps to restore and copy previews during report generation. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Add a comment with preview URLs to pull requests. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Update directory paths for permissions and restore previews in reports. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Updates report generation command to include destination and coverage options. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Updates publication directories to use ./tmp/reports/ instead of ./public Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * Updates pull request event types to include 'closed' and removes unnecessary permissions. Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> * docs: add documentation for GitHub Actions workflows and repository setup procedures --------- Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/.github/wiki b/.github/wiki
@@ -1 +1 @@
-Subproject commit 60910d026b0af8eb430cff4ef449760fd1e6e01f
+Subproject commit 6e2dfccfd3d375c4b6a365091c5b71919184302a
diff --git a/.github/workflows/reports.yml b/.github/workflows/reports.yml
@@ -3,22 +3,29 @@ name: Generate Reports and Deploy to GitHub Pages
 on:
     workflow_call:
     workflow_dispatch:
+    pull_request:
+        types: [ "opened", "synchronize", "reopened", "closed" ]
     push:
         branches: [ "main" ]
 
 permissions:
     contents: write
-    pages: write
-    id-token: write
+    pull-requests: write
 
 concurrency:
     group: "pages"
     cancel-in-progress: false
 
 jobs:
     reports:
+        if: github.event_name != 'pull_request' || github.event.action != 'closed'
         name: Generate Reports
         runs-on: ubuntu-latest
+
+        env:
+            PAGES_ARTIFACT_NAME: ${{ github.event_name == 'pull_request' && format('github-pages-pr-{0}', github.event.pull_request.number) || 'github-pages' }}
+            REPORTS_ROOT_VERSION: ${{ github.event_name == 'pull_request' && format('dev-{0}', github.event.pull_request.head.ref) || 'dev-main' }}
+
         steps:
             - uses: actions/checkout@v6
 
@@ -41,45 +48,98 @@ jobs:
               env:
                 COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ github.token }}"} }'
                 COMPOSER_CACHE_DIR: /tmp/composer-cache
-                COMPOSER_ROOT_VERSION: dev-main
+                COMPOSER_ROOT_VERSION: ${{ env.REPORTS_ROOT_VERSION }}
               run: composer install --prefer-dist --no-progress --no-interaction --no-scripts
 
             - name: Mark workspace as safe for git
               run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
             - name: Generate reports
               env:
-                COMPOSER_ROOT_VERSION: dev-main
-              run: composer dev-tools reports
+                COMPOSER_ROOT_VERSION: ${{ env.REPORTS_ROOT_VERSION }}
+              run: composer dev-tools reports -- --target=tmp/reports --coverage=tmp/reports/coverage
 
             - name: Fix permissions
               run: |
-                chmod -c -R +rX "public/" | while read line; do
+                chmod -c -R +rX "tmp/reports/" | while read line; do
                     echo "::warning title=Invalid file permissions automatically fixed::$line"
                 done
 
-            - name: Upload artifact
-              if: github.ref == 'refs/heads/main'
-              uses: actions/upload-pages-artifact@v5
-              with:
-                path: public/
-
-    deploy:
-        if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+            - name: Add .nojekyll
+              run: touch tmp/reports/.nojekyll
 
-        name: Deploy to GitHub Pages
-        needs: reports
+            - name: Restore previews from gh-pages
+              if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+              uses: actions/checkout@v6
+              continue-on-error: true
+              with:
+                ref: gh-pages
+                path: gh-pages-current
 
-        permissions:
-            pages: write
-            id-token: write
+            - name: Copy existing previews into publish directory
+              if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+              run: |
+                if [ -d "gh-pages-current/previews" ]; then
+                    mkdir -p tmp/reports/previews
+                    cp -R gh-pages-current/previews/. tmp/reports/previews/
+                fi
+
+            - name: Deploy main reports
+              if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+              uses: peaceiris/actions-gh-pages@v4
+              with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                publish_branch: gh-pages
+                publish_dir: ./tmp/reports/
+                destination_dir: .
+                keep_files: false
+                force_orphan: false
+
+            - name: Deploy PR preview
+              if: github.event_name == 'pull_request'
+              uses: peaceiris/actions-gh-pages@v4
+              with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                publish_branch: gh-pages
+                publish_dir: ./tmp/reports/
+                destination_dir: previews/pr-${{ github.event.pull_request.number }}
+                keep_files: false
+                force_orphan: false
+
+            - name: Comment preview URLs on pull request
+              if: github.event_name == 'pull_request'
+              uses: marocchino/sticky-pull-request-comment@v2
+              with:
+                header: pr-preview
+                message: |
+                  🚀 Preview is available for this pull request.
 
-        environment:
-            name: github-pages
-            url: ${{ steps.deployment.outputs.page_url }}
+                  - Docs: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/
+                  - Coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/coverage/
 
+    cleanup_preview:
+        if: github.event_name == 'pull_request' && github.event.action == 'closed'
+        name: Cleanup Pull Request Preview
         runs-on: ubuntu-latest
+
         steps:
-            - name: Deploy to GitHub Pages
-              id: deployment
-              uses: actions/deploy-pages@v5
+            - name: Checkout gh-pages
+              uses: actions/checkout@v6
+              with:
+                ref: gh-pages
+                path: gh-pages
+
+            - name: Remove preview directory
+              run: |
+                rm -rf "gh-pages/previews/pr-${{ github.event.pull_request.number }}"
+                cd gh-pages
+                touch .nojekyll
+                git config user.name "github-actions[bot]"
+                git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+                git add -A
+                git diff --cached --quiet || git commit -m "chore: remove preview for PR #${{ github.event.pull_request.number }}"
+
+            - name: Push changes
+              run: |
+                cd gh-pages
+                git push
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -16,6 +16,12 @@ on:
                 type: number
                 default: 80
     pull_request:
+        paths:
+          - 'src/**'
+          - 'tests/**'
+          - 'composer.json'
+          - 'composer.lock'
+          - '.github/workflows/tests.yml'
     push:
         branches: [ "main" ]
 
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
@@ -10,3 +10,4 @@ command supports them.
 
    tooling-defaults
    overriding-defaults
+   repository-setup
diff --git a/docs/configuration/repository-setup.rst b/docs/configuration/repository-setup.rst
@@ -0,0 +1,49 @@
+Repository Setup
+================
+
+To fully utilize the automation and documentation features provided by FastForward DevTools, consumer repositories require specific configurations in GitHub.
+
+GitHub Pages
+------------
+
+FastForward DevTools automatically generates and deploys reports, test coverage, and API documentation to GitHub Pages.
+
+1.  Navigate to your repository on GitHub.
+2.  Go to **Settings** > **Pages**.
+3.  Under **Build and deployment** > **Branch**:
+    *   Select the ``gh-pages`` branch.
+    *   Select ``/ (root)`` as the folder.
+    *   Click **Save**.
+
+.. note::
+   The ``gh-pages`` branch is automatically created and updated by the ``reports.yml`` workflow. If the branch does not exist yet, run the workflow manually once or wait for the first push to ``main``.
+
+GitHub Wiki
+-----------
+
+The wiki synchronization feature allows you to maintain documentation in Markdown within your repository and have it automatically published to the GitHub Wiki.
+
+.. important::
+   **Initial Manual Step Required**
+   GitHub does not create the underlying wiki repository until at least one page is created via the web interface. You **MUST** create an initial ``Home.md`` page manually before using ``dev-tools wiki --init`` or any automated sync features.
+
+1.  Navigate to your repository on GitHub.
+2.  Click the **Wiki** tab.
+3.  Click **Create the first page** (or **New Page**).
+4.  Ensure the title is ``Home`` and add some initial content.
+5.  Click **Save Page**.
+
+Once this is done, the wiki can be cloned as a submodule and synchronized by the DevTools commands.
+
+Workflow Permissions
+--------------------
+
+GitHub Actions must have permission to push changes to your repository (for Wiki updates and GitHub Pages deployments).
+
+1.  Go to **Settings** > **Actions** > **General**.
+2.  Scroll down to **Workflow permissions**.
+3.  Select **Read and write permissions**.
+4.  Click **Save**.
+
+.. warning::
+   Without these permissions, the ``wiki.yml`` and ``reports.yml`` workflows will fail when attempting to deploy content.
diff --git a/docs/usage/github-actions.rst b/docs/usage/github-actions.rst
@@ -0,0 +1,65 @@
+GitHub Actions Workflows
+========================
+
+FastForward DevTools provides a set of reusable GitHub Actions workflows that automate testing, documentation generation, and wiki synchronization. These workflows are synchronized into consumer repositories via the ``dev-tools:sync`` command.
+
+Workflow Inheritance
+--------------------
+
+Workflows in consumer repositories (located in ``.github/workflows/``) are typically "thin wrappers" that inherit logic from the central ``dev-tools`` repository.
+
+Example of an inherited workflow:
+
+.. code-block:: yaml
+
+    name: "Fast Forward Reports"
+    uses: php-fast-forward/dev-tools/.github/workflows/reports.yml@main
+    secrets: inherit
+
+This approach ensures that all libraries in the ecosystem benefit from infrastructure updates without requiring manual changes to every repository.
+
+Fast Forward Reports
+--------------------
+
+The ``reports.yml`` workflow is responsible for generating technical documentation and quality reports.
+
+**Triggers:**
+*   Push to ``main``.
+*   Pull Request (opened, synchronized, reopened, closed).
+*   Manual trigger (workflow_dispatch).
+
+**Behavior:**
+*   **Main Branch**: Runs all checks and deploys the final reports to the root of the ``gh-pages`` branch.
+*   **Pull Requests**:
+    *   Generates a **Preview** of the documentation and coverage.
+    *   Deploys the preview to ``gh-pages`` under ``previews/pr-{number}/``.
+    *   Posts a **Sticky Comment** on the PR with links to the live preview and coverage report.
+    *   **Cleanup**: When a PR is closed, the workflow automatically removes the preview directory from the ``gh-pages`` branch to keep the repository clean.
+
+Fast Forward Wiki
+-----------------
+
+The ``wiki.yml`` workflow synchronizes the documentation generated by the ``dev-tools wiki`` command with the GitHub Wiki repository.
+
+**Behavior:**
+*   **Submodule Management**: It manages a submodule at ``.github/wiki`` that points to the actual wiki repository.
+*   **Pull Requests**: Pushes documentation changes to a dedicated branch (e.g., ``pr-123``) in the wiki repository for review.
+*   **Merge**: When a PR is merged into ``main``, it pushes the changes to the ``master`` branch of the wiki, making them live.
+
+.. note::
+   See :doc:`../configuration/repository-setup` for mandatory initial setup required for the Wiki workflow to function.
+
+Fast Forward Tests
+------------------
+
+The ``tests.yml`` workflow provides standard Continuous Integration.
+
+*   Runs PHPUnit tests across supported PHP versions (defaults to 8.3).
+*   Validates code style using ECS.
+*   Performs static analysis.
+
+Maintenance Workflows
+---------------------
+
+*   **Auto Assign**: Automatically assigns reviewers to PRs.
+*   **Label Sync**: Synchronizes repository labels with ecosystem standards.
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
@@ -10,5 +10,6 @@ task-oriented guidance instead of class-by-class reference.
    common-workflows
    testing-and-coverage
    documentation-workflows
+   github-actions
    syncing-packaged-skills
    syncing-consumer-projects
diff --git a/resources/github-actions/reports.yml b/resources/github-actions/reports.yml
@@ -1,15 +1,16 @@
 name: "Fast Forward Reports"
 
 on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
   push:
     branches:
       - main
   workflow_dispatch:
 
 permissions:
   contents: write
-  pages: write
-  id-token: write
+  pull-requests: write
 
 jobs:
   reports:
diff --git a/src/Console/Command/ReportsCommand.php b/src/Console/Command/ReportsCommand.php
@@ -90,12 +90,12 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $docs = $this->processBuilder
             ->withArgument('--ansi')
             ->withArgument('--target', $input->getOption('target'))
-            ->build('composer dev-tools docs');
+            ->build('composer dev-tools docs --');
 
         $coverage = $this->processBuilder
             ->withArgument('--ansi')
             ->withArgument('--coverage', $input->getOption('coverage'))
-            ->build('composer dev-tools tests');
+            ->build('composer dev-tools tests --');
 
         $this->processQueue->add(process: $docs, detached: true);
         $this->processQueue->add(process: $coverage, detached: true);
diff --git a/tests/Console/Command/ReportsCommandTest.php b/tests/Console/Command/ReportsCommandTest.php
@@ -90,10 +90,10 @@ protected function setUp(): void
         $this->processBuilder->withArgument(Argument::cetera())
             ->willReturn($this->processBuilder->reveal());
 
-        $this->processBuilder->build('composer dev-tools docs')
+        $this->processBuilder->build('composer dev-tools docs --')
             ->willReturn($this->docsProcess->reveal());
 
-        $this->processBuilder->build('composer dev-tools tests')
+        $this->processBuilder->build('composer dev-tools tests --')
             ->willReturn($this->testsProcess->reveal());
 
         $this->processQueue->run($this->output->reveal())

Original file line number	Diff line number	Diff line change
`@@ -10,3 +10,4 @@ command supports them.`
`10`	`10`
`11`	`11`	`tooling-defaults`
`12`	`12`	`overriding-defaults`
	`13`	`+ repository-setup`