Skip to content

Commit b1ca531

Browse files
Copilotdamacusramereth
authored
Add GitHub Copilot instructions for Apache2 cookbook development with automated setup workflow (#827)
* Initial plan * Create comprehensive GitHub Copilot instructions for Apache2 cookbook Co-authored-by: damacus <40786+damacus@users.noreply.github.com> * Add action setup steps for copilot Signed-off-by: Lance Albertson <lance@osuosl.org> * Update copilot instructions to reflect resolved network and tooling limitations Co-authored-by: ramereth <48997+ramereth@users.noreply.github.com> --------- Signed-off-by: Lance Albertson <lance@osuosl.org> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: damacus <40786+damacus@users.noreply.github.com> Co-authored-by: Lance Albertson <lance@osuosl.org> Co-authored-by: ramereth <48997+ramereth@users.noreply.github.com>
1 parent ddbab87 commit b1ca531

File tree

2 files changed

+151
-0
lines changed

2 files changed

+151
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Apache2 Chef Cookbook
2+
3+
This repository contains the Chef cookbook for Apache HTTP Server management. It provides Debian/Ubuntu style Apache configuration across multiple platforms with resources for managing modules, sites, configurations, and service lifecycle.
4+
5+
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.
6+
7+
## Working Effectively
8+
9+
### Bootstrap Environment
10+
- Install Ruby 3.2+ with development tools:
11+
- `sudo apt update && sudo apt install -y ruby-bundler ruby-dev build-essential nodejs npm`
12+
- Install Chef development tools (user gems due to permission constraints):
13+
- `gem install --user-install berkshelf cookstyle chefspec`
14+
- `export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"`
15+
- Install additional linting tools:
16+
- `npm install -g markdownlint-cli2`
17+
18+
**Environment Setup**: With the Copilot setup workflow (`.github/workflows/copilot-setup-steps.yml`), Chef Workstation and dependencies are automatically installed via GitHub Actions setup steps, enabling full Berkshelf functionality (`berks install` works with supermarket.chef.io access).
19+
20+
### Linting and Code Quality
21+
- **Cookstyle (Ruby linting)**: `cookstyle .` -- takes 5 seconds. NEVER use `--auto-correct` as it can introduce syntax errors.
22+
- **YAML linting**: `yamllint .` -- takes <1 second
23+
- **Markdown linting**: `markdownlint-cli2 "**/*.md"` -- takes 1 second
24+
- **CRITICAL**: Always run `cookstyle .` before committing. Currently shows 17 style offenses that should NOT be auto-corrected due to syntax risks.
25+
26+
### Testing Status
27+
- **Unit Tests**: RSpec with ChefSpec works with Chef Workstation from setup workflow
28+
- **Integration Tests**: Test Kitchen available with Chef Workstation and container support
29+
- **CI Environment**: Uses GitHub Actions with Chef Workstation, Dokken containers, and matrix testing across platforms
30+
- **Available Validation**: Full linting (Cookstyle, YAML, Markdown), unit tests, and integration tests
31+
32+
### Build and Dependency Management
33+
- **Berkshelf**: `berks install` -- Works with Chef Workstation installed via setup workflow
34+
- **Dependencies**: Single dependency on `yum-epel` cookbook (defined in metadata.rb)
35+
- **Platforms Supported**: Debian, Ubuntu, RHEL, CentOS, Fedora, Amazon, Scientific, FreeBSD, SUSE, OpenSUSE, Arch
36+
- **Chef Version**: Requires Chef >= 15.3
37+
38+
## Validation Scenarios
39+
- **Cookstyle auto-correction available**: With Chef Workstation, `cookstyle --auto-correct` can be used safely
40+
- **Complete testing pipeline**: Lint, unit tests, and integration tests all available via setup workflow
41+
- **Full dependency resolution**: Berkshelf can install all cookbook dependencies from Chef Supermarket
42+
- **CI will run full integration tests**: 9 test suites across 13 platform combinations in GitHub Actions
43+
44+
## Common Tasks
45+
46+
### Repository Structure
47+
```
48+
/home/runner/work/apache2/apache2/
49+
├── resources/ # Chef resources (install.rb, service.rb, mod_*.rb, etc.)
50+
├── libraries/ # Helper functions (helpers.rb)
51+
├── templates/ # Configuration templates (.erb files)
52+
├── test/ # Test cookbooks and integration tests
53+
│ ├── cookbooks/test/ # Test recipes
54+
│ └── integration/ # InSpec integration tests
55+
├── spec/ # RSpec unit tests (ChefSpec)
56+
├── documentation/ # Resource documentation
57+
├── metadata.rb # Cookbook metadata and dependencies
58+
├── kitchen.yml # Test Kitchen configuration
59+
├── kitchen.dokken.yml # Docker-based testing config
60+
└── Berksfile # Berkshelf dependency management
61+
```
62+
63+
### Key Files to Reference
64+
- **metadata.rb**: Cookbook version, dependencies, supported platforms
65+
- **libraries/helpers.rb**: Platform-specific defaults and helper methods
66+
- **resources/install.rb**: Main Apache installation resource
67+
- **resources/service.rb**: Apache service management
68+
- **resources/mod_*.rb**: Apache module management resources
69+
- **test/cookbooks/test/recipes/**: Example usage patterns
70+
71+
### Workflow Commands
72+
```bash
73+
# Set up environment
74+
export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
75+
76+
# Lint everything before changes
77+
cookstyle .
78+
yamllint .
79+
markdownlint-cli2 "**/*.md"
80+
81+
# View test examples
82+
cat test/cookbooks/test/recipes/default.rb
83+
cat test/cookbooks/test/recipes/basic_site.rb
84+
85+
# Check integration test scenarios
86+
ls test/integration/*/controls/
87+
```
88+
89+
### Resource Usage Examples
90+
See `test/cookbooks/test/recipes/` for working examples:
91+
- **Basic Apache**: `default.rb` - Install, configure service, manage default site
92+
- **SSL Configuration**: `mod_ssl.rb` - SSL module and site setup
93+
- **PHP Integration**: `php.rb` - PHP module configuration
94+
- **Custom Modules**: `module_template.rb` - Custom module management
95+
96+
### Platform-Specific Notes
97+
- **RHEL/CentOS**: Uses `httpd` service name, `/etc/httpd/` config path
98+
- **Debian/Ubuntu**: Uses `apache2` service name, `/etc/apache2/` config path
99+
- **FreeBSD**: Uses `apache24` service name
100+
- Helper functions in `libraries/helpers.rb` abstract platform differences
101+
102+
### Environment Capabilities
103+
- **Network access**: Full access to Chef Supermarket and external dependencies via GitHub Actions setup
104+
- **Chef Workstation**: Available via `actionshub/chef-install` action in setup workflow
105+
- **Unit tests**: ChefSpec and RSpec available with proper Chef Workstation installation
106+
- **Integration testing**: Available with Test Kitchen and container support
107+
- **Cookstyle auto-correction**: Safe to use with proper Chef environment
108+
109+
### CI Integration Notes
110+
- GitHub Actions uses `actionshub/chef-install` to install Chef Workstation
111+
- Runs on Ubuntu with Chef licensing: `CHEF_LICENSE: accept-no-persist`
112+
- Full matrix testing: 9 test suites × 13 platforms = 117 test combinations
113+
- Uses Dokken containers for fast, isolated testing environment
114+
- Shared workflow from sous-chefs/.github repository handles lint-unit phase
115+
116+
**TIMING EXPECTATIONS**:
117+
- Cookstyle linting: ~5 seconds
118+
- YAML linting: ~1 second
119+
- Markdown linting: ~1 second
120+
- Dependency resolution: Works with Berkshelf via setup workflow
121+
- Unit tests: Available with ChefSpec
122+
- Integration tests: Available with Test Kitchen and containers
123+
124+
**REMEMBER**: This cookbook manages Apache HTTP server across multiple platforms. Focus on resource definitions, template logic, and platform compatibility when making changes. The extensive CI matrix will validate functionality across all supported platforms.

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: "Copilot Setup Steps"
3+
4+
on:
5+
workflow_dispatch:
6+
push:
7+
paths:
8+
- .github/workflows/copilot-setup-steps.yml
9+
pull_request:
10+
paths:
11+
- .github/workflows/copilot-setup-steps.yml
12+
13+
jobs:
14+
copilot-setup-steps:
15+
runs-on: ubuntu-latest
16+
17+
permissions:
18+
contents: read
19+
20+
steps:
21+
- name: Check out code
22+
uses: actions/checkout@v5
23+
- name: Install Chef
24+
uses: actionshub/chef-install@main
25+
- name: Install cookbooks
26+
run: |
27+
berks install

0 commit comments

Comments
 (0)