managarten/cicd/IMPLEMENTATION_CHECKLIST.md

Private Repo Access - Implementation Checklist

Issue: Docker builds fail due to private repo mana-core-nestjs-package access Solution: Pass GitHub token to Docker builds via secrets Time Required: 10-15 minutes

---

Checklist

Step 1: Create Personal Access Token (PAT)

• Go to GitHub Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
• Click "Generate new token"
• Set token name: CI-Private-Repo-Access
• Set expiration: 1 year
• Repository access: "Only select repositories" → Memo-2023/mana-core-nestjs-package
• Permissions:
  • Repository permissions → Contents → Read
  • Repository permissions → Metadata → Read (auto-selected)
• Click "Generate token"
• Copy token (starts with github_pat_...)

Calendar Reminder: Set reminder 1 week before token expires to rotate

---

Step 2: Add Secret to GitHub Repository

• Navigate to https://github.com/Memo-2023/manacore-monorepo/settings/secrets/actions
• Click "New repository secret"
• Name: PRIVATE_REPO_TOKEN
• Value: Paste the PAT from Step 1
• Click "Add secret"

Verification: Secret should appear in the list (value is hidden)

---

Step 3: Update CI Workflow

• Open .github/workflows/ci-main.yml
• Find the "Build and push" step (around line 126)
• Add these 2 lines after build-args: section:

secrets: |
  github_token=${{ secrets.PRIVATE_REPO_TOKEN }}

Complete example:

- name: Build and push
  if: steps.check-dockerfile.outputs.exists == 'true'
  uses: docker/build-push-action@v5
  with:
    context: .
    file: ${{ matrix.service.path }}/Dockerfile
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}
    cache-from: type=gha
    cache-to: type=gha,mode=max
    build-args: |
      NODE_ENV=production
      PORT=${{ matrix.service.port }}
    secrets: |
      github_token=${{ secrets.PRIVATE_REPO_TOKEN }}

• Save file
• Commit: git commit -m "ci: add GitHub token secret for private repo access"

---

Step 4: Verify Implementation

Local Testing (Optional):

# Export token
export GITHUB_TOKEN="github_pat_YOUR_TOKEN"

# Test maerchenzauber
docker build \
  --secret id=github_token,env=GITHUB_TOKEN \
  -t test-maerchenzauber \
  -f apps/maerchenzauber/apps/backend/Dockerfile \
  .

# Test manadeck
docker build \
  --secret id=github_token,env=GITHUB_TOKEN \
  -t test-manadeck \
  -f apps/manadeck/apps/backend/Dockerfile \
  .

• Local builds succeed (if testing locally)

CI Testing:

• Push changes to test branch
• Check GitHub Actions workflow run
• Verify build logs show: "Using GitHub token for private repo access"
• Verify no "exit code 128" errors
• Verify Docker images pushed to ghcr.io

---

Success Criteria

• ✅ GitHub secret PRIVATE_REPO_TOKEN exists
• ✅ CI workflow file updated with secrets section
• ✅ Build logs show "Using GitHub token for private repo access"
• ✅ Git clone succeeds without authentication errors
• ✅ Tarball creation succeeds: "Mana-core packaged as tarball"
• ✅ Docker images build and push successfully
• ✅ Both maerchenzauber-backend and manadeck-backend images available in ghcr.io

---

Troubleshooting

Problem: "No GitHub token provided" in logs

• Fix: Check secret exists and workflow syntax is correct

Problem: "git clone failed: exit code 128"

• Fix: Token expired or has wrong permissions - regenerate PAT

Problem: "Permission denied (publickey)"

• Fix: Check Dockerfile uses HTTPS URLs, not SSH

---

What This Fixes

Affected Services:

• ✅ apps/maerchenzauber/apps/backend
• ✅ apps/manadeck/apps/backend

Impact:

• Docker builds will succeed in CI
• Images will auto-push to ghcr.io
• Unblocks deployment to staging/production
• No changes needed to local development workflow

---

Maintenance

Token Rotation (Annual):

1. Generate new PAT (same permissions)
2. Update GitHub secret value
3. Old token automatically revoked
4. No code changes needed

Monitoring:

• GitHub sends email 1 week before PAT expires
• Set calendar reminder as backup

---

Related Documentation

• Full Solution Guide: PRIVATE_REPO_ACCESS_SOLUTION.md
• Issue Tracker: IMMEDIATE_FIXES_NEEDED.md
• CI/CD Setup: SETUP.md

---

Estimated Implementation Time: 10-15 minutes Risk Level: LOW (proven pattern) Rollback: Remove secrets section from workflow