windows-iac-vm-tooling/docs/02-prerequisites/secrets.md

🔐 Secret Management

Overview

This document describes how to configure required secrets for the CI/CD pipeline. All secrets should be stored securely in Forgejo and never committed to the repository.

---

Required Secrets

Secret Name	Description	Used By	Required
PFX_PASS	Code signing certificate password	osslsigncode	✅ Yes
PM_TOKEN_ID	Proxmox API token ID	OpenTofu	✅ Yes
PM_TOKEN_SECRET	Proxmox API token secret	OpenTofu	✅ Yes
WIN_ADMIN_PASS	Windows Administrator password	Ansible	✅ Yes

---

Forgejo Configuration

Accessing Secrets

1. Navigate to your Forgejo repository
2. Go to Settings → Secrets
3. Add each secret with the exact names listed below

Required Secrets List

graph TD
    subgraph Forgejo["Forgejo Settings"]
        Settings["Settings"] --> Secrets["Secrets"]
        Secrets --> Add["Add Secret"]
        Add --> |"Enter Name & Value"| Created[Secret Created]
    end
    
    subgraph CreatedSecrets["Configured Secrets"]
        PFX["🔐 PFX_PASS"]
        PM_ID["🔑 PM_TOKEN_ID"]
        PM_SEC["🔑 PM_TOKEN_SECRET"]
        WIN["🪟 WIN_ADMIN_PASS"]
    end
    
    Created --> PFX
    Created --> PM_ID
    Created --> PM_SEC
    Created --> WIN
    
    style Forgejo fill:#e1f5fe
    style CreatedSecrets fill:#e8f5e9

---

Proxmox API Token

Create API Token

1. SSH to Proxmox host:

   ssh root@la-vmh-07
   

2. Navigate to API Tokens:

   • Go to Datacenter → API Tokens
   • Click Add

3. Configure Token:

   Token Name: forgejo-automation
   User: root@pam
   Expiration: 31-12-2026 (or never)
   Privileges: VM.Admin (or Administrator)
   

4. Save Credentials:

   Token ID: root@pam!forgejo-automation
   Secret: <YOUR_SECRET_VALUE>
   

Set Environment Variables

# In Forgejo workflow or local environment
export PM_API_TOKEN_ID="root@pam!forgejo-automation"
export PM_API_TOKEN_SECRET="<your-token-secret>"

---

Code Signing Certificate

Certificate Requirements

Property	Value
Format	PKCS#12 (.pfx or .p12)
Algorithm	SHA-256
Timestamp Server	http://timestamp.digicert.com

Prepare Certificate

# Verify certificate
openssl pkcs12 -in cert.pfx -info -noout

# Extract for use (if needed)
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -out key.pem

Set Password Secret

# Set PFX_PASS secret in Forgejo
export PFX_PASS="your-certificate-password"

---

Windows Administrator Password

Requirements

Property	Value
Account	Administrator
Complexity	Windows complexity requirements
Length	Minimum 12 characters

Configuration in Autounattend.xml

The password is configured in packer/Autounattend.xml:

<UserAccounts>
  <AdministratorPassword>
    <Value>PackerPassword123!</Value>
    <PlainText>true</PlainText>
  </AdministratorPassword>
</UserAccounts>

Ansible Integration

# ansible/pipeline.yml
- name: Verify Installer
  hosts: windows_vm
  vars:
    ansible_user: Administrator
    ansible_password: "{{ lookup('env', 'WIN_ADMIN_PASS') }}"

---

Security Best Practices

flowchart LR
    subgraph BestPractices["Security Guidelines"]
        direction TB
        NeverCommit["❌ Never commit secrets to git"]
        RotateKeys["🔄 Rotate keys regularly"]
        UseVault["🔐 Use Forgejo Secrets"]
        LimitScopes["📊 Limit token privileges"]
        AuditLogs["📝 Audit access logs"]
    end
    
    NeverCommit --> RotateKeys
    RotateKeys --> UseVault
    UseVault --> LimitScopes
    LimitScopes --> AuditLogs
    
    style BestPractices fill:#ffebee

Practice	Description
Never commit secrets	Use .gitignore for .pfx, .env files
Rotate keys	Rotate Proxmox tokens quarterly
Use Forgejo Secrets	Store all secrets in Forgejo settings
Limit scopes	Use minimum required privileges
Audit access	Review Proxmox API access logs

---

Environment Variables Mapping

Secret	Env Var	Usage
PFX_PASS	PFX_PASS	osslsigncode command
PM_TOKEN_ID	PM_API_TOKEN_ID	OpenTofu provider
PM_TOKEN_SECRET	PM_API_TOKEN_SECRET	OpenTofu provider
WIN_ADMIN_PASS	ANSIBLE_PASSWORD	Ansible connection

---

Troubleshooting

Issue	Cause	Solution
Token invalid	Token expired	Create new token in Proxmox
Permission denied	Insufficient privileges	Add VM.Admin to token
Password rejected	Windows complexity	Use stronger password
Certificate invalid	Wrong format	Convert to PKCS#12

---

Next Steps

Goal	Next Document
Configure ISOs	ISO Requirements
Build template	Packer Configuration
View architecture	Architecture Overview

---

← Documentation Index | → ISO Requirements | ← Architecture