Repo Dispatch Setup

Repository Dispatch Setup Guide

This guide explains how to implement repository dispatch to trigger integration tests in testviper when there are merges to the main branches of toolviper, xradio, graphviper, or astroviper.

Overview

The solution consists of:

1. Dispatch Sender: Modified workflows in source repositories (toolviper, xradio, graphviper, astroviper)
2. Dispatch Receiver: Modified workflow in testviper that listens for dispatch events

Prerequisites

1. Create a Personal Access Token (PAT)

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Create a new token with the following permissions:
   • repo (Full control of private repositories)
   • workflow (Update GitHub Action workflows)
3. Copy the token value

2. Add the Token as a Secret

For each source repository (toolviper, xradio, graphviper, astroviper):

1. Go to repository Settings → Secrets and variables → Actions
2. Add a new repository secret:
   • Name: TESTVIPER_DISPATCH_TOKEN
   • Value: The PAT created above

For testviper repository:

1. Go to repository Settings → Secrets and variables → Actions
2. Add the same repository secret:
   • Name: TESTVIPER_DISPATCH_TOKEN
   • Value: The same PAT

Implementation Steps

Step 1: Update Source Repository Workflows

Replace or modify the existing python-testing-integration-template.yml in the nrao organization in GitHub, gh-actions-template-public workflows. Follow up with adding the repository dispatch token to the source repository (toolviper, xradio, graphviper, astroviper) (TBC) to send the token across organizations. This might change in the near future after all projects move to the same nrao organization.

File path: .github/workflows/python-testing-integration-template.yml

Key features of the sender workflow:

• Runs existing tests as before
• Adds a new job dispatch-integration-tests that only runs on main branch pushes
• Sends repository dispatch event to testviper with metadata about the triggering event

Step 2: Update testviper Workflow

Replace or modify the existing python-tests-allure-report.yml in testviper repository with the dispatch receiver workflow.

File path: .github/workflows/python-tests-allure-report.yml

Key features of the receiver workflow:

• Listens for repository_dispatch events with type integration-test-trigger
• Runs integration tests with Allure reporting
• Uploads Allure reports as artifacts
• Optionally deploys reports to GitHub Pages
• Sends status updates back to the source repository

Step 3: Enable GitHub Pages (Optional)

To automatically publish Allure reports:

1. Go to testviper repository Settings → Pages
2. Set Source to "GitHub Actions"
3. Reports will be available at: https://casangi.github.io/testviper/allure-report/

How It Works

Trigger Flow

1. Developer pushes to main branch of toolviper, xradio, graphviper, or astroviper
2. Source repository workflow runs and completes its tests
3. Dispatch event is sent to testviper with metadata:

   {
     "repository": "casangi/toolviper",
     "ref": "refs/heads/main",
     "sha": "abc123...",
     "actor": "developer-username",
     "workflow": "Python Integration Testing with Dispatch",
     "run_id": "123456789",
     "run_number": "42"
   }

4. testviper workflow is triggered automatically
5. Integration tests run with Allure reporting
6. Status is reported back to the source repository as a commit status
7. Allure reports are generated and uploaded

Event Types

The system responds to:

• push events to main branch of source repositories
• repository_dispatch events in testviper
• workflow_dispatch for manual triggering
• schedule for periodic integration tests (daily at 2 AM UTC)

Testing the Setup

Manual Testing

1. Trigger manually: Go to testviper → Actions → Select the workflow → "Run workflow"
2. Test dispatch: Push a change to main branch of any source repository
3. Check logs: Verify the dispatch event details appear in testviper workflow logs

Verification Checklist

• DISPATCH_TOKEN secret is set in all repositories
• Source repositories have updated workflows
• testviper has updated workflow
• GitHub Pages is configured (if using report deployment)
• Test push to source repository triggers testviper workflow
• Allure reports are generated and accessible
• Status checks appear on source repository commits

Troubleshooting

Common Issues

1. Dispatch not triggering:

   • Check TESTVIPER_DISPATCH_TOKEN is valid and has correct permissions
   • Verify the token is added to both source and target repositories
   • Ensure workflow files are in the correct paths
   • Check validity of token as it has a limited duration.

2. Tests failing:

   • Check test dependencies are properly installed
   • Verify test files exist in expected locations
   • Review pytest configuration

3. Allure reports not generating:

   • Ensure Java is installed (required for Allure CLI)
   • Check allure-results directory is created
   • Verify pytest-allure-adaptor is installed

4. Status checks not appearing:

   • Confirm DISPATCH_TOKEN has repo permissions
   • Check the notify-completion job is running
   • Verify repository and SHA information in dispatch payload

Debug Information

The workflows include comprehensive logging:

• Dispatch event details are logged in testviper
• Client payload information is displayed
• Status updates include links back to test runs

Customization

Modify Trigger Conditions

To change when dispatch events are sent, modify the if condition in the dispatch job:

if: github.ref == 'refs/heads/main' && github.event_name == 'push'

Add More Metadata

Extend the client payload to include additional information:

client-payload: |
  {
    "repository": "${{ github.repository }}",
    "custom_field": "custom_value"
  }

Change Event Type

Modify the event type to categorize different dispatch sources:

event-type: integration-test-trigger-toolviper  # for toolviper
event-type: integration-test-trigger-xradio     # for xradio

Security Considerations

• The TESTVIPER_DISPATCH_TOKEN has significant permissions - store securely
• Consider using fine-grained PATs for better security
• Regularly rotate the token
• Monitor dispatch events for unexpected usage
• Ensure the token belongs to a service account rather than personal account

Maintenance

• Update Allure CLI version periodically in the receiver workflow
• Review and update Python versions in the matrix
• Monitor workflow run times and optimize as needed
• Update dependencies regularly for security patches