{"id":34889555,"url":"https://github.com/advanced-security/codeql-development-template","last_synced_at":"2026-01-06T00:56:05.095Z","repository":{"id":327680462,"uuid":"1098729265","full_name":"advanced-security/codeql-development-template","owner":"advanced-security","description":"Copilot-native repository template for CodeQL query development","archived":false,"fork":false,"pushed_at":"2025-12-15T14:35:28.000Z","size":222,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-16T00:40:25.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CodeQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/advanced-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T04:19:16.000Z","updated_at":"2025-12-15T14:35:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/advanced-security/codeql-development-template","commit_stats":null,"previous_names":["advanced-security/codeql-development-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/advanced-security/codeql-development-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Fcodeql-development-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Fcodeql-development-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Fcodeql-development-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Fcodeql-development-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/advanced-security","download_url":"https://codeload.github.com/advanced-security/codeql-development-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Fcodeql-development-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28142151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-31T02:00:06.200Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-26T05:00:31.731Z","updated_at":"2025-12-31T10:00:59.431Z","avatar_url":"https://github.com/advanced-security.png","language":"CodeQL","readme":"# codeql-development-template\n\n\u003e **Lowering the barrier to entry for CodeQL development through natural language and GitHub Copilot**\n\nA GitHub repository template for building custom CodeQL queries with AI assistance. This template provides a structured environment with prompts, instructions, and workflows designed to guide GitHub Copilot Coding Agent through the complete CodeQL development lifecycle.\n\n## Background\n\nThis repository template enables developers to create custom CodeQL security queries with minimal CodeQL expertise by leveraging:\n\n- **GitHub Copilot Coding Agent** for automated query development\n- **Hierarchical prompt system** that guides AI through CodeQL tasks\n- **Test-driven development methodology** for reliable query creation\n- **Pre-configured workflows** for setup, testing, and validation\n\n## Requirements\n\nBefore using this repository template, ensure your GitHub organization/account has:\n\n- **GitHub Actions** enabled for running CI/CD workflows\n- **GitHub Copilot Coding Agent** access for AI-assisted development\n- **GitHub Advanced Security** (optional, but recommended)\n\n## Getting Started\n\n### Step 1: Create a New Repository from Template\n\n1. Click the **\"Use this template\"** button at the top of this repository\n2. Choose **\"Create a new repository\"**\n3. Select your GitHub organization or personal account\n4. Enter a repository name (e.g., `my-codeql-queries`)\n5. Set the repository visibility (internal, private, or public)\n6. Click **\"Create repository\"**\n\n**Note:** The ['copilot-setup-steps' actions workflow](./.github/workflows/copilot-setup-steps.yml) will automatically set up the environment for Copilot Coding Agent (CCA), so local installation is optional and primarily useful for manual development.\n\n### Step 2: Create an Issue for the CodeQL query you want to develop\n\n1. **Navigate to Issues** in your new repository\n2. **Click \"New Issue\"**\n3. **Select \"Request new CodeQL Query\"** template\n4. **Fill in the details:**\n   - Choose target language (e.g., Java, Python, JavaScript)\n   - Describe what the query should detect\n   - Provide code examples (optional but recommended)\n   - Specify severity level\n5. **Submit the issue**\n\n### Step 3: Assign Issue to `@copilot`\n\n1. **Assign the issue** to `@copilot` (GitHub's Copilot Coding Agent user)\n2. **Wait for Copilot** to process the issue and create a Pull Request\n3. **Monitor progress** via the `Sessions` and/or comments for the new Pull Request\n\n### Step 4: Review Pull Request created by Copilot Coding Agent\n\n1. **Navigate to the generated Pull Request**\n2. **Review the changes:**\n   - Query implementation (`.ql` files)\n   - Test cases (in `test/` directories)\n   - Query documentation (`.md` and `.qhelp` files)\n3. **Check CI/CD results:**\n   - All tests pass\n   - Query compiles successfully\n   - Linting and formatting checks pass\n4. **Review and approve** the PR\n5. **Merge** to incorporate the query into your repository\n\n## 📋 Available Issue Templates\n\n| Template                                                                 | Purpose                                                                        |\n| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |\n| [Request new CodeQL Query](.github/ISSUE_TEMPLATE/query-create.yml)      | Create a new CodeQL query to detect specific code patterns or vulnerabilities  |\n| [Update existing CodeQL Query](.github/ISSUE_TEMPLATE/query-update.yml)  | Modify an existing query to improve accuracy or add new detection capabilities |\n| [Improve Prompts/Instructions](.github/ISSUE_TEMPLATE/prompt-update.yml) | Contribute improvements to the AI guidance system                              |\n\n## Repository Structure\n\nAfter creating your first query, your repository will contain:\n\n```text\ncodeql-development-template/\n├── .github/\n│   ├── instructions/           # Level 2: Language-specific Copilot instructions\n│   ├── prompts/               # Level 3: High-level prompt templates\n│   ├── ISSUE_TEMPLATE/        # Level 1: Entry points for Copilot workflows\n│   └── workflows/             # CI/CD automation for testing and setup\n├── languages/\n│   └── {language}/            # Per-language development environments\n│       ├── custom/            # Your custom queries (generated by Copilot)\n│       │   ├── src/          # Query source files (.ql)\n│       │   └── test/         # Query test cases\n│       ├── example/           # Example queries for reference\n│       └── tools/             # Development resources and AST exploration\n│           ├── dev/          # Language-specific development guides\n│           ├── src/          # PrintAST queries for exploring code structure\n│           └── test/         # PrintAST test suites\n├── resources/cli/             # CLI command reference documentation\n│   ├── codeql/               # CodeQL CLI subcommand guides\n│   └── qlt/                  # QLT CLI subcommand guides\n└── scripts/                   # Setup and automation scripts\n```\n\n## How It Works\n\nThis template implements a **hierarchical prompt system** that maximizes GitHub Copilot's effectiveness:\n\n1. **Issue Templates** provide structured input for query requirements\n2. **Language-Specific Instructions** guide Copilot with relevant context\n3. **High-Level Prompts** break down complex CodeQL workflows\n4. **Tool-Specific Resources** provide CLI usage examples and patterns\n5. **Test-Driven Development** ensures query accuracy through automated testing\n\nThe Copilot Coding Agent uses this hierarchy to:\n\n- Understand your query requirements\n- Generate appropriate CodeQL logic\n- Create comprehensive test cases\n- Validate query correctness\n- Document the query properly\n\nSee [PROMPTS.md](PROMPTS.md) for details on the prompt hierarchy system.\n\n## Supported Languages\n\nThe template supports CodeQL query development for:\n\n| Language              | CodeQL Library |\n| --------------------- | -------------- |\n| GitHub Actions        | `actions`      |\n| C/C++                 | `cpp`          |\n| C#                    | `csharp`       |\n| Go                    | `go`           |\n| Java                  | `java`         |\n| JavaScript/TypeScript | `javascript`   |\n| Python                | `python`       |\n| Ruby                  | `ruby`         |\n\n## License\n\nThis repository template is available under the [MIT License](LICENSE).\n\n## Maintainers\n\nThis repository template is maintained by the [CODEOWNERS](CODEOWNERS).\n\n## Support\n\nThis repository template comes with no expectation or guarantee of support, with more details in the [SUPPORT.md](SUPPORT.md) document.\n","funding_links":[],"categories":["Tooling \u0026 Environment"],"sub_categories":["CodeQL AI \u0026 LLM Tooling"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvanced-security%2Fcodeql-development-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadvanced-security%2Fcodeql-development-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvanced-security%2Fcodeql-development-template/lists"}