Skip to content

Commit dc7cee3

Browse files
Copilotfiftin
Copilot
and
fiftin
authored
Add comprehensive GitHub Copilot instructions for Semaphore UI development (#3251)
* Initial plan * Create comprehensive GitHub Copilot instructions for Semaphore UI development Co-authored-by: fiftin <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: fiftin <[email protected]>
1 parent 1852fc6 commit dc7cee3

File tree

1 file changed

+156
-0
lines changed

1 file changed

+156
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Semaphore UI Development Instructions
2+
3+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
4+
5+
Semaphore UI is a modern web interface for managing popular DevOps tools like Ansible, Terraform, PowerShell, and Bash scripts. It's built with Go (backend) and Vue.js (frontend), using Task runner for build automation.
6+
7+
## Working Effectively
8+
9+
### Bootstrap, build, and test the repository:
10+
- Install Go 1.21+ (currently requires go version 1.21 or higher)
11+
- Install Node.js 16+
12+
- Install Task runner: `go install github.com/go-task/task/v3/cmd/task@latest`
13+
- Install dependencies: `task deps` -- takes 3 minutes first time (faster with cache). NEVER CANCEL. Set timeout to 5+ minutes.
14+
- Build the application: `task build` -- takes 1.5 minutes. NEVER CANCEL. Set timeout to 3+ minutes.
15+
- Run tests: `task test` -- takes 33 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
16+
17+
### Run the application:
18+
- ALWAYS run the bootstrapping steps first
19+
- Setup database and admin user: `./bin/semaphore setup` (interactive, use BoltDB option 2 for development)
20+
- Start server: `./bin/semaphore server --config ./config.json`
21+
- Web UI: http://localhost:3000 (login: admin / changeme)
22+
- API: http://localhost:3000/api/ (test with: `curl http://localhost:3000/api/ping`)
23+
24+
## Validation
25+
26+
- **CRITICAL**: Always manually validate any new code by building and running the application.
27+
- ALWAYS run through at least one complete end-to-end scenario after making changes:
28+
1. Build the application: `task build`
29+
2. Start the server: `./bin/semaphore server --config ./config.json`
30+
3. Test API endpoint: `curl http://localhost:3000/api/ping` (should return "pong")
31+
4. Access web UI at http://localhost:3000 and verify it loads
32+
5. For auth changes: Test login with admin/changeme
33+
- For significant changes, run full setup process to ensure setup still works
34+
- Always build and exercise your changes before considering the task complete
35+
36+
### Complete Validation Scenario (for major changes):
37+
```bash
38+
# 1. Clean build
39+
task build
40+
41+
# 2. Setup database (if config.json doesn't exist)
42+
./bin/semaphore setup # Choose option 2 (BoltDB), use admin/changeme
43+
44+
# 3. Start server
45+
./bin/semaphore server --config ./config.json
46+
47+
# 4. Test in another terminal
48+
curl http://localhost:3000/api/ping # Should return "pong"
49+
curl -I http://localhost:3000/ # Should return HTTP 200
50+
51+
# 5. Test web interface manually in browser at http://localhost:3000
52+
# 6. Test login with admin/changeme if auth-related changes
53+
```
54+
55+
### Linting and Code Quality
56+
57+
- Frontend linting: `cd web && npm run lint` (has known warnings about console statements and asset sizes - ignore existing issues)
58+
- Backend linting: `golangci-lint run --timeout=3m` (has known type errors due to module import issues - ignore existing issues)
59+
- **DO NOT** try to fix existing linting issues unless specifically asked to
60+
- Always run linting on new code you add to ensure it follows project standards
61+
- Install golangci-lint if needed: `go install github.com/golangci/golangci-lint/cmd/[email protected]`
62+
63+
## Common Tasks
64+
65+
### Repository Structure
66+
```
67+
.
68+
├── README.md - Project documentation
69+
├── CONTRIBUTING.md - Development guidelines
70+
├── Taskfile.yml - Task runner configuration
71+
├── go.mod - Go module dependencies
72+
├── web/ - Vue.js frontend application
73+
│ ├── package.json - Frontend dependencies
74+
│ ├── src/ - Vue.js source code
75+
│ └── public/ - Static assets
76+
├── cli/ - Go CLI application entry point
77+
├── api/ - Go API server endpoints
78+
├── db/ - Database models and interfaces
79+
├── services/ - Business logic services
80+
├── util/ - Utility functions and configuration
81+
├── bin/ - Built binaries (after build)
82+
└── config.json - Runtime configuration (after setup)
83+
```
84+
85+
### Key Commands Reference
86+
```bash
87+
# Install task runner
88+
go install github.com/go-task/task/v3/cmd/task@latest
89+
90+
# Install all dependencies (backend + frontend + tools)
91+
task deps
92+
93+
# Build application (frontend + backend)
94+
task build
95+
96+
# Run tests
97+
task test
98+
99+
# Run linting
100+
task lint
101+
102+
# Setup application (interactive)
103+
./bin/semaphore setup
104+
105+
# Start server
106+
./bin/semaphore server --config ./config.json
107+
108+
# View available task commands
109+
task --list
110+
```
111+
112+
### Database Options for Development
113+
During setup, choose option 2 (BoltDB) for simplest development setup:
114+
- No external database required
115+
- Database file stored as `database.boltdb` in project root
116+
- Perfect for development and testing
117+
118+
### Frontend Development
119+
- Vue.js 2.x application in `web/` directory
120+
- Built with Vue CLI and Vuetify components
121+
- Build output goes to `api/public/` for serving by Go backend
122+
- Development server not typically used - Go server serves built assets
123+
124+
### Backend Development
125+
- Go application with CLI and API server
126+
- Uses Gorilla Mux for routing
127+
- Supports multiple databases: MySQL, PostgreSQL, SQLite, BoltDB
128+
- Configuration via JSON file or environment variables
129+
130+
## Troubleshooting
131+
132+
### Build Issues
133+
- If `task` command not found: Install with `go install github.com/go-task/task/v3/cmd/task@latest`
134+
- If Go version errors: Ensure Go 1.21+ is installed
135+
- If npm install fails: Ensure Node.js 16+ is installed
136+
- If build takes too long: This is normal - frontend build can take 60+ seconds
137+
138+
### Runtime Issues
139+
- If server won't start: Check config.json exists and database is accessible
140+
- If web UI shows errors: Check that frontend build completed successfully in `api/public/`
141+
- If API returns errors: Check server logs for specific error messages
142+
143+
### Database Issues
144+
- For development, always use BoltDB (option 2) during setup
145+
- Database file will be created automatically
146+
- If database errors occur, delete `database.boltdb` and run setup again
147+
148+
## Important Notes
149+
150+
- **NEVER CANCEL** long-running builds or dependency installations
151+
- Set appropriate timeouts: deps (5+ min), build (3+ min), tests (2+ min)
152+
- The application serves the frontend from the Go backend - no separate frontend server needed
153+
- Configuration is stored in `config.json` after running setup
154+
- Default admin credentials after setup: admin / changeme
155+
- Linting has known issues - focus on not introducing new ones
156+
- Always test changes by running the full application, not just unit tests

0 commit comments

Comments
 (0)