Arsitektur CI/CD Pipeline AI-Assisted untuk Golang: Blueprint Lengkap

 1PRINSIP 1: FAIL FAST, FAIL CHEAP
 2  Step yang paling cepat dan paling sering fail harus dijalankan pertama.
 3
 4  Order: build → test → lint → architecture → AI review → spec audit
 5
 6  Rationale:
 7  - Build fail: paling sering, paling cepat (30 detik)
 8  - Test fail: sering, 2-5 menit
 9  - AI review: jarang block, 2 menit (tapi mahal relatif)
10  - Spec audit: jarang dijalankan, 1 menit
11
12  Jangan: jalankan spec audit sebelum test — sia-sia kalau test fail
13
14PRINSIP 2: PARALLEL WHERE POSSIBLE
15  Steps yang tidak saling dependent harus parallel.
16
17  Parallel group A (blocking):
18    go build, go test, golangci-lint, architecture-check
19
20  Parallel group B (informational, non-blocking awal):
21    AI review, PR description generation
22
23  Total wall time: max(group A) + security-scan
24  Bukan: sum semua steps
25
26PRINSIP 3: GRADUATED ENFORCEMENT
27  Bukan semua failure harus block merge dari hari pertama.
28
29  Level 1 (blocking dari hari pertama):
30    Build fail, test fail, critical security vulnerability
31
32  Level 2 (blocking setelah 2 sprint):
33    AI review CRITICAL issues, architecture violations
34
35  Level 3 (informational always):
36    AI review SUGGESTION, PR description quality

 1┌─────────────────────────────────────────────────────────────┐
 2│  LAYER 1: SYNTACTIC (Deterministik, Zero AI Cost)           │
 3│  go build | go test -race | go vet | golangci-lint          │
 4│  Waktu: 2-5 menit | Blocking: YES dari day 1                │
 5├─────────────────────────────────────────────────────────────┤
 6│  LAYER 2: SEMANTIC-STATIC (Custom Script, Zero AI Cost)     │
 7│  Architecture boundary | Import graph | Naming convention   │
 8│  Waktu: 30 detik | Blocking: YES (sprint 2+)                │
 9├─────────────────────────────────────────────────────────────┤
10│  LAYER 3: SEMANTIC-AI (LLM-Powered, Low Cost)               │
11│  Copilot PR review | Claude error pattern check             │
12│  Waktu: 2 menit (parallel) | Blocking: CRITICAL only        │
13├─────────────────────────────────────────────────────────────┤
14│  LAYER 4: SPEC COMPLIANCE (Spec Kit, Optional)              │
15│  specify audit | AC coverage | Contract validation          │
16│  Waktu: 1 menit | Blocking: jika score < 80                 │
17└─────────────────────────────────────────────────────────────┘

  1# .github/workflows/ci.yml — Full Structure
  2
  3name: CI — AI-Assisted Quality Pipeline
  4on:
  5  push:
  6    branches: [main, develop]
  7  pull_request:
  8    branches: [main, develop]
  9    types: [opened, synchronize, ready_for_review]
 10
 11# Satu env block untuk semua jobs
 12env:
 13  GO_VERSION: '1.22'
 14
 15jobs:
 16  # ============================================================
 17  # LAYER 1: SYNTACTIC — Always runs, blocks everything
 18  # ============================================================
 19
 20  syntactic:
 21    name: "L1: Build, Test & Lint"
 22    runs-on: ubuntu-latest
 23    outputs:
 24      status: ${{ job.status }}
 25    steps:
 26      - uses: actions/checkout@v4
 27      - uses: actions/setup-go@v5
 28        with: { go-version: '${{ env.GO_VERSION }}', cache: true }
 29      - name: Build
 30        run: go build ./...
 31      - name: Test
 32        run: go test -race -count=1 -timeout=5m ./...
 33      - name: Coverage gate
 34        run: |
 35          go test -coverprofile=cov.out ./...
 36          COVERAGE=$(go tool cover -func=cov.out | grep total | awk '{print $3}' | tr -d '%')
 37          echo "Coverage: ${COVERAGE}%"
 38          awk "BEGIN {exit ($COVERAGE >= 70) ? 0 : 1}" || \
 39            { echo "❌ Coverage below 70%"; exit 1; }
 40      - name: Vet
 41        run: go vet ./...
 42      - name: Lint
 43        uses: golangci/golangci-lint-action@v6
 44      - name: Security scan
 45        run: |
 46          go install github.com/securego/gosec/v2/cmd/gosec@latest
 47          gosec -severity medium -no-fail ./...
 48
 49  # ============================================================
 50  # LAYER 2: SEMANTIC-STATIC — Runs after L1, blocks merge
 51  # ============================================================
 52
 53  architecture:
 54    name: "L2: Architecture Boundary Check"
 55    runs-on: ubuntu-latest
 56    needs: syntactic
 57    steps:
 58      - uses: actions/checkout@v4
 59      - uses: actions/setup-go@v5
 60        with: { go-version: '${{ env.GO_VERSION }}' }
 61      - name: Check layer boundaries
 62        run: go run ./scripts/check-architecture.go ./...
 63      - name: Check dependency guard
 64        run: |
 65          # Ensure no cross-service internal imports
 66          go run ./scripts/check-monorepo-boundaries.go ./...
 67
 68  # ============================================================
 69  # LAYER 3: SEMANTIC-AI — Parallel with L4, PR only
 70  # ============================================================
 71
 72  ai-review:
 73    name: "L3: AI Semantic Review"
 74    runs-on: ubuntu-latest
 75    needs: syntactic          # hanya jalan setelah L1 pass
 76    if: |
 77      github.event_name == 'pull_request' &&
 78      !github.event.pull_request.draft
 79    permissions:
 80      pull-requests: write
 81      contents: read
 82    steps:
 83      - uses: actions/checkout@v4
 84        with: { fetch-depth: 0 }
 85      - name: Copilot PR Review
 86        uses: github/copilot-for-pull-requests@v1
 87        with:
 88          github-token: ${{ secrets.GITHUB_TOKEN }}
 89          review-instructions: |
 90            Review Go code per CLAUDE.md rules.
 91            CRITICAL (block): error not wrapped, float64 for money,
 92            architecture violations, _ ignoring errors.
 93            End with REVIEW_SCORE: X/100
 94
 95  pr-enrichment:
 96    name: "L3: PR Description & Metadata"
 97    runs-on: ubuntu-latest
 98    needs: syntactic
 99    if: |
100      github.event_name == 'pull_request' &&
101      github.event.action == 'opened'
102    permissions:
103      pull-requests: write
104      contents: read
105    env:
106      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
107    steps:
108      - uses: actions/checkout@v4
109        with: { fetch-depth: 0 }
110      - name: Generate PR description
111        uses: actions/github-script@v7
112        with:
113          script: |
114            // Auto-generate PR description (detail di Artikel 10)
115            console.log('PR description generation — see Article 10');
116
117  # ============================================================
118  # LAYER 4: SPEC COMPLIANCE — Parallel with L3, PR only
119  # ============================================================
120
121  spec-audit:
122    name: "L4: Spec Compliance Audit"
123    runs-on: ubuntu-latest
124    needs: syntactic
125    if: |
126      github.event_name == 'pull_request' &&
127      !github.event.pull_request.draft
128    steps:
129      - uses: actions/checkout@v4
130      - uses: actions/setup-node@v4
131        with: { node-version: '20' }
132      - name: Install specify CLI
133        run: npm install -g @santekno/spec-kit
134      - name: Run spec audit
135        run: specify audit --fail-on-score-below 80

 1Tidak semua pipeline perlu dijalankan di semua events.
 2Trigger yang salah = pipeline yang lambat dan mahal.
 3
 4EVENT: push ke feature branch
 5  Tujuan: fast feedback untuk developer yang sedang coding
 6  Run: Layer 1 only (build + test + lint)
 7  Tidak run: AI review (tidak ada PR), spec audit
 8  Waktu: 3-5 menit
 9
10EVENT: PR opened atau synchronize (commit baru ke PR)
11  Tujuan: quality gate sebelum code review
12  Run: Layer 1 + 2 + 3 + 4
13  Waktu: 7 menit (L1+L2 sequential, L3+L4 parallel)
14
15EVENT: push ke main atau develop
16  Tujuan: verify post-merge health
17  Run: Layer 1 + 2 (L3 dan L4 tidak relevan — PR sudah di-review)
18  Waktu: 5 menit
19
20EVENT: PR marked ready_for_review (dari draft)
21  Tujuan: run full pipeline untuk PR yang baru ready
22  Run: Layer 1 + 2 + 3 + 4 (full)
23  Waktu: 7 menit
24
25EVENT: schedule (nightly)
26  Tujuan: full health check + dependency update check
27  Run: Layer 1 + security deep scan
28  Waktu: 10 menit (comprehensive scan)

 1Biaya per pipeline run:
 2
 3Layer 1 (no AI cost):
 4  GitHub Actions: ~$0.002 (ubuntu runner, 5 menit)
 5  Total L1: $0.002
 6
 7Layer 2 (no AI cost):
 8  GitHub Actions: ~$0.001 (30 detik)
 9  Total L2: $0.001
10
11Layer 3 (AI cost):
12  Copilot PR review: sudah included di subscription
13  Claude PR description: ~500 tokens input, ~200 output
14    Cost: (500 × $0.80 + 200 × $4.00) / 1,000,000 = $0.0012
15  GitHub Actions: ~$0.001
16  Total L3: ~$0.002
17
18Layer 4 (no AI cost):
19  specify CLI: gratis
20  GitHub Actions: ~$0.001
21  Total L4: $0.001
22
23TOTAL per full pipeline run: ~$0.006
24
25Monthly estimate (24 PRs/week × 4 minggu = 96 PRs/bulan):
26  96 × $0.006 = $0.58/bulan
27  Plus GitHub Actions compute: ~$2/bulan
28
29  TOTAL: ~$2.60/bulan untuk tim 8 developer
30  (di luar Copilot subscription yang sudah ada)

 1santekno-shop/
 2├── .github/
 3│   ├── workflows/
 4│   │   ├── ci.yml              ← main pipeline (artikel ini)
 5│   │   ├── release.yml         ← release notes generator (artikel 11)
 6│   │   └── nightly.yml         ← scheduled security scan
 7│   ├── copilot-instructions.md ← AI review context
 8│   └── pull_request_template.md
 9├── scripts/
10│   ├── check-architecture.go   ← dari Topik 3
11│   ├── check-monorepo-boundaries.go
12│   └── review-bot/
13│       └── main.go             ← custom AI review (artikel 5)
14├── CLAUDE.md                   ← universal context
15├── .golangci.yml               ← lint configuration
16├── .gitleaks.toml              ← secret scan rules
17└── go.work                     ← workspace (jika monorepo)

 1# .golangci.yml — konfigurasi untuk Santekno Shop
 2
 3run:
 4  timeout: 5m
 5  go: '1.22'
 6  tests: true
 7
 8linters:
 9  enable:
10    # Core correctness
11    - errcheck          # check error yang tidak di-handle
12    - govet             # suspicious constructs
13    - staticcheck       # comprehensive static analysis
14    - unused            # unused code
15
16    # Go idioms
17    - gofmt             # formatting
18    - goimports         # import ordering
19    - misspell          # typo
20
21    # Performance
22    - prealloc          # slice preallocation
23    - bodyclose         # HTTP response body close check
24
25    # Security
26    - gosec             # security issues
27    - exhaustive        # switch exhaustiveness
28
29    # Custom rules
30    - depguard          # forbidden import paths
31    - gomodguard        # module usage rules
32
33linters-settings:
34  depguard:
35    rules:
36      main:
37        deny:
38          # Pastikan tidak ada cross-service internal import
39          - pkg: "github.com/santekno/santekno-shop/services/*/internal"
40            desc: "Cross-service internal imports forbidden. Use Kafka events."
41          # Pastikan tidak ada deprecated mock library
42          - pkg: "github.com/golang/mock"
43            desc: "Use go.uber.org/mock instead"
44
45  errcheck:
46    check-type-assertions: true
47    check-blank: true
48
49  govet:
50    enable-all: true
51
52issues:
53  exclude-rules:
54    # Test files boleh ignore errors
55    - path: _test\.go
56      linters: [errcheck]
57    # Generated files dikecualikan
58    - path: ".*\\.pb\\.go"
59      linters: [all]
60    - path: ".*mock.*\\.go"
61      linters: [all]
62
63  max-issues-per-linter: 50
64  max-same-issues: 3

 1# GitHub Secrets yang perlu di-setup:
 2
 3# Required untuk AI review via Claude API:
 4ANTHROPIC_API_KEY      # dari console.anthropic.com
 5
 6# Required untuk secret scanning:
 7# (tidak ada — gitleaks dan trufflehog tidak butuh secret)
 8
 9# Optional untuk extended features:
10SLACK_WEBHOOK          # untuk notifikasi deployment
11SONAR_TOKEN            # jika pakai SonarQube
12
13# Setup via GitHub CLI:
14gh secret set ANTHROPIC_API_KEY --body "sk-ant-xxx"
15gh secret set SLACK_WEBHOOK --body "https://hooks.slack.com/xxx"
16
17# Verify:
18gh secret list
19
20# Security best practices untuk secrets di CI:
21# 1. Minimal permissions — API key hanya untuk yang diperlukan
22# 2. Rotation schedule — rotate setiap 90 hari
23# 3. Environment scoping — production secrets hanya di production env
24# 4. Audit logs — monitor usage di Anthropic console
25
26# Environment protection (untuk production secrets):
27# GitHub → Settings → Environments → production → Protection rules
28# Required reviewers: [tech lead]
29# Restrict to protected branches: main only

 1# Cache yang significant untuk Go pipeline:
 2
 3# 1. Go module cache (paling impactful, 30-60 detik saved)
 4- uses: actions/setup-go@v5
 5  with:
 6    go-version: '1.22'
 7    cache: true          # ini saja sudah cache go modules
 8
 9# 2. golangci-lint cache (10-20 detik saved)
10- uses: golangci/golangci-lint-action@v6
11  with:
12    # Cache sudah built-in di action ini
13
14# 3. Build cache untuk custom scripts
15- uses: actions/cache@v4
16  with:
17    path: |
18      ~/.cache/go-build
19      ~/go/pkg/mod
20    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
21    restore-keys: |
22      ${{ runner.os }}-go-
23
24# 4. Node modules untuk specify CLI
25- uses: actions/cache@v4
26  with:
27    path: ~/.npm
28    key: ${{ runner.os }}-npm-specify-${{ hashFiles('package-lock.json') }}
29
30# Expected cache hit improvement:
31# Cold run (no cache): 8-12 menit
32# Warm run (cache hit): 3-5 menit
33# Savings: ~60% pipeline time

 1# Notifikasi yang useful (tidak overwhelming):
 2
 3# Pattern yang disarankan:
 4# - SUCCESS: tidak perlu notifikasi (developer tidak perlu distract)
 5# - FAILURE di main: notif ke Slack channel #engineering-alerts
 6# - FAILURE di PR: GitHub comment (auto dari Actions)
 7# - WEEKLY summary: digest di Slack #engineering
 8
 9# Workflow untuk Slack notification saat main fail:
10- name: Notify on main branch failure
11  if: failure() && github.ref == 'refs/heads/main'
12  uses: 8398a7/action-slack@v3
13  with:
14    status: failure
15    fields: repo,message,commit,author,workflow
16    text: ':red_circle: Main branch CI failed! Check immediately.'
17  env:
18    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
19
20# GitHub comment untuk PR failure (built-in dari Actions):
21# Ketika job fail, GitHub otomatis show di PR checks tab
22# Developer langsung lihat apa yang fail tanpa perlu Slack

 1# Dashboard metrics yang perlu di-track:
 2
 3# 1. Pipeline success rate (target: > 95%)
 4# Via GitHub Actions API:
 5gh run list --workflow=ci.yml --json conclusion \
 6  | jq '[.[] | select(.conclusion != null)] | {
 7      total: length,
 8      success: [.[] | select(.conclusion == "success")] | length
 9    } | .success / .total * 100 | floor'
10
11# 2. Average pipeline duration (target: < 10 menit)
12gh run list --workflow=ci.yml --json createdAt,updatedAt \
13  | jq '[.[] | ((.updatedAt | fromdateiso8601) - (.createdAt | fromdateiso8601))] | add / length / 60'
14
15# 3. Most common failure reason
16gh run list --workflow=ci.yml --status failure --json jobs \
17  | jq '[.[].jobs[] | select(.conclusion == "failure") | .name] | group_by(.) | map({job: .[0], count: length}) | sort_by(-.count) | .[0:5]'
18
19# Simpan metrics mingguan:
20# Spreadsheet atau Grafana dashboard
21# Review di sprint retrospective

 1Cara rollout pipeline baru tanpa disrupt development:
 2
 3PHASE 1 (Week 1): Shadow mode
 4  Pipeline baru berjalan parallel dengan pipeline lama
 5  Hasilnya hanya di-log, tidak block merge
 6  Tujuan: validate false positive rate
 7
 8PHASE 2 (Week 2-3): Warning mode
 9  Pipeline baru replace pipeline lama
10  Failures menjadi GitHub comments (tidak block)
11  Developer bisa lihat tapi tidak di-block
12  Tujuan: developer familiar dengan output format
13
14PHASE 3 (Week 4+): Enforcement mode
15  CRITICAL issues block merge
16  SUGGESTION tetap informational
17  Monitor: ada yang complain false positive?
18
19Cara implement shadow mode:
20  continue-on-error: true  # pada semua AI-related steps
21
22  # Setelah shadow period:
23  # Remove continue-on-error dari CRITICAL checks

 1Pipeline YAML adalah code — perlu diperlakukan seperti code:
 2
 31. PR untuk pipeline changes
 4   Perubahan ke .github/workflows/*.yml harus via PR
 5   Bukan langsung push ke main
 6
 72. Review oleh senior developer
 8   Pipeline affect semua developer — perlu careful review
 9
103. Testing di branch sebelum merge
11   Feature branch: buat perubahan pipeline
12   Test: push beberapa commits, verify pipeline behavior
13   Merge: setelah confirmed working
14
154. CHANGELOG untuk pipeline
16   Simpan changelog di .github/PIPELINE_CHANGELOG.md
17   Dokumentasikan setiap perubahan signifikan
18
195. Rollback plan
20   Tag pipeline state sebelum perubahan besar:
21   git tag pipeline-v1.0 (sebelum AI review ditambahkan)
22   git tag pipeline-v2.0 (setelah AI review)
23
24   Rollback: git checkout pipeline-v1.0 -- .github/workflows/

 1Security considerations untuk pipeline yang aman:
 2
 3PERMISSIONS (principle of least privilege):
 4  Default untuk semua jobs:
 5    permissions:
 6      contents: read  # read-only by default
 7
 8  Override per-job hanya yang butuh:
 9    ai-review job:
10      permissions:
11        pull-requests: write  # untuk post comment
12        contents: read
13
14    pr-enrichment job:
15      permissions:
16        pull-requests: write
17        contents: read
18
19SECRETS:
20  - Jangan expose secrets di logs
21  - Gunakan ${{ secrets.XXX }} bukan environment variable hardcode
22  - secrets.GITHUB_TOKEN: auto-generated, scope minimal
23
24THIRD-PARTY ACTIONS:
25  - Pin ke commit hash, bukan tag floating
26  - Verified creator actions lebih aman
27
28  BAD:  uses: some-action@main
29  OK:   uses: some-action@v1
30  BEST: uses: some-action@abc123def456  # pinned commit
31
32RUNNER:
33  - ubuntu-latest untuk non-sensitive
34  - Self-hosted runner untuk sensitive secrets
35  - Isolated environment via container untuk high-security

 1# STARTER TEMPLATE: .github/workflows/ci.yml
 2# Copy ini, customise, dan extend di artikel-artikel berikutnya
 3
 4name: CI — Santekno Shop
 5on:
 6  push:
 7    branches: [main, develop]
 8  pull_request:
 9    branches: [main, develop]
10    types: [opened, synchronize, ready_for_review]
11
12env:
13  GO_VERSION: '1.22'
14
15jobs:
16  # Layer 1: Core Go checks
17  go-quality:
18    name: Go Quality Gates
19    runs-on: ubuntu-latest
20    steps:
21      - uses: actions/checkout@v4
22      - uses: actions/setup-go@v5
23        with: { go-version: '${{ env.GO_VERSION }}', cache: true }
24      - run: go build ./...
25      - run: go test -race -count=1 ./...
26      - run: go vet ./...
27      - uses: golangci/golangci-lint-action@v6
28
29  # Layer 2: Architecture (kita tambahkan di artikel berikutnya)
30  # architecture-check: ...
31
32  # Layer 3: AI Review (artikel 03 dan seterusnya)
33  # ai-review: ...
34
35  # Layer 4: Spec Audit (artikel 04)
36  # spec-audit: ...

 1Perbandingan dengan pipeline standard di komunitas Go:
 2
 3STANDARD Go pipeline (mayoritas tim):
 4  ✅ build, test, vet, lint
 5  ❌ architecture enforcement
 6  ❌ AI review
 7  ❌ spec compliance
 8  ❌ PR description generation
 9
10ADVANCED Go pipeline (10% tim):
11  ✅ semua di atas
12  ✅ security scanning (gosec, snyk)
13  ✅ coverage gate
14  ❌ AI review
15  ❌ spec compliance
16
17SANTEKNO AI-AUGMENTED (apa yang kita bangun):
18  ✅ semua di atas
19  ✅ architecture enforcement (custom script)
20  ✅ AI semantic review (Copilot + Claude)
21  ✅ spec compliance (Spec Kit)
22  ✅ PR description generation
23  ✅ cost monitoring
24  ✅ graduated enforcement
25
26Posisi kompetitif:
27  Mayoritas tim Go di Indonesia: Standard pipeline
28  Target kita: AI-Augmented yang belum banyak diterapkan
29
30  Membangun ini sekarang = 12-18 bulan head start
31  sebelum ini menjadi "standard" industri

 1Roadmap implementasi sepanjang Topik 4:
 2
 3SEKARANG (Artikel 2):
 4  ✅ Blueprint arsitektur (artikel ini)
 5  ✅ Skeleton workflow YAML
 6  ✅ Directory structure
 7
 8ARTIKEL 3 (next):
 9  Claude Code setup di GitHub Actions
10  Environment, auth, CLAUDE.md access
11  Basic Claude API call dari CI
12
13ARTIKEL 4:
14  Spec validation integration
15  specify audit di pipeline
16
17ARTIKEL 5-9 (Part 2):
18  Quality gates: AI review, security, coverage, architecture
19
20ARTIKEL 10-14 (Part 3):
21  Automation: PR description, changelog, migration check
22
23ARTIKEL 15-20 (Part 4):
24  LLMOps: prompt versioning, cost monitoring, incident playbook