diff --git a/.github/CI.md b/.github/CI.md index 266c378..d9c17d6 100644 --- a/.github/CI.md +++ b/.github/CI.md @@ -1,6 +1,6 @@ # CI Workflows -Three workflows gate changes to this repository. All are triggered by pull requests to `main`, scoped to their relevant paths. +Six workflows gate changes to this repository. All are triggered by pull requests to `main`, scoped to their relevant paths. --- @@ -77,7 +77,7 @@ Checkov results are posted as a PR comment on failure and uploaded to the GitHub --- -## `gitops-ci.yaml` — GitOps / Kubernetes CI +## `gitops-ci.yaml` - GitOps / Kubernetes CI **Triggers:** pull requests to `main` with changes under `gitops/**`, `k8s/**`, or `charts/**`. @@ -90,19 +90,19 @@ Protects the GitOps repo from broken YAML, invalid manifests, and broken Helm te | `helm lint` | Chart structure and values for all three charts (`simple-time-service`, `namespaces`, `raw`) | | `helm template \| kubeconform` | Rendered manifests from `simple-time-service` and `namespaces` are valid Kubernetes resources against the 1.34 schema | -`charts/raw` is only linted, not templated — it is a passthrough chart that requires caller-supplied `Values.resources` to produce output. +`charts/raw` is only linted, not templated - it is a passthrough chart that requires caller-supplied `Values.resources` to produce output. ### Job: `manifests` | Step | What it checks | |------|----------------| | `kubeconform` on `k8s/` | Strict schema validation against Kubernetes 1.34 | -| `kubeconform` on `gitops/` | Schema validation with `--ignore-missing-schemas` — standard K8s resources are validated; ArgoCD and Prometheus CRDs are skipped | +| `kubeconform` on `gitops/` | Schema validation with `--ignore-missing-schemas` - standard K8s resources are validated; ArgoCD and Prometheus CRDs are skipped | | ApplicationSet Go template options | Every `kind: ApplicationSet` file must have `goTemplate: true` and `goTemplateOptions: ["missingkey=error"]` | **Why the ApplicationSet check matters:** -- `goTemplate: true` — enables Go template syntax in the ApplicationSet generator; without it, template expressions are rendered literally -- `missingkey=error` — makes ArgoCD fail at sync time if a template variable is undefined, instead of silently rendering an empty string which can produce broken manifests that pass validation but misbehave at runtime +- `goTemplate: true` - enables Go template syntax in the ApplicationSet generator; without it, template expressions are rendered literally +- `missingkey=error` - makes ArgoCD fail at sync time if a template variable is undefined, instead of silently rendering an empty string which can produce broken manifests that pass validation but misbehave at runtime ### Job: `yaml-lint` @@ -128,8 +128,82 @@ All three jobs post results as a PR comment on failure. --- +## `actions-check.yaml` - GitHub Actions Check + +**Triggers:** pull requests to `main` with changes under `.github/workflows/**`. + +### Job: `Lint Workflows` + +Runs [`actionlint`](https://github.com/rhysd/actionlint) across all workflow files in `.github/workflows/`. Catches issues before they reach GitHub Actions runners: + +- Invalid expression syntax (`${{ }}`) +- References to undefined contexts or outputs +- Type mismatches (e.g. passing a string where a boolean is expected) +- Invalid `if:` conditionals +- Incorrect `needs:` job references +- Missing required inputs on `workflow_call` + +Results are posted as a PR comment on failure. + +--- + +## `codeowners-check.yaml` - CODEOWNERS Check + +**Triggers:** pull requests to `main` with changes to `.github/CODEOWNERS`. + +### Job: `validate` + +Runs [`codeowners-validator`](https://github.com/mszostok/codeowners-validator) against `.github/CODEOWNERS` with three checks: + +| Check | What it validates | +|-------|-------------------| +| `syntax` | File follows the valid CODEOWNERS pattern format | +| `duppatterns` | No two entries match the same glob pattern | + +The `owners` check is excluded - it requires `read:org` OAuth scope which the default `GITHUB_TOKEN` does not have. + +Results are posted as a PR comment on failure. + +--- + +## `pr-title-check.yaml` - PR Title Check + +**Triggers:** all pull requests to `main` (no path filter) on `opened`, `edited`, `synchronize`, and `reopened` events. + +### Job: `validate` + +Validates that the PR title follows [Conventional Commits](https://www.conventionalcommits.org/) format using [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request). + +**Format:** `[optional scope]: ` + +**Valid types:** + +| Type | Use for | +|------|---------| +| `feat` | New feature or capability | +| `fix` | Bug fix | +| `chore` | Maintenance, dependency updates | +| `docs` | Documentation only | +| `ci` | CI/CD pipeline changes | +| `refactor` | Code restructuring without behaviour change | +| `test` | Adding or updating tests | +| `perf` | Performance improvements | +| `style` | Formatting, whitespace (no logic change) | +| `revert` | Reverting a previous commit | + +**Examples:** +- `feat: add velero backup schedule` +- `fix(app): correct health check endpoint` +- `ci: add pr title check workflow` + +The `synchronize` trigger ensures branch protection always sees a current status on the latest commit, even when only the branch is updated without editing the title. On failure, a PR comment is posted with the current title, the expected format, and examples. The comment is updated in place if the title is edited and still fails. + +--- + ## Branch protection To enforce that all checks must pass before a PR can be merged, configure branch protection on `main`: -**Settings → Branches → Add rule → Require status checks to pass → add `build-and-scan`, `validate`, `security`, `helm`, `manifests`, `yaml-lint`** +**Settings → Branches → Add rule → Require status checks to pass → add `Build and Trivy Scan`, `Validate Terraform`, `Checkov Scan`, `Helm Lint`, `Validate Manifests`, `YAML Lint`, `Lint Workflows`, `Validate CODEOWNERS`, `Validate PR Title`** + +> `validate` appears in both `terraform-ci` and `codeowners-check`. GitHub treats status checks by job name - both must pass when both are triggered. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..e8b78e7 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,16 @@ +# Default owner for everything not matched below +* @Beem0807 + +# CI workflows - any change to pipelines requires review +.github/ @Beem0807 + +# Infrastructure - Terraform changes require review +terraform/ @Beem0807 + +# Application - image and source code changes require review +app/ @Beem0807 + +# GitOps - manifest changes require review before ArgoCD picks them up +gitops/ @Beem0807 +k8s/ @Beem0807 +charts/ @Beem0807 \ No newline at end of file diff --git a/.github/branch-protection.md b/.github/branch-protection.md new file mode 100644 index 0000000..4be81f2 --- /dev/null +++ b/.github/branch-protection.md @@ -0,0 +1,36 @@ +# Branch Protection - `main` + +Documents the branch protection rules configured on `main`. These settings enforce that all CI checks pass before any PR can be merged. + +## Rules + +| Rule | Setting | +|------|---------| +| Require pull request before merging | ✅ Enabled - Required approvals: **0** | +| Require status checks to pass | ✅ Enabled - see checks below | +| Require branches to be up to date | ✅ Enabled | +| Require conversation resolution | ✅ Enabled | +| Require linear history | ✅ Enabled | +| Restrict direct pushes to `main` | ✅ Enabled | +| Require review from Code Owners | ❌ Disabled | + +## Required status checks + +| Check | Workflow | +|-------|----------| +| `App Image CI` | `.github/workflows/app-image.yaml` | +| `Terraform CI` | `.github/workflows/terraform-ci.yaml` | +| `GitOps CI` | `.github/workflows/gitops-ci.yaml` | +| `CODEOWNERS Check` | `.github/workflows/codeowners-check.yaml` | +| `GitHub Actions Check` | `.github/workflows/actions-check.yaml` | +| `PR Title Check` | `.github/workflows/pr-title-check.yaml` | + +Each check only triggers when its relevant paths change. A check that was not triggered by a PR is treated as passing - only triggered checks must succeed. + +## Notes + +**Required approvals: 0** - PRs can self-merge once all required status checks pass. Suitable for a solo project; increase to 1 when collaborators are added. + +**CODEOWNERS disabled** - `.github/CODEOWNERS` is present but "Require review from Code Owners" is off. The file is ready to enforce reviews if a second owner is added to the project. + +See [CI.md](CI.md) for full documentation on what each workflow validates. diff --git a/.github/workflows/actions-check.yaml b/.github/workflows/actions-check.yaml new file mode 100644 index 0000000..97bb77c --- /dev/null +++ b/.github/workflows/actions-check.yaml @@ -0,0 +1,66 @@ +name: GitHub Actions Check + +on: + pull_request: + branches: + - main + paths: + - '.github/workflows/**' + workflow_dispatch: + +jobs: + actionlint: + name: Lint Workflows + runs-on: ubuntu-latest + + permissions: + contents: read + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install actionlint + run: | + curl -sL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash + sudo mv ./actionlint /usr/local/bin/ + + - name: Run actionlint + id: actionlint + run: | + set -o pipefail + actionlint \ + 2>&1 | tee "$GITHUB_WORKSPACE/actionlint-report.txt" + + - name: Post results as PR comment + if: failure() && github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.existsSync('actionlint-report.txt') + ? fs.readFileSync('actionlint-report.txt', 'utf8').trim() + : 'No report generated.'; + const body = `## actionlint Results\n\`\`\`\n${report}\n\`\`\``; + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + const existing = comments.find(c => c.body.startsWith('## actionlint Results')); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body, + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body, + }); + } diff --git a/.github/workflows/app-image.yaml b/.github/workflows/app-image.yaml index 3da5226..f7dc8da 100644 --- a/.github/workflows/app-image.yaml +++ b/.github/workflows/app-image.yaml @@ -1,4 +1,4 @@ -name: Build and Push app image +name: App Image CI on: push: @@ -17,6 +17,7 @@ on: jobs: build-and-scan: + name: Build and Trivy Scan runs-on: ubuntu-latest permissions: diff --git a/.github/workflows/codeowners-check.yaml b/.github/workflows/codeowners-check.yaml new file mode 100644 index 0000000..3501d4a --- /dev/null +++ b/.github/workflows/codeowners-check.yaml @@ -0,0 +1,68 @@ +name: CODEOWNERS Check + +on: + pull_request: + branches: + - main + paths: + - '.github/CODEOWNERS' + - '.github/workflows/codeowners-check.yaml' + workflow_dispatch: + +jobs: + validate: + name: Validate CODEOWNERS + runs-on: ubuntu-latest + + permissions: + contents: read + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install codeowners-validator + run: go install github.com/mszostok/codeowners-validator@v0.7.4 + + - name: Validate CODEOWNERS + id: codeowners + env: + REPOSITORY_PATH: ${{ github.workspace }} + CHECKS: "syntax,duppatterns" + run: | + set -o pipefail + "$(go env GOPATH)/bin/codeowners-validator" \ + 2>&1 | tee "$GITHUB_WORKSPACE/codeowners-report.txt" + + - name: Post results as PR comment + if: failure() && github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const report = fs.existsSync('codeowners-report.txt') + ? fs.readFileSync('codeowners-report.txt', 'utf8').trim() + : 'No report generated.'; + const body = `## CODEOWNERS Validation Results\n\`\`\`\n${report}\n\`\`\``; + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + const existing = comments.find(c => c.body.startsWith('## CODEOWNERS Validation Results')); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body, + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body, + }); + } diff --git a/.github/workflows/gitops-ci.yaml b/.github/workflows/gitops-ci.yaml index 8b64a52..2457dbe 100644 --- a/.github/workflows/gitops-ci.yaml +++ b/.github/workflows/gitops-ci.yaml @@ -13,7 +13,7 @@ on: jobs: helm: - name: Helm + name: Helm Lint runs-on: ubuntu-latest permissions: @@ -38,7 +38,7 @@ jobs: run: | set -o pipefail helm lint charts/simple-time-service charts/namespaces charts/raw \ - 2>&1 | tee $GITHUB_WORKSPACE/helm-lint-report.txt + 2>&1 | tee "$GITHUB_WORKSPACE/helm-lint-report.txt" - name: helm template | kubeconform id: helm_kubeconform @@ -48,7 +48,7 @@ jobs: helm template charts/simple-time-service helm template charts/namespaces } | kubeconform -summary -strict -kubernetes-version 1.34.0 - \ - 2>&1 | tee $GITHUB_WORKSPACE/helm-kubeconform-report.txt + 2>&1 | tee "$GITHUB_WORKSPACE/helm-kubeconform-report.txt" - name: Post results as PR comment if: failure() && github.event_name == 'pull_request' @@ -86,7 +86,7 @@ jobs: } manifests: - name: Manifests + name: Validate Manifests runs-on: ubuntu-latest permissions: @@ -108,7 +108,7 @@ jobs: run: | set -o pipefail kubeconform -summary -strict -kubernetes-version 1.34.0 k8s/ \ - 2>&1 | tee $GITHUB_WORKSPACE/kubeconform-k8s-report.txt + 2>&1 | tee "$GITHUB_WORKSPACE/kubeconform-k8s-report.txt" - name: kubeconform (gitops/) id: kube_gitops @@ -120,7 +120,7 @@ jobs: -ignore-missing-schemas \ -kubernetes-version 1.34.0 \ gitops/ \ - 2>&1 | tee $GITHUB_WORKSPACE/kubeconform-gitops-report.txt + 2>&1 | tee "$GITHUB_WORKSPACE/kubeconform-gitops-report.txt" - name: Validate ApplicationSet Go template options id: appset_gotemplate @@ -128,11 +128,11 @@ jobs: failed=0 while IFS= read -r file; do if ! grep -q "goTemplate: true" "$file"; then - echo "FAIL: $file — missing 'goTemplate: true'" + echo "FAIL: $file - missing 'goTemplate: true'" failed=1 fi if ! grep -q "missingkey=error" "$file"; then - echo "FAIL: $file — missing 'missingkey=error' in goTemplateOptions" + echo "FAIL: $file - missing 'missingkey=error' in goTemplateOptions" failed=1 fi done < <(grep -rl "kind: ApplicationSet" gitops/ --include="*.yaml") @@ -174,7 +174,7 @@ jobs: } yaml-lint: - name: YAML lint + name: YAML Lint runs-on: ubuntu-latest permissions: @@ -193,7 +193,7 @@ jobs: run: | set -o pipefail yamllint gitops/ k8s/ charts/ \ - 2>&1 | tee $GITHUB_WORKSPACE/yamllint-report.txt + 2>&1 | tee "$GITHUB_WORKSPACE/yamllint-report.txt" - name: Post results as PR comment if: failure() && github.event_name == 'pull_request' diff --git a/.github/workflows/pr-title-check.yaml b/.github/workflows/pr-title-check.yaml new file mode 100644 index 0000000..b777acd --- /dev/null +++ b/.github/workflows/pr-title-check.yaml @@ -0,0 +1,74 @@ +name: PR Title Check + +on: + pull_request: + branches: + - main + types: + - opened + - edited + - synchronize + - reopened + +jobs: + validate: + name: Validate PR Title + runs-on: ubuntu-latest + + permissions: + pull-requests: write + + steps: + - name: Check PR title follows Conventional Commits + id: pr_title + uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Post results as PR comment + if: failure() && github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const title = context.payload.pull_request.title; + const body = [ + '## PR Title Check Failed', + '', + `Current title: \`${title}\``, + '', + 'PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) format:', + '', + '```', + '[optional scope]: ', + '```', + '', + '**Valid types:** `feat`, `fix`, `chore`, `docs`, `ci`, `refactor`, `test`, `perf`, `style`, `revert`', + '', + '**Examples:**', + '- `feat: add velero backup schedule`', + '- `fix(app): correct health check endpoint`', + '- `ci: add pr title check workflow`', + '', + 'Edit the PR title and the check will re-run automatically.', + ].join('\n'); + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + const existing = comments.find(c => c.body.startsWith('## PR Title Check Failed')); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body, + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body, + }); + } diff --git a/.github/workflows/terraform-ci.yaml b/.github/workflows/terraform-ci.yaml index 2a952c7..daf830b 100644 --- a/.github/workflows/terraform-ci.yaml +++ b/.github/workflows/terraform-ci.yaml @@ -11,7 +11,7 @@ on: jobs: validate: - name: Validate + name: Validate Terraform runs-on: ubuntu-latest permissions: @@ -60,7 +60,7 @@ jobs: - name: TFLint id: tflint - run: tflint --recursive 2>&1 | tee $GITHUB_WORKSPACE/tflint-report.txt; exit ${PIPESTATUS[0]} + run: tflint --recursive 2>&1 | tee "$GITHUB_WORKSPACE/tflint-report.txt"; exit "${PIPESTATUS[0]}" working-directory: terraform - name: Post TFLint results as PR comment @@ -96,7 +96,7 @@ jobs: } security: - name: Security scan + name: Checkov Scan runs-on: ubuntu-latest permissions: diff --git a/README.md b/README.md index f55c335..68f76b8 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,8 @@ A production-style cloud-native platform built on AWS EKS, demonstrating the ful | | | |-|-| -| [.github/CI.md](.github/CI.md) | CI workflows - triggers, steps, required secrets, branch protection | +| [.github/CI.md](.github/CI.md) | CI workflows - triggers, steps, required secrets | +| [.github/branch-protection.md](.github/branch-protection.md) | Branch protection rules and required status checks | | [app/README.md](app/README.md) | Docker image, CI pipeline, endpoints, container security | | [terraform/README.md](terraform/README.md) | Infrastructure provisioning, bootstrap module, remote state | | [charts/namespaces/README.md](charts/namespaces/README.md) | Namespace management chart - creates namespaces and ResourceQuotas from a values list | @@ -202,11 +203,16 @@ bash terraform/scripts/upgrade.sh ``` . ├── .github/ -│ ├── CI.md # CI workflows - triggers, steps, secrets, branch protection +│ ├── CI.md # CI workflows - triggers, steps, secrets +│ ├── CODEOWNERS # Automatic review assignment by path +│ ├── branch-protection.md # Branch protection rules and required status checks │ └── workflows/ │ ├── app-image.yaml # CI - build, scan, and push Docker image to Docker Hub │ ├── terraform-ci.yaml # CI - format, validate, lint, and security scan Terraform -│ └── gitops-ci.yaml # CI - helm lint, kubeconform, and yamllint for GitOps manifests +│ ├── gitops-ci.yaml # CI - helm lint, kubeconform, and yamllint for GitOps manifests +│ ├── actions-check.yaml # CI - lint all GitHub Actions workflow files with actionlint +│ ├── codeowners-check.yaml # CI - validate CODEOWNERS syntax and owner existence +│ └── pr-title-check.yaml # CI - enforce Conventional Commits format on PR titles ├── .yamllint.yaml # yamllint config - rules for gitops-ci YAML linting ├── compose.yaml # Docker Compose for local development ├── app/