docs: document CI testing strategy for actions

Add documentation explaining how CI tests local GitHub Actions using arrange-act-assert patterns and how tests adapt to different trigger contexts (branch push, tag push, PR).

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

.github/workflows/__test-action-docker-build-image.yml

@@ -123,7 +123,10 @@ jobs:
               expectedTags.push(refTag);
               expectedImageVersion = refTag;
 
-              if (`${{ github.event_name }}` === "push" && refTag === "${{ github.event.repository.default_branch }}") {
+              const isTag = `${{ github.ref }}`.startsWith('refs/tags/');
+              const isPushOnDefaultBranch = `${{ github.event_name }}` === "push" && !isTag && refTag === "${{ github.event.repository.default_branch }}";
+
+              if (isPushOnDefaultBranch) {
                 expectedTags.push("latest");
               }
             }

.github/workflows/__test-action-get-image-metadata.yml

@@ -86,8 +86,13 @@ jobs:
 
               expectedTags.push(prShaTag, prTag);
             } else {
-              expectedTags.push("main");
-              if (`${{ github.event_name }}` === "push" && `${{ github.ref_name }}` === "${{ github.event.repository.default_branch }}") {
+              const refTag = `${{ github.ref_name }}`;
+              expectedTags.push(refTag);
+
+              const isTag = `${{ github.ref }}`.startsWith('refs/tags/');
+              const isPushOnDefaultBranch = `${{ github.event_name }}` === "push" && !isTag && refTag === "${{ github.event.repository.default_branch }}";
+
+              if (isPushOnDefaultBranch) {
                 expectedTags.push("latest");
               }
             }

AGENTS.md

@@ -17,6 +17,7 @@ This project contains **opinionated GitHub Actions and reusable workflows** to s
 - **[Reusable Workflows](README.md#reusable-workflows)** – Orchestration playbooks for common CI tasks
 - **[Contributing](README.md#contributing)** – Contribution guidelines, action structure patterns, and development standards
 - **[Development Workflow](README.md#development-workflow)** – Commands for linting, testing, and local development
+- **[CI Testing Strategy](README.md#ci-testing-strategy)** – How we test local actions with arrange-act-assert patterns across different trigger contexts
 
 ## Agent-Specific Development Patterns
 

README.md

@@ -121,6 +121,23 @@ make test-build-application  # Build and push the sample test application image
 make test-ct-install         # Validate Helm charts via chart-testing
 ```
 
+#### CI Testing Strategy
+
+The repository includes comprehensive end-to-end tests for all local GitHub Actions. These tests follow an **Arrange-Act-Assert** pattern:
+
+1. **Arrange**: Set up test fixtures and inputs (e.g., checkout code, prepare test context)
+2. **Act**: Execute the action being tested with specific inputs
+3. **Assert**: Validate outputs match expected values using `actions/github-script`
+
+Test workflows are located in `.github/workflows/__test-action-*.yml` and `.github/workflows/__test-workflow-*.yml`. They run on:
+
+- Push to `main` branch
+- Push to tags (e.g., `v1.0.0`)
+- Pull request events
+- Scheduled runs (weekly)
+
+**Tag-specific behavior**: When tests run on tag pushes, assertions dynamically adapt to expect the tag name (e.g., `v1.0.0`) instead of branch names. This ensures tests pass in all trigger contexts without hardcoding expected values.
+
 ## Author
 
 🏢 **Hoverkraft <contact@hoverkraft.cloud>**