You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md
-52Lines changed: 0 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -531,58 +531,6 @@ Whitespace between instructions is ignored, so the instructions can be written a
531
531
532
532
<!-- end of Xcode tab -->
533
533
534
-
<!-- START COPILOT CLI TAB -->
535
-
536
-
{% copilotcli %}
537
-
538
-
This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments.
539
-
540
-
## Creating custom instructions
541
-
542
-
{% data variables.product.prodname_copilot %} supports three types of repository custom instructions.
543
-
544
-
***Repository-wide custom instructions**, which apply to all requests made in the context of a repository.
545
-
546
-
These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions).
547
-
548
-
***Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path.
549
-
550
-
These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions).
551
-
552
-
If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic.
553
-
554
-
***Agent instructions** are used by AI agents.
555
-
556
-
{% data reusables.copilot.custom-instructions-agents %}
557
-
558
-
Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository.
559
-
560
-
## Creating repository-wide custom instructions
561
-
562
-
1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
563
-
564
-
Create the `.github` directory if it does not already exist.
565
-
566
-
1. Add natural language instructions to the file, in Markdown format.
567
-
568
-
Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
569
-
570
-
## Creating path-specific custom instructions
571
-
572
-
{% data reusables.copilot.custom-instructions-path %}
573
-
574
-
{% data reusables.copilot.custom-instructions-note %}
intro: 'Create repository custom instructions files that give {% data variables.product.prodname_copilot_short %} additional context on how to understand your project and how to build, test and validate its changes.'
5
+
versions:
6
+
feature: copilot
7
+
topics:
8
+
- Copilot
9
+
contentType: how-tos
10
+
---
11
+
12
+
This version of this article is for using repository custom instructions with the {% data variables.product.prodname_copilot %} CLI. Click the tabs above for instructions on using custom instructions in other environments.
13
+
14
+
## Creating custom instructions
15
+
16
+
{% data variables.product.prodname_copilot %} supports three types of repository custom instructions.
17
+
18
+
***Repository-wide custom instructions**, which apply to all requests made in the context of a repository.
19
+
20
+
These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions).
21
+
22
+
***Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path.
23
+
24
+
These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions).
25
+
26
+
If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic.
27
+
28
+
***Agent instructions** are used by AI agents.
29
+
30
+
{% data reusables.copilot.custom-instructions-agents %}
31
+
32
+
Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository.
33
+
34
+
## Creating repository-wide custom instructions
35
+
36
+
1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
37
+
38
+
Create the `.github` directory if it does not already exist.
39
+
40
+
1. Add natural language instructions to the file, in Markdown format.
41
+
42
+
Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
43
+
44
+
## Creating path-specific custom instructions
45
+
46
+
{% data reusables.copilot.custom-instructions-path %}
47
+
48
+
{% data reusables.copilot.custom-instructions-note %}
Copy file name to clipboardExpand all lines: content/copilot/how-tos/copilot-cli/install-copilot-cli.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Installing GitHub Copilot CLI
3
3
shortTitle: Install Copilot CLI
4
-
intro: 'Learn how to install {% data variables.copilot.copilot_cli_short %} so that you can use {% data variables.product.prodname_copilot_short %} directly from the command line.'
4
+
intro: Learn how to install {% data variables.copilot.copilot_cli_short %} so that you can use {% data variables.product.prodname_copilot_short %} directly from the command line.
Copy file name to clipboardExpand all lines: content/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks.md
+4-90Lines changed: 4 additions & 90 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Using hooks with GitHub Copilot agents
3
3
shortTitle: Use hooks
4
-
intro: 'Learn how to extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.'
4
+
intro: 'Extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.'
5
5
versions:
6
6
feature: copilot
7
7
topics:
@@ -11,101 +11,15 @@ category:
11
11
- Configure Copilot
12
12
---
13
13
14
-
Hooks allow you to extend and customize the behavior of {% data variables.product.prodname_copilot %} agents by executing custom shell commands at key points during agent execution. For a conceptual overview of hooks, see [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-hooks).
14
+
{% data reusables.copilot.coding-agent.hooks-intro %}
15
15
16
16
## Creating a hook in a repository on {% data variables.product.github %}
17
17
18
-
1. Create a new `hooks.json` file with the name of your choice in the `.github/hooks/` folder of your repository. The hooks configuration file **must be present** on your repository's default branch to be used by {% data variables.copilot.copilot_coding_agent %}. For {% data variables.copilot.copilot_cli %}, hooks are loaded from your current working directory.
19
-
20
-
1. In your text editor, copy and paste the following hook template. Remove any hooks you don't plan on using from the `hooks` array.
21
-
22
-
```json copy
23
-
{
24
-
"version": 1,
25
-
"hooks": {
26
-
"sessionStart": [...],
27
-
"sessionEnd": [...],
28
-
"userPromptSubmitted": [...],
29
-
"preToolUse": [...],
30
-
"postToolUse": [...],
31
-
"errorOccurred": [...]
32
-
}
33
-
}
34
-
```
35
-
36
-
1. Configure your hook syntax under the `bash` or `powershell` keys, or directly reference script files you have created.
37
-
38
-
* This example runs a script that outputs the start date of the session to a log file using the `sessionStart` hook:
* This example calls out to an external `log-prompt` script:
53
-
54
-
```json copy
55
-
"userPromptSubmitted": [
56
-
{
57
-
"type": "command",
58
-
"bash": "./scripts/log-prompt.sh",
59
-
"powershell": "./scripts/log-prompt.ps1",
60
-
"cwd": "scripts",
61
-
"env": {
62
-
"LOG_LEVEL": "INFO"
63
-
}
64
-
}
65
-
],
66
-
```
67
-
68
-
For a full reference on the input JSON from agent sessions along with sample scripts, see [AUTOTITLE](/copilot/reference/hooks-configuration).
69
-
70
-
1. Commit the file to the repository and merge it into the default branch. Your hooks will now run during agent sessions.
18
+
{% data reusables.copilot.coding-agent.create-hooks-instructions %}
71
19
72
20
## Troubleshooting
73
21
74
-
If you run into problems using hooks, use the following table to troubleshoot.
75
-
76
-
| Issue | Action |
77
-
| --- | --- |
78
-
| Hooks are not executing | <ul><li>Verify the JSON file is in the `.github/hooks/` directory.</li><li>Check for valid JSON syntax (for example, `jq . hooks.json`).</li><li>Ensure `version: 1` is specified in your `hooks.json` file.</li><li>Verify the script you are calling from your hook is executable (`chmod +x script.sh`)</li><li>Check that the script has a proper shebang (for example, `#!/bin/bash`)</li></ul> |
79
-
| Hooks are timing out | <ul><li>The default timeout is 30 seconds. Increase `timeoutSec` in the configuration if needed.</li><li>Optimize script performance by avoiding unnecessary operations.</li> |
80
-
| Invalid JSON output | <ul><li>Ensure the output is on a single line.</li><li>On Unix, use `jq -c` to compact and validate the JSON output.</li><li>On Windows, use the `ConvertTo-Json -Compress` command in PowerShell to do the same.</li></ul> |
81
-
82
-
## Debugging
83
-
84
-
You can debug hooks using the following methods:
85
-
86
-
* **Enable verbose logging** in the script to inspect the input data and trace script execution.
87
-
88
-
```shell copy
89
-
#!/bin/bash
90
-
set -x # Enable bash debug mode
91
-
INPUT=$(cat)
92
-
echo "DEBUG: Received input" >&2
93
-
echo "$INPUT" >&2
94
-
# ... rest of script
95
-
```
96
-
97
-
***Test hooks locally** by piping test input into your hook to validate its behavior:
0 commit comments