Skip to content

Commit 461a407

Browse files
mr-chelyshkinmr-chelyshkin
authored
Docs (#9)
* [infra] docs
1 parent 70288fe commit 461a407

12 files changed

Lines changed: 496 additions & 444 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Description
2+
Brief description of what this PR does.
3+
4+
## Title Format
5+
- [ ] Title starts with tag: `[feat]`, `[fix]`, `[refactor]`, `[docs]`, `[chore]`
6+
7+
## Type of Change
8+
- [ ] 🐛 Bug fix
9+
- [ ] ✨ New feature
10+
- [ ] 💥 Breaking change
11+
- [ ] 📚 Documentation
12+
- [ ] 🔧 Refactoring
13+
14+
## Testing
15+
- [ ] Linting passes (`task yamllint`)
16+
- [ ] Tested with examples
17+
- [ ] Documentation updated
18+
19+
## Action-Specific
20+
- [ ] Follows input standards (`show_summary`, validation)
21+
- [ ] Includes README with inputs/outputs
22+
- [ ] Examples provided
23+
24+
## Issue
25+
Add issue if relevant
26+
27+
## Notes
28+
Additional context or concerns.
29+

‎CONCEPT.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Concept: Taskfile-Centric Development
2+
## Why
3+
Teams waste time fighting environment drift between local dev and CI.
4+
Scripts scatter across repos, CI has hidden steps, and debugging becomes trial-and-error.
5+
We fix this by making **Taskfile the single source of truth** and running everything in **secure containers** — locally and in CI.
6+
7+
## Who This Is For
8+
- Teams with complex build/test pipelines
9+
- Infrastructure-heavy projects (AWS, Terraform, CD)
10+
- Organizations wanting reproducibility and quick onboarding
11+
12+
## Core Principles
13+
1. **Reproducibility** — same Task runs identically everywhere
14+
2. **Isolation** — no host dependencies beyond Docker + Task
15+
3. **Security by default** — non-root, dropped caps, no-new-privileges
16+
4. **Transparency** — no CI-only magic; everything in `Taskfile.yml`
17+
5. **Separation of concerns** — CI (dev tasks) in Taskfile; CD (deploy) in Actions
18+
19+
## Container Security Defaults
20+
- `--cap-drop=ALL` — no privileged capabilities
21+
- `--security-opt no-new-privileges` — prevent privilege escalation
22+
- `--user $(id -u):$(id -g)` — non-root execution
23+
- `--workdir /workspace` — consistent working directory
24+
- Project mount only: `/workspace` (read-write)
25+
26+
## Container Runtime Pattern
27+
Pull image once (quiet):
28+
```yaml
29+
_docker/pull:
30+
internal: true
31+
cmds:
32+
- |
33+
if ! docker image inspect "{{.IMAGE}}" >/dev/null 2>&1; then
34+
docker pull -q "{{.IMAGE}}" >/dev/null 2>&1 || {
35+
echo "Failed to pull image: {{.IMAGE}}"
36+
exit 1
37+
}
38+
fi
39+
silent: true
40+
requires:
41+
vars: [IMAGE]
42+
```
43+
Run securely (never pull during execution):
44+
```yaml
45+
_docker/run:
46+
internal: true
47+
dir: "{{.git_root}}"
48+
deps:
49+
- task: _docker/pull
50+
vars: { IMAGE: "{{.IMAGE}}" }
51+
cmd: |
52+
docker run --rm --init --pull=never {{if .TTY}}-it{{end}} \
53+
--cap-drop=ALL \
54+
--security-opt no-new-privileges \
55+
--user $(id -u):$(id -g) \
56+
--workdir /workspace \
57+
{{if .ENVS}}{{range $e := .ENVS}}--env {{$e}} {{end}}{{end}}\
58+
{{if .PORTS}}{{range $p := .PORTS}}--publish {{$p}} {{end}}{{end}}\
59+
{{if .VOLUMES}}{{range $v := .VOLUMES}}--volume {{$v}} {{end}}{{end}}\
60+
--volume "{{.git_root}}/{{.MOUNT_DIR}}:/workspace:rw" \
61+
"{{.IMAGE}}" \
62+
{{.CMD}}
63+
silent: true
64+
requires:
65+
vars: [IMAGE, CMD, MOUNT_DIR]
66+
```
67+
68+
### Runtime Variables
69+
| Variable | Purpose | Example |
70+
|---|---|---|
71+
|`IMAGE`|Docker image (pin in CI)|`node:20`, `golang:1.22@sha256:...`|
72+
|`CMD`|Command to execute|`sh -c 'npm ci && npm test'`|
73+
|`MOUNT_DIR`|Project directory to mount|`"."`, `"site"`, `"infra"`|
74+
|`ENVS`|Environment variables|`["GOOS=linux","NPM_CONFIG_CACHE=/cache"]`|
75+
|`PORTS`|Port mappings for dev servers|`["3000:3000"]`|
76+
|`VOLUMES`|Additional mounts|`["$HOME/.ssh:/ssh:ro"]`|
77+
|`TTY`|Interactive mode|`"true"` for dev servers|
78+
79+
## Task Examples
80+
```yaml
81+
lint:
82+
desc: "Run code linting"
83+
cmds:
84+
- task: _docker/run
85+
vars:
86+
IMAGE: "node:20"
87+
MOUNT_DIR: "."
88+
ENVS: ["NPM_CONFIG_CACHE=/workspace/.cache"]
89+
CMD: "sh -c 'npm ci && npx eslint .'"
90+
91+
test:
92+
desc: "Run test suite"
93+
cmds:
94+
- task: _docker/run
95+
vars:
96+
IMAGE: "golang:1.22"
97+
MOUNT_DIR: "."
98+
CMD: "go test ./..."
99+
100+
dev:
101+
desc: "Development server with hot reload"
102+
cmds:
103+
- task: _docker/run
104+
vars:
105+
IMAGE: "node:20"
106+
MOUNT_DIR: "."
107+
PORTS: ["3000:3000"]
108+
TTY: "true"
109+
CMD: "sh -c 'npm ci && npm run dev -- --host 0.0.0.0'"
110+
```
111+
112+
## CI Integration
113+
Use the same tasks in GitHub Actions:
114+
```yaml
115+
jobs:
116+
ci:
117+
runs-on: ubuntu-latest
118+
steps:
119+
- uses: actions/checkout@v4
120+
121+
- uses: Mad-Pixels/github-workflows/actions/taskfile-runner@v1
122+
with:
123+
command: "lint"
124+
125+
- uses: Mad-Pixels/github-workflows/actions/taskfile-runner@v1
126+
with:
127+
command: "test"
128+
```
129+
130+
## What Goes Where
131+
|✅ Include in Taskfile|❌ Keep in Actions|
132+
|---|---|
133+
|Code linting/formatting|AWS deployments|
134+
|Unit/integration tests|Infrastructure provisioning|
135+
|Building/compilation|Production secrets handling|
136+
|Development servers|Cloud resource management|
137+
|Static analysis|Terraform apply operations|
138+
139+
## Benefits
140+
- 💰 **Reduced maintenance** — no more "works on my machine"
141+
- 🚀 **Faster delivery** — fewer environment-specific bugs
142+
- 🔐 **Stronger security** — containerized, non-root execution
143+
- 📋 **Clear audit trails** — Git history = deployment history
144+
- 🧠 **Better onboarding** — new engineers only need Docker and Task
145+
146+
## Local-to-CI Guarantee
147+
If it works locally, it works in CI — **guaranteed**:
148+
- Same Docker images and commands
149+
- Same environment variables and mounts
150+
- No CI-specific scripts or hidden steps
151+
- Debug locally, not through failed pipelines
152+
153+
## Best Practices
154+
- **Pin images by digest in CI** for determinism: `node:20@sha256:...`
155+
- **Use project-local caches** under `/workspace/.cache`
156+
- **Mount read-only where possible**: `["$HOME/.ssh:/ssh:ro"]`
157+
- **Validate inputs** in task descriptions and error messages
158+
- **Keep secrets out of Taskfile** — handle via Actions only
159+
160+
## Real Project Examples
161+
| Name | Description |
162+
|---|---|
163+
|**[about](https://github.com/mr-chelyshkin/about)**|VueJS static site with containerized build and AWS deployment|
164+

‎CONTRIBUTING.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Contributing Guide
2+
3+
Thank you for your interest in contributing to GitHub Workflows & Actions!
4+
5+
## Project Structure
6+
```bash
7+
.
8+
├── actions/ # All reusable actions
9+
│ ├── action-name/
10+
│ │ ├── action.yml # Action definition
11+
│ │ ├── readme.md # Documentation
12+
│ │ └── examples/ # Usage examples
13+
│ └── internal/ # Internal composite actions
14+
├── .github/workflows/ # CI/CD workflows
15+
├── Taskfile.yml # Development tasks
16+
└── README.md # Main documentation
17+
```
18+
19+
## Getting Started
20+
### Prerequisites
21+
- [Task CLI](https://taskfile.dev/installation/)
22+
- Docker
23+
- Git
24+
25+
### Development Workflow
26+
1. `Fork and clone` the repository
27+
2. `Create a feature branch`:
28+
```bash
29+
git checkout -b feature/my-new-action
30+
```
31+
3. `Run linting`:
32+
```bash
33+
task yamllint
34+
```
35+
4. `Test your changes` using example workflows
36+
37+
## Adding a New Action
38+
1. **Create directory structure**:
39+
```bash
40+
actions/my-new-action/
41+
├── action.yml
42+
├── readme.md
43+
└── examples/
44+
└── base.yml
45+
```
46+
2. **Follow existing patterns**:
47+
- Look at [docker-build-push](./actions/docker-build-push/) as reference
48+
- Use composite actions for shell scripts
49+
- Validate all inputs
50+
- Provide clear error messages
51+
52+
3. **Documentation requirements**:
53+
- Complete `readme.md` with inputs/outputs tables
54+
- Practical usage examples
55+
- Prerequisites and limitations
56+
57+
4. **Testing**:
58+
- Add example workflow in `examples/`
59+
- Test manually with the example
60+
- Ensure `task yamllint` passes
61+
62+
## Action Standards
63+
### Required Inputs
64+
All actions must include these standard inputs:
65+
```yaml
66+
show_summary:
67+
description: 'Print summary in the job summary'
68+
required: false
69+
default: 'true'
70+
```
71+
72+
### Summary Implementation
73+
- Generate job summary using `$GITHUB_STEP_SUMMARY`
74+
- Respect `show_summary` inputs
75+
- Include key outputs, status, and relevant details
76+
77+
## Code Standards
78+
- **YAML**: Follow `.yamllint.yml` rules
79+
- **Shell scripts**: Use `set -euo pipefail`
80+
- **Security**: Follow principle of least privilege
81+
- **Error handling**: Fail fast with clear messages
82+
83+
## Submitting Changes
84+
1. **Test thoroughly**:
85+
```bash
86+
task yamllint
87+
```
88+
2. **Commit with clear messages**:
89+
```bash
90+
git commit -m "[feat] add new action for xyz"
91+
```
92+
3. **Push and create PR**:
93+
- Describe what the action does
94+
- Include usage examples
95+
- Reference any related issues
96+
97+
## Questions?
98+
Open an [issue](https://github.com/Mad-Pixels/github-workflows/issues)
99+
or start a [discussion](https://github.com/Mad-Pixels/github-workflows/discussions)!
100+

0 commit comments

Comments
 (0)