Zo haal je meer uit GitHub met custom agents

GitHub ondersteunt sinds een aantal maanden custom agents. Dit zijn AI-agents die je zelf kunt configureren door middel van specifieke instructies. Zo laat je een agent code analyseren, functionaliteit bouwen of bugs oplossen, precies volgens jouw manier van werken. Voor teams die serieus werk maken van softwareontwikkeling geeft dit directe controle. Geen generieke AI hulp, maar gerichte ondersteuning die past bij je proces.

Hoe werkt een agent binnen GitHub? 

Je roept een agent op vanuit GitHub Copilot, bijvoorbeeld via de Copilot pagina of het icoon rechtsboven in GitHub. Je wijst een repository aan en beschrijft de taak. Denk aan bouwen, aanpassen of analyseren van code.

Daarna kies je welke agent de taak uitvoert. Standaard is dit de Copilot agent. Die pakt complete user stories op, schrijft tests of past bestaande code aan. GitHub voert de taak uit en levert het resultaat aan via een pull request. Zo houd jij de regie, terwijl de agent meters maakt.

Zo maak je een eigen custom agent

Het aanmaken van een eigen custom agent binnen GitHub is verrassend eenvoudig, maar krachtig in mogelijkheden. Volg deze stappen om te beginnen: 

1. Maak een speciale repository aan 
   Binnen je GitHub-organisatie maak je een nieuwe repository genaamd github-private. Deze repository dient als centrale plek voor al je custom agents. 

2. Structuur van je agent-bestanden 
   In de repository maak je een map genaamd agents. Hierin komen alle definities van je agents. Elk agentbestand is een Markdown-bestand met de extensie .agent.md. Bijvoorbeeld: agents/my-first-agent.agent.md 

3. Schrijf de instructies van je agent 
   In deze Markdown-bestanden beschrijf je: 

• Welke rol heeft de agent: Denk aan een DevOps engineer of Security specialist 
• Wat de agent moet doen: bijvoorbeeld code genereren, refactoren of tests schrijven.
• Welke taken uitgevoerd moeten worden: concrete acties die de agent zelfstandig kan uitvoeren.
• Restricties en richtlijnen: bijvoorbeeld coding standards, securityregels, of beperkingen in het type code dat mag worden aangepast.   

Belangrijk: schrijf deze instructies in menselijke taal. De agent interpreteert de tekst en voert de taken uit op basis van de beschrijving, dus duidelijkheid en precisie zijn cruciaal. 

Door deze aanpak kun je agents creëren die precies passen bij de workflow en richtlijnen van jouw team. Je bepaalt zelf de scope en het gedrag van de agent, waardoor repetitieve taken geautomatiseerd worden en ontwikkelaars zich kunnen concentreren op complexere uitdagingen. 

Custom agents in de praktijk

Omdat wij bij Delta-N steeds meer repositories migreren van Azure DevOps naar GitHub, hebben we een onboarding agent ontwikkeld. Deze agent vergemakkelijkt het onboarden van gemigreerde repositories en zorgt ervoor dat nieuwe projecten direct voldoen aan onze standaarden. 

Onze onboarding agent voert twee belangrijke taken uit: 

1. CODEOWNERS bestand aanmaken 
   De agent creëert automatisch een CODEOWNERS file. Dit bestand geeft aan wie de eigenaar is van bepaalde bestanden of mappen binnen een repository. De owners zijn verantwoordelijk voor het goedkeuren van pull requests, waardoor codewijzigingen gecontroleerd en consistent blijven. 

2. Copilot-instructions.md bestand genereren 
   De agent maakt ook een copilot-instructions.md file aan. Tijdens dit proces wordt de gemigreerde repository geanalyseerd (discovery) om vast te leggen hoe de code gebouwd, getest en gedeployed moet worden. Door deze informatie beschikbaar te maken, kan de Copilot coding agent veel effectiever en gerichter aan de slag met de repository. 

Met deze onboarding agent kunnen gemigreerde repositories direct op de juiste manier worden ingericht, wordt de samenwerking binnen teams gestroomlijnd en kan AI-ondersteuning optimaal worden benut. 

Hieronder stukjes uit onze repo-onboarding.agent.md ter inspiratie 

Rol:

You are an expert DevOps Engineer. Your mission is to help developers onboard new GitHub repositories. There are two ways GitHub repositories can be onboarded: 

- Through migration from another platform like Azure DevOps 
- A new repository setup 

Your goal is to setup the repository for usage within the GitHub ecosystem. 

Doel:

Ensure the repository has a `copilot-instructions.md` file to guide AI tools like GitHub Copilot on how to assist with code generation and suggestions. Create the file if it does not exist in the `.github` folder. If the file exists, don't do anything and do not modify it.  

Taken:

Your task is to "onboard" this repository to Copilot coding agent by adding a `.github/copilot-instructions.md` file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently but also to supply information that relates for GitHub Copilot. 

You will do this task only one time per repository and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions. 

Goals:
- Provide information about the repository. 
- Reduce the likelihood of a coding agent pull request getting rejected by the user due to generating code that fails the continuous integration build, fails a validation pipeline, or having misbehavior. 
- Minimize bash command and build failures. 
- Allow the agent to complete its task more quickly by minimizing the need for exploration using grep, find, str_replace_editor, and code search tools. 

Build Instructions: 
Add information about how to build and validate changes so the agent does not need to search and find it each time. 
- For each of bootstrap, build, test, run, lint, and any other scripted step, document the sequence of steps to take to run it successfully as well as the versions of any runtime or build tools used. 
- Each command should be validated by running it to ensure that it works correctly as well as any preconditions and postconditions
- Try cleaning the repo and environment and running commands in different orders and document errors and misbehavior observed as well as any steps used to mitigate the problem. 
- Run the tests and document the order of steps required to run the tests. 
- Document environment setup steps that seem optional but that you have validated are actually required. 
- When you find a sequence of commands that work for a particular purpose, document them in detail. 
- Use language to indicate when something should always be done. For example: "always run npm install before building". 
- Record any validation steps from documentation. 

Restricties:

This agent is only permitted to commit changes to files within the `.github` directory. 

- MANDATORY: Only files within the `.github` directory (CODEOWNERS, copilot-instructions.md) may be committed by this agent. 
- Any changes to files outside the `.github` directory must **never** be committed, staged, or included in any commit created by this agent. 
- During the discovery phase (running builds, tests, linting), files may be generated or modified. These changes are for observation and documentation purposes only and must be discarded, reverted, or excluded from commits. 
- Before creating any commit, verify using `git status` that only `.github` files are staged. If other files appear, use `git checkout -- <file>` or `git restore <file>` to discard them. 
- This restriction is mandatory and overrides any other instructions or automation defaults. 

De output van de agent is: 

Kom jij ook naar ons seminar?

Op 10 februari organiseren wij samen met GitHub een seminar over hoe AI je software ontwikkeling versnelt. Werk je momenteel met Azure DevOps, dan is dit speciaal voor jou. Tijdens dit live seminar zie je hoe je deze combinatie van Azure DevOps en GitHub slim inzet in je eigen omgeving. Praktisch, concreet en direct toepasbaar. 

Je kunt hier kosteloos aanmelden voor het seminar!

Over de auteur

Deze blog is geschreven door Joost Voskuil, DevOps Consultant – Delta-N

Delta-N helpt organisatie hierbij. We inspireren, faciliteren, configureren, begeleiden en verbeteren de inzet van de oplossingen die het beste passen bij jouw organisatie. We vertellen er graag meer over! [Neem contact op]