Skip to content

Commit d0a7bec

Browse files
chendelin1982chendelin1982
authored
Merge pull request #2 from Websoft9/dev
Dev to main
2 parents 6621212 + e347b96 commit d0a7bec

89 files changed

Lines changed: 3493 additions & 1367 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/branch-protection-guide.md‎

Lines changed: 74 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,69 @@
11
# Branch Protection And CI Roles
22

3-
This repository uses three CI layers with different responsibilities:
3+
This repository uses three primary CI/CD layers with different responsibilities:
44

55
- `PR Gate`: the pre-merge blocking gate for `main`
66
- `Main Post-Merge`: post-merge validation for merge-result health and advisory supply-chain checks
77
- `Release`: tag-based release preparation and draft release creation
88

9+
There is also one source-security workflow managed alongside the CI layers:
10+
11+
- `CodeQL`: source code security scanning for PRs to `main` and pushes to `main`
12+
13+
There is also one optional developer workflow:
14+
15+
- `Dev Fast CI`: lightweight self-checks for non-`main` development branches
16+
917
Related workflows:
1018

1119
- `.github/workflows/pr-gate.yml`
20+
- `.github/workflows/_quality-gate.yml`
1221
- `.github/workflows/main-post-merge.yml`
22+
- `.github/workflows/codeql.yml`
23+
- `.github/workflows/dev-fast-ci.yml`
1324
- `.github/workflows/release.yml`
1425
- `.github/workflows/publish-images.yml`
1526

1627
## What Should Block Merge
1728

18-
Only the PR gate should be configured as the required branch-protection check for `main`.
29+
Only the PR gate should be configured as the required branch-protection check set for `main`.
30+
31+
Recommended required check targets:
32+
33+
- `PR Gate / Quality Gate / Lint (pull_request)`
34+
- `PR Gate / Quality Gate / Test Backend (pull_request)`
35+
- `PR Gate / Quality Gate / Test Frontend (pull_request)`
36+
- `PR Gate / Quality Gate / Security Scan (pull_request)`
37+
- `PR Gate / Quality Gate / E2E Smoke (pull_request)`
1938

20-
Recommended required check target:
39+
Optional later additions after the first successful CodeQL PR runs:
2140

22-
- workflow: `PR Gate`
23-
- job: `Quality Gate`
41+
- the real reported CodeQL PR job checks, such as the Go and JavaScript TypeScript analysis jobs
2442

2543
Why:
2644

27-
- It is the main admission gate for code entering `main`.
28-
- It runs lint, tests, security fast checks, and e2e smoke.
29-
- It avoids using post-merge or release-only checks as pre-merge blockers.
45+
- `PR Gate` is the main admission gate for code entering `main`
46+
- it runs lint, tests, security fast checks, and e2e smoke
47+
- it avoids using post-merge or release-only checks as pre-merge blockers
48+
- GitHub branch protection must reference the real job-level checks reported by workflows, not abstract wrapper names like `PR Gate` or `Quality Gate`
49+
50+
Do not set these as required checks unless matching workflows are actually reporting them:
51+
52+
- `PR Gate`
53+
- `Quality Gate`
54+
- `Code scanning results`
55+
56+
## Developer Branch Fast CI
57+
58+
`Dev Fast CI` is intended for personal development branches and excludes `main`.
59+
60+
It is useful for early feedback, but it is not a merge-governance layer and should not replace the PR gate.
61+
62+
Recommended use:
63+
64+
- run lightweight lint, backend/frontend tests, and fast security checks on `push -> non-main branches`
65+
- do not treat `Dev Fast CI` as a required check for `main`
66+
- do not use it as a substitute for PR review or branch protection
3067

3168
## What Should Not Block Merge
3269

@@ -55,8 +92,9 @@ Enable:
5592

5693
Recommended manual settings outside the repository:
5794

58-
- set `PR Gate / Quality Gate` as a required status check
59-
- require at least one human approval
95+
- set the five PR job checks listed above as required status checks
96+
- after the first successful CodeQL runs, optionally add the real reported CodeQL PR check names if you want source security scanning to block merges
97+
- require at least one human approval when the repository has more than one active maintainer
6098
- add CODEOWNERS later for sensitive areas such as workflows, release logic, and runtime bootstrapping
6199

62100
## How To Treat AI In Branch Protection
@@ -76,4 +114,29 @@ Release workflows are not part of the merge gate.
76114
- `Release` validates tags, generates release artifacts, and creates a draft release
77115
- `Publish Images` runs only after a release is published
78116

79-
This separation avoids using release-specific work as a daily development bottleneck.
117+
This separation avoids using release-specific work as a daily development bottleneck.
118+
119+
## Current Code Scanning State
120+
121+
There is a dedicated repository-managed CodeQL workflow in `.github/workflows/codeql.yml`.
122+
123+
What exists right now:
124+
125+
- `CodeQL` runs for `pull_request -> main`
126+
- `CodeQL` runs for `push -> main`
127+
- `Main Post-Merge` runs an advisory Trivy image scan
128+
- the Trivy SARIF report is uploaded to GitHub Security using `github/codeql-action/upload-sarif@v3`
129+
- the Trivy SARIF upload happens after pushes to `main`, not as a PR gate
130+
131+
What this means operationally:
132+
133+
- PRs to `main` now produce dedicated CodeQL checks and code scanning results
134+
- pushes to `main` continue to refresh the default-branch code scanning baseline
135+
- branch protection should use the real CodeQL job check names after they appear, not the generic label `Code scanning results`
136+
- Trivy image scanning remains a post-merge image-security signal, not a source-code scanning gate
137+
138+
Recommended interpretation:
139+
140+
- CodeQL is the source-code security layer
141+
- Trivy image scanning is the post-merge image-security layer
142+
- these are complementary and should not be treated as the same check type

‎.github/pull_request_template.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Explain the problem, requirement, or risk this PR addresses.
1717
- [ ] `make lint`
1818
- [ ] `make test backend`
1919
- [ ] `make test web`
20-
- [ ] `make e2e`
20+
- [ ] `make test e2e fast`
2121
- [ ] Other validation noted below
2222

2323
Additional validation notes:

‎.github/workflows/_quality-gate.yml‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,21 @@ jobs:
5959
- name: Run backend tests
6060
run: make test backend
6161

62+
openapi:
63+
name: OpenAPI Check
64+
runs-on: ubuntu-latest
65+
steps:
66+
- uses: actions/checkout@v4
67+
68+
- name: Set up Go
69+
uses: actions/setup-go@v5
70+
with:
71+
go-version-file: backend/go.mod
72+
cache-dependency-path: backend/go.sum
73+
74+
- name: Run OpenAPI sync check
75+
run: make openapi-sync
76+
6277
test-frontend:
6378
name: Test Frontend
6479
runs-on: ubuntu-latest
@@ -164,7 +179,7 @@ jobs:
164179
e2e:
165180
name: E2E Smoke
166181
runs-on: ubuntu-latest
167-
needs: [lint, test-backend, test-frontend, sec]
182+
needs: [lint, test-backend, test-frontend, openapi, sec]
168183
timeout-minutes: 30
169184
steps:
170185
- uses: actions/checkout@v4
@@ -173,7 +188,7 @@ jobs:
173188
run: mkdir -p build/reports/e2e
174189

175190
- name: Run container smoke test
176-
run: make e2e
191+
run: make test e2e fast
177192
env:
178193
APPOS_E2E_ARTIFACT_DIR: build/reports/e2e
179194
APPOS_E2E_KEEP_CONTAINER_ON_FAILURE: "1"

‎.github/workflows/codeql.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: CodeQL
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
push:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
permissions:
11+
actions: read
12+
contents: read
13+
security-events: write
14+
15+
concurrency:
16+
group: codeql-${{ github.workflow }}-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
jobs:
20+
analyze-go:
21+
name: Analyze Go
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
27+
- name: Initialize CodeQL
28+
uses: github/codeql-action/init@v3
29+
with:
30+
languages: go
31+
32+
- name: Set up Go
33+
uses: actions/setup-go@v5
34+
with:
35+
go-version-file: backend/go.mod
36+
cache-dependency-path: backend/go.sum
37+
38+
- name: Build Go sources
39+
run: cd backend && go build ./...
40+
41+
- name: Perform CodeQL analysis
42+
uses: github/codeql-action/analyze@v3
43+
with:
44+
category: /language:go
45+
46+
analyze-javascript-typescript:
47+
name: Analyze JavaScript TypeScript
48+
runs-on: ubuntu-latest
49+
steps:
50+
- name: Checkout repository
51+
uses: actions/checkout@v4
52+
53+
- name: Initialize CodeQL
54+
uses: github/codeql-action/init@v3
55+
with:
56+
languages: javascript-typescript
57+
58+
- name: Set up Node.js
59+
uses: actions/setup-node@v4
60+
with:
61+
node-version: "20"
62+
cache: npm
63+
cache-dependency-path: web/package-lock.json
64+
65+
- name: Install frontend deps
66+
run: cd web && npm ci
67+
68+
- name: Perform CodeQL analysis
69+
uses: github/codeql-action/analyze@v3
70+
with:
71+
category: /language:javascript-typescript

‎.github/workflows/dev-fast-ci.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Dev Fast CI
2+
3+
on:
4+
push:
5+
branches-ignore:
6+
- main
7+
workflow_dispatch:
8+
9+
concurrency:
10+
group: dev-fast-ci-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
fast-checks:
15+
name: Fast Checks
16+
runs-on: ubuntu-latest
17+
env:
18+
GITLEAKS_REPORT_PATH: build/reports/gitleaks-report.json
19+
steps:
20+
- uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
24+
- name: Set up Go
25+
uses: actions/setup-go@v5
26+
with:
27+
go-version-file: backend/go.mod
28+
cache-dependency-path: backend/go.sum
29+
30+
- name: Prepare Go tool bin
31+
run: |
32+
mkdir -p "$RUNNER_TEMP/bin"
33+
echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
34+
35+
- name: Set up Node.js
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: "20"
39+
cache: npm
40+
cache-dependency-path: web/package-lock.json
41+
42+
- name: Install frontend deps
43+
run: cd web && npm ci
44+
45+
- name: Install fast-check tools
46+
run: |
47+
set -euo pipefail
48+
GOBIN="$RUNNER_TEMP/bin" go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
49+
GOBIN="$RUNNER_TEMP/bin" go install golang.org/x/vuln/cmd/govulncheck@latest
50+
51+
GL_VERSION="8.24.2"
52+
ARCH="$(uname -m)"
53+
case "$ARCH" in
54+
x86_64) GL_ARCH="x64" ;;
55+
aarch64|arm64) GL_ARCH="arm64" ;;
56+
*) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
57+
esac
58+
curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GL_VERSION}/gitleaks_${GL_VERSION}_linux_${GL_ARCH}.tar.gz" \
59+
| tar -xz -C "$RUNNER_TEMP/bin" gitleaks
60+
61+
- name: Run fast lint
62+
run: make lint fast
63+
env:
64+
GOLANGCI_LINT_BIN: ${{ runner.temp }}/bin/golangci-lint
65+
66+
- name: Run fast backend tests
67+
run: make test backend fast
68+
69+
- name: Run frontend tests
70+
run: make test web
71+
72+
- name: Run fast security checks
73+
run: make sec fast
74+
env:
75+
GOVULNCHECK_BIN: ${{ runner.temp }}/bin/govulncheck
76+
GITLEAKS_BIN: ${{ runner.temp }}/bin/gitleaks
77+
GITLEAKS_REPORT_PATH: ${{ env.GITLEAKS_REPORT_PATH }}
78+
79+
- name: Upload fast CI gitleaks report
80+
if: always()
81+
uses: actions/upload-artifact@v4
82+
with:
83+
name: dev-fast-gitleaks-${{ github.sha }}
84+
path: ${{ env.GITLEAKS_REPORT_PATH }}
85+
if-no-files-found: ignore

‎.gitleaks.toml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
title = "AppOS gitleaks config"
2+
3+
[extend]
4+
useDefault = true
5+
6+
[[allowlists]]
7+
description = "Generated frontend build output"
8+
paths = [
9+
'''^web/dist/'''
10+
]
11+
12+
[[allowlists]]
13+
description = "BMAD file manifest stores content hashes, not credentials"
14+
paths = [
15+
'''^_bmad/_config/files-manifest\.csv$'''
16+
]
17+
18+
[[allowlists]]
19+
description = "Bundled skill docs use redacted or illustrative token examples"
20+
paths = [
21+
'''^\.agents/skills/.*/resources/knowledge/api-testing-patterns\.md$''',
22+
'''^\.agents/skills/wds-6-asset-generation/steps-p/step-01-load-context\.md$'''
23+
]
24+
25+
[[allowlists]]
26+
description = "Test fixtures use deterministic non-production placeholders"
27+
paths = [
28+
'''^backend/domain/certs/resolve_test\.go$''',
29+
'''^backend/domain/monitor/signals/agent/agent_test\.go$''',
30+
'''^backend/domain/monitor/signals/checks/credential_sweep_test\.go$''',
31+
'''^backend/domain/worker/monitoring_checks_test\.go$'''
32+
]
33+
regexes = [
34+
'''MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=''',
35+
'''-----BEGIN PRIVATE KEY-----''',
36+
]
37+
38+
[[allowlists]]
39+
description = "Deterministic development-only crypto fallback keys"
40+
paths = [
41+
'''^backend/infra/crypto/crypto\.go$''',
42+
'''^backend/domain/secrets/legacy_encryption\.go$'''
43+
]
44+
regexes = [
45+
'''0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'''
46+
]

0 commit comments

Comments
 (0)