|
| 1 | +--- |
| 2 | +description: Automatically assign issues to GitHub Copilot to fix failed builds |
| 3 | +sidebar_position: 4 |
| 4 | +--- |
| 5 | +# Copilot Cloud Integration |
| 6 | + |
| 7 | +This page explains how to integrate Semaphore CI pipelines with GitHub's Copilot Agent to automatically fix build errors. |
| 8 | + |
| 9 | +:::note |
| 10 | + |
| 11 | +In this scenario, we use GitHub's Cloud version of Copilot. The Copilot AI Agent runs inside GitHub and creates a draft Pull Request with fixes. If you prefer to run a different AI agent or run the agent inside the CI itself, see [Self-Healing CI](./self-healing-ci). |
| 12 | + |
| 13 | +::: |
| 14 | + |
| 15 | +## Overview |
| 16 | + |
| 17 | +GitHub Copilot can run an AI Agent inside their infrastructure to take actions on the repository. On this page, we describe an integration method that automatically fixes build errors in the CI using Copilot Agents. |
| 18 | + |
| 19 | +The process is as follows: |
| 20 | + |
| 21 | +1. One or more of the jobs in your pipeline fails |
| 22 | +2. For each failed job, we create an issue on the repository and assign Copilot |
| 23 | +3. GitHub spins up an AI agent and creates a draft Pull Request with a fix |
| 24 | +4. You review the Pull Request and mark it as ready if it seems valid |
| 25 | +5. Marking the Pull Request valid for review starts a new CI workflow |
| 26 | +6. If the build is fixed, you can merge the Pull Request |
| 27 | + |
| 28 | +This process is repeated for every issue opened and assigned to Copilot. |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | + |
| 34 | +- A [GitHub Personal Access Token](https://github.com/settings/tokens) with write permissions on the repository and read permissions in the GitHub organization |
| 35 | +- Copilot Agents enabled in your GitHub organization (available in GitHub Copilot Pro, GitHub Copilot Pro+, GitHub Copilot Business, and GitHub Copilot Enterprise plans) |
| 36 | + |
| 37 | +## Preventing build loops |
| 38 | + |
| 39 | +To prevent WIP branches created by Copilot from creating a CI loop: |
| 40 | +- We only create issues on branches that do not start with `copilot/` |
| 41 | +- We do not run workflows on draft Pull Requests |
| 42 | + |
| 43 | +## Preparation |
| 44 | + |
| 45 | +Before you can set up the integration, we must set up a few things. |
| 46 | + |
| 47 | +### Obtain a GitHub Access Token |
| 48 | + |
| 49 | +1. Create a [Personal Access Token](https://github.com/settings/tokens) (classic) in GitHub with: |
| 50 | + |
| 51 | + - write permissions to the repository |
| 52 | + - permissions to create pull requests in the repository |
| 53 | + - read permissions in the organization |
| 54 | + |
| 55 | +  |
| 56 | + |
| 57 | +2. Create a [secret](../secrets) called `gh-cli` with the environment variable `GH_TOKEN` to store your GitHub token |
| 58 | + |
| 59 | +### Enable Copilot Agents in your GitHub Organization |
| 60 | + |
| 61 | +Copilot Agents are available on a set of paid plans. For this integration to work, this feature must be enabled. See [Managing Copilot coding agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/manage-agents) to learn how to activate the agent for your project. |
| 62 | + |
| 63 | +### Configure test reports |
| 64 | + |
| 65 | +While not entirely mandatory, it's highly recommended to [configure test reports](../tests/test-reports) to obtain a standardized error report that the AI Agent can use to diagnose and fix build errors. |
| 66 | + |
| 67 | +For the remainder of the tutorial, we'll assume that all tests in the CI create a file called `results.xml` containing the test results. |
| 68 | + |
| 69 | +## Set up Copilot Integration |
| 70 | + |
| 71 | +To set up the integration, follow these steps. |
| 72 | + |
| 73 | +<Steps> |
| 74 | + |
| 75 | +1. Disable draft Pull Requests on Semaphore: open your [project settings] and ensure **Build drafts on Pull Requests** is set to "No" |
| 76 | + |
| 77 | +  |
| 78 | + |
| 79 | +2. Create a prompt template file called `prompt-template.txt`. Use this example as a starting point: |
| 80 | + |
| 81 | + ```text title="Prompt template for Copilot" |
| 82 | + Read the following JUnit test report, diagnose the failure, and create a Pull Request with the fix. Validat |
| 83 | + e the fix before creating the Pull Request. |
| 84 | + ``` |
| 85 | +
|
| 86 | +3. Push the prompt template file to the repository on GitHub |
| 87 | +
|
| 88 | +4. Open the workflow editor for your project in Semaphore. Locate a block that contains tests that might fail. |
| 89 | +
|
| 90 | +5. Enable the `gh-cli` secret in the blog |
| 91 | +
|
| 92 | +6. Open the **Epilogue** and add the following commands in the **If job has failed** command box |
| 93 | +
|
| 94 | + ```shell title="Commands to create a GitHub Issue for Copilot" |
| 95 | + cp prompt-template.txt prompt-issue.txt |
| 96 | + echo '```xml' >> prompt-issue.txt |
| 97 | + cat results.xml >> prompt-issue.txt |
| 98 | + echo -e '\n```' >> prompt-ussue.txt |
| 99 | + [[ ! "$SEMAPHORE_GIT_WORKING_BRANCH" =~ ^copilot/ ]] && gh issue create --assignee "@copilot" --title "Fix failed job: ${SEMAPHORE_JOB_NAME}" -F prompt-issue.txt |
| 100 | + ``` |
| 101 | +
|
| 102 | +  |
| 103 | +
|
| 104 | +7. Repeat steps 4 to 6 for every block with jobs or tests in your pipeline that you wish for Copilot to diagnose and fix |
| 105 | +
|
| 106 | +8. Save your changes |
| 107 | +
|
| 108 | +</Steps> |
| 109 | +
|
| 110 | +## How to follow Copilot activity |
| 111 | +
|
| 112 | +With the integration set up, a new issue should be created every time a job or test fails in your pipeline. |
| 113 | +
|
| 114 | +You can follow the Copilot activity in the following places: |
| 115 | +
|
| 116 | +- [GitHub Copilot Agent dashboard](https://github.com/copilot/agents) |
| 117 | +- Your GitHub issues page |
| 118 | +- Your GitHub pull request page |
| 119 | +
|
| 120 | +While Copilot is working, you may see a draft Pull Request with the title containing "[WIP]". This means that Copilot is still working. |
| 121 | +
|
| 122 | +Wait until "[WIP]" disappears from the Pull Request title before marking it as ready for review. Once you mark it ready for review, a new workflow should automatically start in Semaphore. If the build is fixed, you can merge the Pull Request. |
| 123 | +
|
| 124 | +## See also |
| 125 | +
|
| 126 | +- [MCP Server](./mcp-server) |
| 127 | +- [MCP Usage Examples](./mcp-usage-examples) |
| 128 | +- [Self-healing CI](./self-healing-ci) |
| 129 | +
|
0 commit comments