|
| 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` |
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments