Copilot instructions

1---
2applyTo:
3  - ".pipelines/**/*.yml"
4  - ".pipelines/**/*.yaml"
5---
6 
7# OneBranch Signing Configuration
8 
9This guide explains how to configure OneBranch signing variables in Azure Pipeline jobs, particularly when signing is not required.
10 
11## Purpose
12 
13OneBranch pipelines include signing infrastructure by default. For build-only jobs where signing happens in a separate stage, you should disable signing setup to improve performance and avoid unnecessary overhead.
14 
15## Disable Signing for Build-Only Jobs
16 
17When a job does not perform signing (e.g., it only builds artifacts that will be signed in a later stage), disable both signing setup and code sign validation:
18 
19```yaml
20variables:
21  - name: ob_signing_setup_enabled
22    value: false  # Disable signing setup - this is a build-only stage
23  - name: ob_sdl_codeSignValidation_enabled
24    value: false  # Skip signing validation in build-only stage
25```
26 
27### Why Disable These Variables?
28 
29**`ob_signing_setup_enabled: false`**
30- Prevents OneBranch from setting up the signing infrastructure
31- Reduces job startup time
32- Avoids unnecessary credential validation
33- Only disable when the job will NOT sign any artifacts
34 
35**`ob_sdl_codeSignValidation_enabled: false`**
36- Skips validation that checks if files are properly signed
37- Appropriate for build stages where artifacts are unsigned
38- Must be enabled in signing/release stages to validate signatures
39 
40## Common Patterns
41 
42### Build-Only Job (No Signing)
43 
44```yaml
45jobs:
46- job: build_artifacts
47  variables:
48    - name: ob_signing_setup_enabled
49      value: false
50    - name: ob_sdl_codeSignValidation_enabled
51      value: false
52  steps:
53    - checkout: self
54    - pwsh: |
55        # Build unsigned artifacts
56        Start-PSBuild
57```
58 
59### Signing Job
60 
61```yaml
62jobs:
63- job: sign_artifacts
64  variables:
65    - name: ob_signing_setup_enabled
66      value: true
67    - name: ob_sdl_codeSignValidation_enabled
68      value: true
69  steps:
70    - checkout: self
71      env:
72        ob_restore_phase: true  # Steps before first signing operation
73    - pwsh: |
74        # Prepare artifacts for signing
75      env:
76        ob_restore_phase: true  # Steps before first signing operation
77    - task: onebranch.pipeline.signing@1
78      displayName: 'Sign artifacts'
79      # Signing step runs in build phase (no ob_restore_phase)
80    - pwsh: |
81        # Post-signing validation
82      # Post-signing steps run in build phase (no ob_restore_phase)
83```
84 
85## Restore Phase Usage with Signing
86 
87**The restore phase (`ob_restore_phase: true`) should only be used in jobs that perform signing operations.** It separates preparation steps from the actual signing and build steps.
88 
89### When to Use Restore Phase
90 
91Use `ob_restore_phase: true` **only** in jobs where `ob_signing_setup_enabled: true`:
92 
93```yaml
94jobs:
95- job: sign_artifacts
96  variables:
97    - name: ob_signing_setup_enabled
98      value: true  # Signing enabled
99  steps:
100    # Steps BEFORE first signing operation: use restore phase
101    - checkout: self
102      env:
103        ob_restore_phase: true
104    - template: prepare-for-signing.yml
105      parameters:
106        ob_restore_phase: true
107 
108    # SIGNING STEP: runs in build phase (no ob_restore_phase)
109    - task: onebranch.pipeline.signing@1
110      displayName: 'Sign artifacts'
111 
112    # Steps AFTER signing: run in build phase (no ob_restore_phase)
113    - pwsh: |
114        # Validation or packaging
115```
116 
117### When NOT to Use Restore Phase
118 
119**Do not use restore phase in build-only jobs** where `ob_signing_setup_enabled: false`:
120 
121```yaml
122jobs:
123- job: build_artifacts
124  variables:
125    - name: ob_signing_setup_enabled
126      value: false  # No signing
127    - name: ob_sdl_codeSignValidation_enabled
128      value: false
129  steps:
130    - checkout: self
131      # NO ob_restore_phase - not needed without signing
132    - pwsh: |
133        Start-PSBuild
134```
135 
136**Why?** The restore phase is part of OneBranch's signing infrastructure. Using it without signing enabled adds unnecessary overhead without benefit.
137 
138## Related Variables
139 
140Other OneBranch signing-related variables:
141 
142- `ob_sdl_binskim_enabled`: Controls BinSkim security analysis (can be false in build-only, true in signing stages)
143 
144## Best Practices
145 
1461. **Separate build and signing stages**: Build artifacts in one job, sign in another
1472. **Disable signing in build stages**: Improves performance and clarifies intent
1483. **Only use restore phase with signing**: The restore phase should only be used in jobs where signing is enabled (`ob_signing_setup_enabled: true`)
1494. **Restore phase before first signing step**: All steps before the first signing operation should use `ob_restore_phase: true`
1505. **Always validate after signing**: Enable validation in signing stages to catch issues
1516. **Document the reason**: Add comments explaining why signing is disabled or why restore phase is used
152 
153## Example: Split Build and Sign Pipeline
154 
155```yaml
156stages:
157  - stage: Build
158    jobs:
159    - job: build_windows
160      variables:
161        - name: ob_signing_setup_enabled
162          value: false  # Build-only, no signing
163        - name: ob_sdl_codeSignValidation_enabled
164          value: false  # Artifacts are unsigned
165      steps:
166        - template: templates/build-unsigned.yml
167
168  - stage: Sign
169    dependsOn: Build
170    jobs:
171    - job: sign_windows
172      variables:
173        - name: ob_signing_setup_enabled
174          value: true   # Enable signing infrastructure
175        - name: ob_sdl_codeSignValidation_enabled
176          value: true   # Validate signatures
177      steps:
178        - template: templates/sign-artifacts.yml
179```
180 
181## Troubleshooting
182 
183**Job fails with signing-related errors but signing is disabled:**
184- Verify `ob_signing_setup_enabled: false` is set in variables
185- Check that no template is overriding the setting
186- Ensure `ob_sdl_codeSignValidation_enabled: false` is also set
187 
188**Signed artifacts fail validation:**
189- Confirm `ob_sdl_codeSignValidation_enabled: true` in signing job
190- Verify signing actually occurred
191- Check certificate configuration
192 
193## Reference
194 
195- PowerShell signing templates: `.pipelines/templates/packaging/windows/sign.yml`
196