From 8185b4de63beeca46d1d71bbf5e90a90793609bf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 11 Sep 2025 15:38:47 +0000 Subject: [PATCH 1/5] Initial plan From 9630c317aa1e5446bd3d8dd726a684bf54226aac Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 11 Sep 2025 15:45:10 +0000 Subject: [PATCH 2/5] Fix ESLint configuration to ignore lib directory Co-authored-by: JamesIves <10888441+JamesIves@users.noreply.github.com> --- eslint.config.mjs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/eslint.config.mjs b/eslint.config.mjs index 33301eb0e..68676fd7b 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -4,6 +4,9 @@ import eslintConfigPrettier from 'eslint-config-prettier' import jest from 'eslint-plugin-jest' export default tseslint.config( + { + ignores: ['lib/**'] + }, eslintConfigPrettier, jest.configs['flat/recommended'], eslint.configs.recommended, From c748d04454f6a37c4451c5d38d984610e369bd7e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 11 Sep 2025 15:49:33 +0000 Subject: [PATCH 3/5] Add comprehensive GitHub Copilot instructions Co-authored-by: JamesIves <10888441+JamesIves@users.noreply.github.com> --- .github/copilot-instructions.md | 137 ++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..225ff59fd --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,137 @@ +# GitHub Pages Deploy Action + +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. + +## Working Effectively + +### Bootstrap and build the repository: + +- Use Node.js version from `.node-version` file: `v22.11.0` +- Install Yarn globally: `npm install -g yarn` +- Install dependencies: `yarn install --frozen-lockfile` -- takes 1-25 seconds depending on cache state +- Build the project: `yarn build` -- takes 9 seconds. NEVER CANCEL. Set timeout to 30+ seconds +- Run tests: `yarn test` -- takes 8 seconds. NEVER CANCEL. Set timeout to 30+ seconds +- Check linting: `yarn lint:check` -- takes 3 seconds. Set timeout to 15+ seconds +- Check formatting: `yarn lint:format:check` -- takes 2 seconds. Set timeout to 10+ seconds + +### Development workflow: + +- ALWAYS run the bootstrapping steps first (install dependencies and build) +- Make code changes in the `src/` directory (TypeScript source) +- Build with `yarn build` to compile TypeScript to JavaScript in `lib/` directory +- Run `yarn test` to ensure tests pass +- Run `yarn lint:check` and `yarn lint:format:check` before committing + +### Fix linting and formatting issues: + +- Auto-fix linting: `yarn lint` +- Auto-format code: `yarn lint:format` + +## Validation + +### CRITICAL - Required validation steps: + +- ALWAYS run `yarn build` after making changes - the action depends on compiled JavaScript in `lib/` +- ALWAYS run `yarn test` to ensure all unit tests pass +- ALWAYS run `yarn lint:check` and `yarn lint:format:check` or the CI will fail +- **NEVER CANCEL** any build or test commands - they complete quickly (under 30 seconds each) + +### Manual testing scenarios: + +Since this is a GitHub Action, full end-to-end testing requires deploying to a test repository. However, you can validate: + +- Unit tests cover core functionality: `yarn test` runs 59 tests with 92%+ coverage +- Integration tests exist in `.github/workflows/integration.yml` but require GitHub Actions environment +- Build output in `lib/` directory should match TypeScript source in `src/` + +### Before submitting changes: + +- Ensure all TypeScript compiles without errors: `yarn build` +- Ensure all tests pass: `yarn test` +- Ensure code follows style guidelines: `yarn lint:check` and `yarn lint:format:check` +- The `lib/` directory must be committed for distribution branches (not for pull requests to `dev`) + +## Common Tasks + +### Repository structure: + +``` +src/ # TypeScript source files +├── main.ts # Entry point for GitHub Action +├── lib.ts # Main run function (can be used as module) +├── constants.ts # Configuration interfaces and constants +├── git.ts # Git operations for deployment +├── util.ts # Utility functions +├── ssh.ts # SSH key configuration +├── execute.ts # Command execution wrapper +└── worktree.ts # Git worktree operations + +__tests__/ # Jest test files +lib/ # Compiled JavaScript (generated, do not edit) +integration/ # Sample files for testing deployments +.github/workflows/ # CI/CD workflows +``` + +### Key files and their purposes: + +- `action.yml` - GitHub Action definition with inputs/outputs +- `package.json` - Dependencies and npm scripts +- `tsconfig.json` - TypeScript compilation settings +- `jest.config.js` - Test configuration +- `eslint.config.mjs` - Linting rules (ignores `lib/` directory) +- `.node-version` - Required Node.js version (v22.11.0) + +### Understanding the codebase: + +- **Entry Point**: `src/main.ts` imports and calls the `run()` function from `src/lib.ts` +- **Core Logic**: `src/lib.ts` contains the main deployment logic +- **Git Operations**: `src/git.ts` handles repository initialization and deployment +- **Configuration**: `src/constants.ts` defines interfaces for action parameters +- **Testing**: Comprehensive Jest tests in `__tests__/` directory with mocks for GitHub Actions + +### Common development patterns: + +- Action parameters are defined in `src/constants.ts` interfaces +- Error handling uses try/catch with `extractErrorMessage()` utility +- All git commands go through `execute()` wrapper for consistent logging +- SSH and token authentication are handled in separate modules +- Extensive parameter validation in `src/util.ts` + +### CI/CD behavior: + +- `.github/workflows/build.yml` runs on every push and PR +- Linting, formatting, tests, and build must all pass +- Integration tests deploy to test repositories using various authentication methods +- Production releases include `node_modules` in distribution branches + +### Debugging and troubleshooting: + +- Check TypeScript compilation errors first: `yarn build` +- Run specific test files: `yarn test ` +- Use `yarn lint` to auto-fix linting issues +- The action supports debug mode via GitHub Actions debug logging +- Integration tests in CI provide real deployment validation + +### Important notes: + +- The `lib/` directory is compiled output and should not be manually edited +- Distribution branches (like `v4`) include `node_modules` and `lib/` for GitHub Actions runtime +- The dev branch excludes `node_modules` and `lib/` from version control +- SSH key support allows deployment with repository deploy keys +- Cross-repository deployment is supported with proper token permissions + +### Environment requirements: + +- Node.js v22.11.0 (specified in `.node-version`) +- Yarn package manager +- Git (for deployment operations) +- rsync (for file operations, automatically available in GitHub Actions runners) + +### Performance expectations: + +- Fresh install: ~25 seconds for `yarn install --frozen-lockfile` +- Cached install: ~1 second for `yarn install --frozen-lockfile` +- Build: ~9 seconds for `yarn build` +- Tests: ~8 seconds for `yarn test` +- Linting: ~3 seconds for `yarn lint:check` +- Formatting: ~2 seconds for `yarn lint:format:check` From 6bdb0feb0af7758c7d69f4af955dd74389a1a22a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:55:44 +0000 Subject: [PATCH 4/5] Remove hardcoded Node.js version references Co-authored-by: JamesIves <10888441+JamesIves@users.noreply.github.com> --- .github/copilot-instructions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 225ff59fd..8c5eed3f8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,7 +6,7 @@ Always follow these instructions first and only fallback to additional search an ### Bootstrap and build the repository: -- Use Node.js version from `.node-version` file: `v22.11.0` +- Use Node.js version from `.node-version` file - Install Yarn globally: `npm install -g yarn` - Install dependencies: `yarn install --frozen-lockfile` -- takes 1-25 seconds depending on cache state - Build the project: `yarn build` -- takes 9 seconds. NEVER CANCEL. Set timeout to 30+ seconds @@ -79,7 +79,7 @@ integration/ # Sample files for testing deployments - `tsconfig.json` - TypeScript compilation settings - `jest.config.js` - Test configuration - `eslint.config.mjs` - Linting rules (ignores `lib/` directory) -- `.node-version` - Required Node.js version (v22.11.0) +- `.node-version` - Required Node.js version ### Understanding the codebase: @@ -122,7 +122,7 @@ integration/ # Sample files for testing deployments ### Environment requirements: -- Node.js v22.11.0 (specified in `.node-version`) +- Node.js (specified in `.node-version`) - Yarn package manager - Git (for deployment operations) - rsync (for file operations, automatically available in GitHub Actions runners) From 11a668b3b1761d4edec7a2eaf41616094f065b9f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:59:33 +0000 Subject: [PATCH 5/5] Add project description to copilot instructions Co-authored-by: JamesIves <10888441+JamesIves@users.noreply.github.com> --- .github/copilot-instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8c5eed3f8..65142a8a6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,7 @@ # GitHub Pages Deploy Action +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. + 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. ## Working Effectively