Skip to content

Commit aaf077f

Browse files
CopilotJamesIves
Copilot
and
JamesIves
authored
Add comprehensive GitHub Copilot instructions for development workflow (#1894)
* Initial plan * Fix ESLint configuration to ignore lib directory Co-authored-by: JamesIves <[email protected]> * Add comprehensive GitHub Copilot instructions Co-authored-by: JamesIves <[email protected]> * Remove hardcoded Node.js version references Co-authored-by: JamesIves <[email protected]> * Add project description to copilot instructions Co-authored-by: JamesIves <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: JamesIves <[email protected]>
1 parent 9734251 commit aaf077f

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# GitHub Pages Deploy Action
2+
3+
This is a GitHub Action that automatically deploys your project to GitHub Pages with GitHub Actions. The action can be configured to push your production-ready code into any branch you'd like, including `gh-pages` and `docs`. It supports cross-repository deployments, works with GitHub Enterprise, and provides multiple authentication methods including SSH keys and personal access tokens.
4+
5+
Always follow these instructions first and only fallback to additional search and context gathering if the information in these instructions is incomplete or found to be in error.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and build the repository:
10+
11+
- Use Node.js version from `.node-version` file
12+
- Install Yarn globally: `npm install -g yarn`
13+
- Install dependencies: `yarn install --frozen-lockfile` -- takes 1-25 seconds depending on cache state
14+
- Build the project: `yarn build` -- takes 9 seconds. NEVER CANCEL. Set timeout to 30+ seconds
15+
- Run tests: `yarn test` -- takes 8 seconds. NEVER CANCEL. Set timeout to 30+ seconds
16+
- Check linting: `yarn lint:check` -- takes 3 seconds. Set timeout to 15+ seconds
17+
- Check formatting: `yarn lint:format:check` -- takes 2 seconds. Set timeout to 10+ seconds
18+
19+
### Development workflow:
20+
21+
- ALWAYS run the bootstrapping steps first (install dependencies and build)
22+
- Make code changes in the `src/` directory (TypeScript source)
23+
- Build with `yarn build` to compile TypeScript to JavaScript in `lib/` directory
24+
- Run `yarn test` to ensure tests pass
25+
- Run `yarn lint:check` and `yarn lint:format:check` before committing
26+
27+
### Fix linting and formatting issues:
28+
29+
- Auto-fix linting: `yarn lint`
30+
- Auto-format code: `yarn lint:format`
31+
32+
## Validation
33+
34+
### CRITICAL - Required validation steps:
35+
36+
- ALWAYS run `yarn build` after making changes - the action depends on compiled JavaScript in `lib/`
37+
- ALWAYS run `yarn test` to ensure all unit tests pass
38+
- ALWAYS run `yarn lint:check` and `yarn lint:format:check` or the CI will fail
39+
- **NEVER CANCEL** any build or test commands - they complete quickly (under 30 seconds each)
40+
41+
### Manual testing scenarios:
42+
43+
Since this is a GitHub Action, full end-to-end testing requires deploying to a test repository. However, you can validate:
44+
45+
- Unit tests cover core functionality: `yarn test` runs 59 tests with 92%+ coverage
46+
- Integration tests exist in `.github/workflows/integration.yml` but require GitHub Actions environment
47+
- Build output in `lib/` directory should match TypeScript source in `src/`
48+
49+
### Before submitting changes:
50+
51+
- Ensure all TypeScript compiles without errors: `yarn build`
52+
- Ensure all tests pass: `yarn test`
53+
- Ensure code follows style guidelines: `yarn lint:check` and `yarn lint:format:check`
54+
- The `lib/` directory must be committed for distribution branches (not for pull requests to `dev`)
55+
56+
## Common Tasks
57+
58+
### Repository structure:
59+
60+
```
61+
src/ # TypeScript source files
62+
├── main.ts # Entry point for GitHub Action
63+
├── lib.ts # Main run function (can be used as module)
64+
├── constants.ts # Configuration interfaces and constants
65+
├── git.ts # Git operations for deployment
66+
├── util.ts # Utility functions
67+
├── ssh.ts # SSH key configuration
68+
├── execute.ts # Command execution wrapper
69+
└── worktree.ts # Git worktree operations
70+
71+
__tests__/ # Jest test files
72+
lib/ # Compiled JavaScript (generated, do not edit)
73+
integration/ # Sample files for testing deployments
74+
.github/workflows/ # CI/CD workflows
75+
```
76+
77+
### Key files and their purposes:
78+
79+
- `action.yml` - GitHub Action definition with inputs/outputs
80+
- `package.json` - Dependencies and npm scripts
81+
- `tsconfig.json` - TypeScript compilation settings
82+
- `jest.config.js` - Test configuration
83+
- `eslint.config.mjs` - Linting rules (ignores `lib/` directory)
84+
- `.node-version` - Required Node.js version
85+
86+
### Understanding the codebase:
87+
88+
- **Entry Point**: `src/main.ts` imports and calls the `run()` function from `src/lib.ts`
89+
- **Core Logic**: `src/lib.ts` contains the main deployment logic
90+
- **Git Operations**: `src/git.ts` handles repository initialization and deployment
91+
- **Configuration**: `src/constants.ts` defines interfaces for action parameters
92+
- **Testing**: Comprehensive Jest tests in `__tests__/` directory with mocks for GitHub Actions
93+
94+
### Common development patterns:
95+
96+
- Action parameters are defined in `src/constants.ts` interfaces
97+
- Error handling uses try/catch with `extractErrorMessage()` utility
98+
- All git commands go through `execute()` wrapper for consistent logging
99+
- SSH and token authentication are handled in separate modules
100+
- Extensive parameter validation in `src/util.ts`
101+
102+
### CI/CD behavior:
103+
104+
- `.github/workflows/build.yml` runs on every push and PR
105+
- Linting, formatting, tests, and build must all pass
106+
- Integration tests deploy to test repositories using various authentication methods
107+
- Production releases include `node_modules` in distribution branches
108+
109+
### Debugging and troubleshooting:
110+
111+
- Check TypeScript compilation errors first: `yarn build`
112+
- Run specific test files: `yarn test <filename>`
113+
- Use `yarn lint` to auto-fix linting issues
114+
- The action supports debug mode via GitHub Actions debug logging
115+
- Integration tests in CI provide real deployment validation
116+
117+
### Important notes:
118+
119+
- The `lib/` directory is compiled output and should not be manually edited
120+
- Distribution branches (like `v4`) include `node_modules` and `lib/` for GitHub Actions runtime
121+
- The dev branch excludes `node_modules` and `lib/` from version control
122+
- SSH key support allows deployment with repository deploy keys
123+
- Cross-repository deployment is supported with proper token permissions
124+
125+
### Environment requirements:
126+
127+
- Node.js (specified in `.node-version`)
128+
- Yarn package manager
129+
- Git (for deployment operations)
130+
- rsync (for file operations, automatically available in GitHub Actions runners)
131+
132+
### Performance expectations:
133+
134+
- Fresh install: ~25 seconds for `yarn install --frozen-lockfile`
135+
- Cached install: ~1 second for `yarn install --frozen-lockfile`
136+
- Build: ~9 seconds for `yarn build`
137+
- Tests: ~8 seconds for `yarn test`
138+
- Linting: ~3 seconds for `yarn lint:check`
139+
- Formatting: ~2 seconds for `yarn lint:format:check`

‎eslint.config.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ import eslintConfigPrettier from 'eslint-config-prettier'
44
import jest from 'eslint-plugin-jest'
55

66
export default tseslint.config(
7+
{
8+
ignores: ['lib/**']
9+
},
710
eslintConfigPrettier,
811
jest.configs['flat/recommended'],
912
eslint.configs.recommended,

0 commit comments

Comments
 (0)