Skip to content

Commit d8d5c34

Browse files
Copilotcrenshaw-dev
Copilot
and
crenshaw-dev
authored
✨ Add Copilot instructions for repository (#579)
* Initial plan * Add comprehensive Copilot instructions for the repository Co-authored-by: crenshaw-dev <[email protected]> * Address review feedback: update CRD list, remove file headers, fix naming conventions Co-authored-by: crenshaw-dev <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: crenshaw-dev <[email protected]>
1 parent 4a47308 commit d8d5c34

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# GitOps Promoter - GitHub Copilot Instructions
2+
3+
## Project Overview
4+
5+
GitOps Promoter is a Kubernetes operator that facilitates environment promotion for config managed via GitOps. It provides a drift-free promotion process with a robust gating system, complete integration with git and SCM tooling.
6+
7+
### Key Technologies
8+
- **Backend**: Go 1.24+ (Kubernetes operator using controller-runtime)
9+
- **Frontend**: TypeScript/React (Dashboard UI and Argo CD extension)
10+
- **Infrastructure**: Kubernetes, Argo CD integration
11+
- **SCM Support**: GitHub, GitHub Enterprise, GitLab, Forgejo (including Codeberg)
12+
13+
## Architecture
14+
15+
The project follows a standard Kubernetes operator pattern with:
16+
- Custom Resource Definitions (CRDs) in `api/v1alpha1/`
17+
- Controllers in `internal/controller/`
18+
- SCM integrations in `internal/scms/`
19+
- Webhook receiver for SCM events in `internal/webhookreceiver/`
20+
- Dashboard UI in `ui/dashboard/`
21+
- Argo CD extension in `ui/extension/`
22+
- Shared UI components in `ui/components-lib/`
23+
24+
## Development Setup
25+
26+
### Prerequisites
27+
- Go 1.24+
28+
- Node.js (for UI development)
29+
- kubectl
30+
- Docker or compatible container tool
31+
- Kind (for local testing)
32+
33+
### Build Commands
34+
```bash
35+
# Go backend
36+
make build # Build manager binary
37+
make build-all # Build UI components and manager binary
38+
make test # Run tests
39+
make test-parallel # Run tests in parallel
40+
make lint # Run linters
41+
make lint-fix # Run linters with auto-fix
42+
43+
# UI development
44+
make build-dashboard # Build dashboard UI
45+
make build-extension # Build Argo CD extension
46+
make lint-dashboard # Lint dashboard
47+
make lint-extension # Lint extension
48+
make lint-ui # Lint all UI components
49+
50+
# Running locally
51+
make run # Run controller locally
52+
make run-dashboard # Run dashboard locally
53+
```
54+
55+
## Code Style and Standards
56+
57+
### Go Code
58+
- Use `go fmt` for formatting
59+
- Follow golangci-lint rules (see `.golangci.yml`)
60+
- Use Ginkgo/Gomega for testing
61+
- Tests should use table-driven tests where appropriate
62+
- Use controller-runtime patterns for Kubernetes interactions
63+
- Avoid naked returns and follow error wrapping conventions
64+
65+
### TypeScript/React Code
66+
- Use TypeScript for all new code
67+
- Follow ESLint rules
68+
- Run type-checking with `tsc --noEmit`
69+
- Use functional components with hooks
70+
71+
72+
73+
## Directory Structure
74+
75+
### Key Directories
76+
- `api/v1alpha1/` - Kubernetes CRD types (PromotionStrategy, GitRepository, ScmProvider, etc.)
77+
- `internal/controller/` - Kubernetes controllers
78+
- `internal/scms/` - SCM provider implementations (GitHub, GitLab, Forgejo)
79+
- `internal/git/` - Git operations
80+
- `internal/utils/` - Shared utilities
81+
- `internal/webhookreceiver/` - Webhook handling for SCM events
82+
- `internal/webserver/` - Dashboard web server
83+
- `config/` - Kubernetes manifests and Kustomize configurations
84+
- `docs/` - Documentation (MkDocs format)
85+
- `hack/` - Development scripts
86+
- `test/` - Test fixtures and e2e tests
87+
- `ui/` - Frontend code
88+
89+
### Generated Files
90+
These files are auto-generated and should not be edited manually:
91+
- `api/v1alpha1/zz_generated.deepcopy.go`
92+
- `config/crd/bases/*.yaml`
93+
- Files in `dist/`
94+
95+
## Testing Guidelines
96+
97+
### Unit Tests
98+
- Use Ginkgo/Gomega for Go tests
99+
- Test files should be named `*_test.go`
100+
- Use `Context` and `It` blocks for test organization
101+
- Mock external dependencies
102+
- Use `envtest` for controller testing
103+
104+
### Running Tests
105+
```bash
106+
make test # Run all tests
107+
make test-parallel # Run tests in parallel (faster)
108+
make test-e2e # Run end-to-end tests
109+
```
110+
111+
### Test Patterns
112+
- Use table-driven tests for multiple similar test cases
113+
- Test both success and error paths
114+
- Use `Eventually` for async operations in controller tests
115+
- Clean up resources in `AfterEach` blocks
116+
117+
## Custom Resources
118+
119+
### Core CRDs
120+
1. **PromotionStrategy** - Defines promotion flow between environments
121+
2. **GitRepository** - Represents a Git repository
122+
3. **ScmProvider** - SCM provider configuration (GitHub, GitLab, Forgejo)
123+
4. **ClusterScmProvider** - Cluster-scoped SCM provider configuration
124+
5. **PullRequest** - Represents a promotion pull request
125+
6. **CommitStatus** - Commit status tracking
126+
7. **ArgoCDCommitStatus** - Argo CD-specific commit status
127+
8. **ChangeTransferPolicy** - Controls how changes are transferred between branches
128+
9. **RevertCommit** - Represents a revert operation
129+
10. **ControllerConfiguration** - Configuration for the GitOps Promoter controller
130+
131+
### Resource Relationships
132+
- PromotionStrategy references GitRepository
133+
- GitRepository references ScmProvider or ClusterScmProvider
134+
- ScmProvider references a Secret for credentials
135+
- ArgoCDCommitStatus references PromotionStrategy
136+
137+
## Common Patterns
138+
139+
### Controller Patterns
140+
- Use structured logging with `logr`
141+
- Return `ctrl.Result{RequeueAfter: duration}` for retries
142+
- Use conditions to track resource status
143+
- Handle resource not found errors gracefully
144+
- Use finalizers for cleanup operations
145+
146+
### Git Operations
147+
- All git operations are in `internal/git/`
148+
- Use bare repositories for efficiency
149+
- Handle authentication via SCM provider
150+
151+
### SCM Integration
152+
- SCM providers implement interfaces in `internal/scms/`
153+
- Support for GitHub Apps, GitLab tokens, Forgejo tokens
154+
- Webhook support for real-time updates
155+
156+
## Environment Variables and Configuration
157+
158+
Key environment variables:
159+
- `KUBEBUILDER_ASSETS` - Path to test binaries (for tests)
160+
- Image configuration via Makefile variables
161+
162+
## Documentation
163+
164+
- Documentation is in `docs/` using MkDocs
165+
- Update `docs/getting-started.md` for setup changes
166+
- Update `docs/architecture.md` for architectural changes
167+
- Keep version numbers in sync using `hack/bump-docs-manifests.sh`
168+
- When adding a new documentation page, update `mkdocs.yml` to include it in the table of contents
169+
170+
## Best Practices
171+
172+
1. **Minimal Changes**: Make the smallest possible changes to achieve the goal
173+
2. **Test First**: Write tests before implementing features
174+
3. **Error Handling**: Always handle errors explicitly, don't ignore them
175+
4. **Logging**: Use structured logging with appropriate levels
176+
5. **Dependencies**: Avoid adding new dependencies unless necessary
177+
6. **Documentation**: Update docs when changing behavior or APIs
178+
7. **Backwards Compatibility**: While in v1alpha1, breaking changes are allowed but should be avoided if possible
179+
180+
## Common Tasks
181+
182+
### Adding a New CRD Field
183+
1. Update type definition in `api/v1alpha1/`
184+
2. Add proper Kubernetes validation:
185+
- For required strings, set a min length of at least 1
186+
- Set a max length if it makes sense for the field
187+
- Use regex validation for character restrictions
188+
- Use metav1 types for time and duration fields instead of custom types
189+
- For numbers where negative values don't make sense, enforce a minimum of zero
190+
3. Update example files in `internal/controller/testdata/` for both spec and status changes
191+
4. Run `make build-installer` to regenerate CRDs, DeepCopy methods, and install manifests
192+
5. Update controller logic
193+
6. Add tests
194+
7. Update documentation
195+
196+
### Adding a Field to ControllerConfiguration
197+
1. Update type definition in `api/v1alpha1/controllerconfiguration_types.go`
198+
2. Set a default value in the code
199+
3. Explicitly add the default value to `config/config/controllerconfiguration.yaml`
200+
4. For this CR, defaults live in manifests and not in code whenever possible
201+
5. Follow the same validation and testing steps as adding a CRD field
202+
203+
### Building Container Images
204+
```bash
205+
make docker-build
206+
# Note: docker-push should only be used for releases, not automation
207+
```
208+
209+
## Troubleshooting
210+
211+
### Common Issues
212+
- If tests fail with "unable to find kubebuilder assets", run `make setup-envtest`
213+
- If CRDs are out of sync, run `make manifests`
214+
- If deepcopy methods are missing, run `make generate`
215+
- If UI builds fail, check Node.js version and run `npm install` in the UI directory
216+
217+
## Additional Resources
218+
219+
- Main documentation: https://gitops-promoter.readthedocs.io/
220+
- Project repository: https://github.com/argoproj-labs/gitops-promoter
221+
- Related video: "Space Age GitOps: The Rise of the Humble Pull Request"

0 commit comments

Comments
 (0)