From 584f121abab3c38bf41555159dfd8df5850288c5 Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Fri, 1 Aug 2025 21:30:26 -0300 Subject: [PATCH 1/4] Refactor github-trigger.py script into workflow-trigger prompt template - Remove scripts/github-trigger.py - Add struct_module/contribs/github/prompts/workflow-trigger.yaml - Convert standalone Python script to reusable prompt template - Follow existing prompt template structure and patterns - Provide comprehensive guidance for GitHub workflow automation - Include security best practices and error handling guidance - Support template-driven approach for better maintainability Resolves #71 --- scripts/github-trigger.py | 57 ------- .../github/prompts/workflow-trigger.yaml | 139 ++++++++++++++++++ 2 files changed, 139 insertions(+), 57 deletions(-) delete mode 100644 scripts/github-trigger.py create mode 100644 struct_module/contribs/github/prompts/workflow-trigger.yaml diff --git a/scripts/github-trigger.py b/scripts/github-trigger.py deleted file mode 100644 index d740680..0000000 --- a/scripts/github-trigger.py +++ /dev/null @@ -1,57 +0,0 @@ -import os -from github import Github -import argparse -import logging - -# Configure logging -logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') - -def get_repositories_with_topic(org_name, topic): - """Fetch all repositories in an organization with a specific topic.""" - token = os.getenv("GITHUB_TOKEN") - if not token: - raise EnvironmentError("GITHUB_TOKEN environment variable is not set.") - - github = Github(token) - org = github.get_organization(org_name) - repos_with_topic = [] - - for repo in org.get_repos(): - if topic in repo.get_topics(): - repos_with_topic.append(repo) - - return repos_with_topic - -def trigger_workflow(repo): - """Trigger the 'run-struct.yaml' workflow for a given repository.""" - workflows = repo.get_workflows() - for workflow in workflows: - if workflow.path.endswith("run-struct.yaml"): - workflow.create_dispatch(ref=repo.default_branch) - logging.info(f"Triggered workflow for repository: {repo.full_name}") - return - - logging.warning(f"No 'run-struct.yaml' workflow found in repository: {repo.full_name}") - -def main(): - parser = argparse.ArgumentParser(description="Trigger 'run-struct.yaml' workflow for repositories with a specific topic.") - parser.add_argument("--org", required=True, help="The GitHub organization name.") - parser.add_argument("--topic", required=True, help="The topic to filter repositories by.") - - args = parser.parse_args() - - org_name = args.org - topic = args.topic - - try: - repos = get_repositories_with_topic(org_name, topic) - logging.info(f"Found {len(repos)} repositories with topic '{topic}'.") - - for repo in repos: - trigger_workflow(repo) - - except Exception as e: - logging.error(f"Error: {e}") - -if __name__ == "__main__": - main() diff --git a/struct_module/contribs/github/prompts/workflow-trigger.yaml b/struct_module/contribs/github/prompts/workflow-trigger.yaml new file mode 100644 index 0000000..5bb6658 --- /dev/null +++ b/struct_module/contribs/github/prompts/workflow-trigger.yaml @@ -0,0 +1,139 @@ +files: + - .github/prompts/workflow-trigger.prompt.md: + content: | + # GitHub Workflow Trigger Assistant + + ## Role + + You are an expert assistant that helps create automation scripts for triggering GitHub workflows across multiple repositories in an organization based on topics. + + ## Purpose + + Generate Python scripts that can: + - Fetch repositories in a GitHub organization with specific topics + - Trigger specific workflows (like 'run-struct.yaml') for matching repositories + - Handle authentication and error management properly + - Provide comprehensive logging and feedback + + ## Key Components + + ### 1. GitHub API Authentication + - Use GITHUB_TOKEN environment variable for authentication + - Implement proper error handling for missing tokens + - Use PyGithub library for reliable GitHub API interactions + + ### 2. Repository Discovery + - Filter repositories by organization and topic + - Handle pagination for large organizations + - Provide informative logging about discovered repositories + + ### 3. Workflow Triggering + - Find workflows by filename pattern (e.g., 'run-struct.yaml') + - Trigger workflow_dispatch events on the default branch + - Handle cases where target workflow doesn't exist + + ### 4. Security Best Practices + - Never hardcode tokens or sensitive information + - Use environment variables for configuration + - Implement proper exception handling + - Validate inputs before processing + + ## Template Variables + + When generating scripts, consider these configurable elements: + - **Organization name**: Target GitHub organization + - **Topic filter**: Repository topic to filter by + - **Workflow filename**: Target workflow file (default: 'run-struct.yaml') + - **Branch reference**: Branch to trigger workflow on (default: default branch) + + ## Example Implementation Structure + + ```python + import os + from github import Github + import argparse + import logging + + # Configure logging + logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') + + def get_repositories_with_topic(org_name, topic): + """Fetch all repositories in an organization with a specific topic.""" + # Implementation here + + def trigger_workflow(repo, workflow_filename='run-struct.yaml'): + """Trigger the specified workflow for a given repository.""" + # Implementation here + + def main(): + # Argument parsing and main logic + pass + + if __name__ == "__main__": + main() + ``` + + ## Security Considerations + + - **Token Management**: Always use environment variables for GitHub tokens + - **Permissions**: Ensure the token has appropriate workflow trigger permissions + - **Rate Limiting**: Consider GitHub API rate limits for large organizations + - **Error Handling**: Implement comprehensive error handling and logging + - **Validation**: Validate organization existence and access permissions + + ## Usage Patterns + + Typical usage scenarios: + 1. **Bulk Updates**: Trigger structure updates across multiple repositories + 2. **CI/CD Integration**: Automate workflow triggers from other CI/CD systems + 3. **Maintenance Tasks**: Perform organization-wide maintenance operations + 4. **Development Workflows**: Coordinate multi-repository development tasks + + ## Dependencies + + Required Python packages: + - `PyGithub`: For GitHub API interactions + - `argparse`: For command-line argument parsing (built-in) + - `logging`: For comprehensive logging (built-in) + - `os`: For environment variable access (built-in) + + ## Installation Command + + ```bash + pip install PyGithub + ``` + + ## Error Handling Scenarios + + Handle these common scenarios: + - Missing GITHUB_TOKEN environment variable + - Invalid organization name or insufficient permissions + - Repositories without the target workflow + - API rate limiting + - Network connectivity issues + + ## Output Requirements + + Generate a complete, production-ready Python script that: + - Accepts command-line arguments for organization and topic + - Provides clear, informative logging + - Handles errors gracefully + - Follows Python best practices + - Includes proper documentation and comments + + ## Example Command-Line Usage + + ```bash + python workflow_trigger.py --org myorg --topic struct-managed + ``` + + ## Best Practices + + - Use descriptive variable names and function names + - Include docstrings for all functions + - Implement proper logging levels (INFO, WARNING, ERROR) + - Provide helpful error messages + - Consider adding dry-run functionality for testing + - Make the script modular and reusable + + Remember to generate clean, maintainable code that follows Python conventions and provides a good user experience. From 78d28ccd9817905df08d36535a53f3f1ca6e4bdc Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Fri, 1 Aug 2025 21:34:51 -0300 Subject: [PATCH 2/4] Remove documentation references to deleted github-trigger.py script - Remove GitHub Trigger Script section from docs/github-integration.md - Clean up script usage examples and troubleshooting info - Maintain focus on GitHub Actions integration - Keep best practices and FAQ sections intact --- docs/github-integration.md | 73 +------------------------------------- 1 file changed, 1 insertion(+), 72 deletions(-) diff --git a/docs/github-integration.md b/docs/github-integration.md index fd84322..f748bd2 100644 --- a/docs/github-integration.md +++ b/docs/github-integration.md @@ -1,77 +1,6 @@ # GitHub Integration -STRUCT can seamlessly integrate with GitHub to automate the generation of project structures across repositories. This documentation explains how to set up and use the GitHub trigger script. - -## GitHub Trigger Script - -The `github-trigger.py` script is a utility designed to trigger the `run-struct` workflow for all private repositories in a GitHub organization that meet specific criteria. This script is particularly useful for automating tasks across multiple repositories. - -### Features - -- Filters repositories by a specific topic (e.g., `struct-enabled`). -- Checks for the existence of a `.struct.yaml` file in the repository's default branch. -- Verifies the presence of the `run-struct` workflow file in `.github/workflows/`. -- Triggers the workflow dispatch event for eligible repositories. - -### Usage - -To use the script, ensure you have the following prerequisites: - -1. A valid GitHub Personal Access Token with the necessary permissions (set as the `GITHUB_TOKEN` environment variable). -2. The `PyGithub` library installed (`pip install PyGithub`). - -Run the script with the following command: - -```sh -python3 scripts/github-trigger.py -``` - -#### Arguments - -- ``: The name of the GitHub organization. -- ``: The topic to filter repositories by (e.g., `struct-enabled`). - -#### Example - -```sh -export GITHUB_TOKEN=your_personal_access_token -python3 scripts/github-trigger.py my-org struct-enabled -``` - -### How It Works - -1. The script connects to the GitHub API using the provided token. -2. It iterates through all private repositories in the specified organization. -3. For each repository: - - Checks if the repository has the specified topic. - - Verifies the existence of a `.struct.yaml` file in the default branch. - - Confirms the presence of the `run-struct` workflow file. - - Triggers the workflow dispatch event if all conditions are met. - -### Notes - -- Ensure the `GITHUB_TOKEN` environment variable is set before running the script. -- The token must have sufficient permissions to access private repositories and trigger workflows. -- Errors during execution (e.g., missing files or insufficient permissions) will be logged to the console. - -### Advanced Usage - -Add additional parameters to customize the script's behavior: - -- `--dry-run`: Simulate the script actions without executing any API calls. -- `--verbose`: Enable verbose output for debugging purposes. - -Example: - -```sh -python3 scripts/github-trigger.py my-org struct-enabled --dry-run --verbose -``` - -### Troubleshooting - -- **Unauthorized Error**: Make sure your token has the appropriate permissions. -- **Repository Not Found**: Ensure the organization name is correct and the token has access. -- **Missing Files**: Verify that the `.struct.yaml` and workflow files exist in each repository. +STRUCT can seamlessly integrate with GitHub to automate the generation of project structures across repositories. ## Automating STRUCT From 9820c0d0da456636aa7c02eda8ff49e97086604a Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Fri, 1 Aug 2025 21:51:00 -0300 Subject: [PATCH 3/4] Refactor prompt template: move to prompts/ and simplify for MCP integration - Move from github/prompts/workflow-trigger.yaml to prompts/run-struct-trigger.yaml - Simplify content to focus on MCP-based GitHub automation - Target specific 'struct-enabled' topic and 'run-struct' workflow - Add github_organization template variable for configurability - Create more focused, actionable prompt for AI assistants with MCP capabilities --- .../github/prompts/workflow-trigger.yaml | 139 ------------------ .../contribs/prompts/run-struct-trigger.yaml | 14 ++ 2 files changed, 14 insertions(+), 139 deletions(-) delete mode 100644 struct_module/contribs/github/prompts/workflow-trigger.yaml create mode 100644 struct_module/contribs/prompts/run-struct-trigger.yaml diff --git a/struct_module/contribs/github/prompts/workflow-trigger.yaml b/struct_module/contribs/github/prompts/workflow-trigger.yaml deleted file mode 100644 index 5bb6658..0000000 --- a/struct_module/contribs/github/prompts/workflow-trigger.yaml +++ /dev/null @@ -1,139 +0,0 @@ -files: - - .github/prompts/workflow-trigger.prompt.md: - content: | - # GitHub Workflow Trigger Assistant - - ## Role - - You are an expert assistant that helps create automation scripts for triggering GitHub workflows across multiple repositories in an organization based on topics. - - ## Purpose - - Generate Python scripts that can: - - Fetch repositories in a GitHub organization with specific topics - - Trigger specific workflows (like 'run-struct.yaml') for matching repositories - - Handle authentication and error management properly - - Provide comprehensive logging and feedback - - ## Key Components - - ### 1. GitHub API Authentication - - Use GITHUB_TOKEN environment variable for authentication - - Implement proper error handling for missing tokens - - Use PyGithub library for reliable GitHub API interactions - - ### 2. Repository Discovery - - Filter repositories by organization and topic - - Handle pagination for large organizations - - Provide informative logging about discovered repositories - - ### 3. Workflow Triggering - - Find workflows by filename pattern (e.g., 'run-struct.yaml') - - Trigger workflow_dispatch events on the default branch - - Handle cases where target workflow doesn't exist - - ### 4. Security Best Practices - - Never hardcode tokens or sensitive information - - Use environment variables for configuration - - Implement proper exception handling - - Validate inputs before processing - - ## Template Variables - - When generating scripts, consider these configurable elements: - - **Organization name**: Target GitHub organization - - **Topic filter**: Repository topic to filter by - - **Workflow filename**: Target workflow file (default: 'run-struct.yaml') - - **Branch reference**: Branch to trigger workflow on (default: default branch) - - ## Example Implementation Structure - - ```python - import os - from github import Github - import argparse - import logging - - # Configure logging - logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') - - def get_repositories_with_topic(org_name, topic): - """Fetch all repositories in an organization with a specific topic.""" - # Implementation here - - def trigger_workflow(repo, workflow_filename='run-struct.yaml'): - """Trigger the specified workflow for a given repository.""" - # Implementation here - - def main(): - # Argument parsing and main logic - pass - - if __name__ == "__main__": - main() - ``` - - ## Security Considerations - - - **Token Management**: Always use environment variables for GitHub tokens - - **Permissions**: Ensure the token has appropriate workflow trigger permissions - - **Rate Limiting**: Consider GitHub API rate limits for large organizations - - **Error Handling**: Implement comprehensive error handling and logging - - **Validation**: Validate organization existence and access permissions - - ## Usage Patterns - - Typical usage scenarios: - 1. **Bulk Updates**: Trigger structure updates across multiple repositories - 2. **CI/CD Integration**: Automate workflow triggers from other CI/CD systems - 3. **Maintenance Tasks**: Perform organization-wide maintenance operations - 4. **Development Workflows**: Coordinate multi-repository development tasks - - ## Dependencies - - Required Python packages: - - `PyGithub`: For GitHub API interactions - - `argparse`: For command-line argument parsing (built-in) - - `logging`: For comprehensive logging (built-in) - - `os`: For environment variable access (built-in) - - ## Installation Command - - ```bash - pip install PyGithub - ``` - - ## Error Handling Scenarios - - Handle these common scenarios: - - Missing GITHUB_TOKEN environment variable - - Invalid organization name or insufficient permissions - - Repositories without the target workflow - - API rate limiting - - Network connectivity issues - - ## Output Requirements - - Generate a complete, production-ready Python script that: - - Accepts command-line arguments for organization and topic - - Provides clear, informative logging - - Handles errors gracefully - - Follows Python best practices - - Includes proper documentation and comments - - ## Example Command-Line Usage - - ```bash - python workflow_trigger.py --org myorg --topic struct-managed - ``` - - ## Best Practices - - - Use descriptive variable names and function names - - Include docstrings for all functions - - Implement proper logging levels (INFO, WARNING, ERROR) - - Provide helpful error messages - - Consider adding dry-run functionality for testing - - Make the script modular and reusable - - Remember to generate clean, maintainable code that follows Python conventions and provides a good user experience. diff --git a/struct_module/contribs/prompts/run-struct-trigger.yaml b/struct_module/contribs/prompts/run-struct-trigger.yaml new file mode 100644 index 0000000..1079046 --- /dev/null +++ b/struct_module/contribs/prompts/run-struct-trigger.yaml @@ -0,0 +1,14 @@ +files: + - run-struct-trigger.md: + content: | + You are a helpful assistant that can query Github Using MCP + + I will need you to get the list of repositories that have the following topic: "struct-enabled" + The organization should be "{{@ github_organization @}}" + + To all those repositories, you will need to trigger a workflow called "run-struct" + +variables: + - github_organization: + type: string + description: The organization to query for repositories From aa6355284b03aab288da9f78c3ad27428fcb8144 Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Fri, 1 Aug 2025 21:55:54 -0300 Subject: [PATCH 4/4] Make topic configurable in run-struct-trigger prompt template - Replace hardcoded 'struct-enabled' with {{@ topic @}} template variable - Add topic variable with string type and descriptive text - Set 'struct-enabled' as default value for backward compatibility - Increase template flexibility for different repository topics --- struct_module/contribs/prompts/run-struct-trigger.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/struct_module/contribs/prompts/run-struct-trigger.yaml b/struct_module/contribs/prompts/run-struct-trigger.yaml index 1079046..8852c7e 100644 --- a/struct_module/contribs/prompts/run-struct-trigger.yaml +++ b/struct_module/contribs/prompts/run-struct-trigger.yaml @@ -3,7 +3,7 @@ files: content: | You are a helpful assistant that can query Github Using MCP - I will need you to get the list of repositories that have the following topic: "struct-enabled" + I will need you to get the list of repositories that have the following topic: "{{@ topic @}}" The organization should be "{{@ github_organization @}}" To all those repositories, you will need to trigger a workflow called "run-struct" @@ -12,3 +12,7 @@ variables: - github_organization: type: string description: The organization to query for repositories + - topic: + type: string + description: The topic to query for repositories + default: "struct-enabled"