Skip to content

GitHub Secrets and Variables Setup

This document explains how to configure GitHub Actions secrets and variables for the zer0-mistakes theme repository.

Required Configuration

🔐 Repository Secrets

Navigate to: Repository Settings → Secrets and variables → Actions → Secrets

Secret Name Description How to Get
DOCKER_USERNAME Docker Hub username Your Docker Hub login username
DOCKER_TOKEN Docker Hub access token Create at Docker Hub → New Access Token
RUBYGEMS_API_KEY RubyGems API key (for releases) Get from RubyGems
ANTHROPIC_API_KEY Shared Claude key — powers the AI chat proxy (deploy-chat-proxy.yml) and the content reviewer's Claude agent tier (ai-content-review.yml). Optional: both features are gated on its presence and skip gracefully without it. Use a workspace-scoped key with a spend cap (it feeds a public chat proxy and CI agent runs). Get from console.anthropic.com → API keys
XAI_API_KEY Optional — lets the chat proxy answer with Grok instead of (or as well as) Claude. Not read by any workflow yet: set it on the Worker with wrangler secret put XAI_API_KEY and pin CHAT_PROVIDER = "xai" in wrangler.toml (see templates/deploy/chat-proxy/README.md). Locally it goes in .env or is pasted on the Site Builder's Connect step. Get from console.x.ai → API keys
CLOUDFLARE_API_TOKEN Deploy the chat proxy Worker (deploy-chat-proxy.yml). Optional — only needed if you deploy the AI chat proxy. Create at Cloudflare → "Edit Cloudflare Workers"
CLOUDFLARE_ACCOUNT_ID Cloudflare account id for the chat-proxy deploy. Optional. Cloudflare dashboard → Workers & Pages (right sidebar)

📝 Repository Variables

Navigate to: Repository Settings → Secrets and variables → Actions → Variables

Variable Name Default Value Description
DOCKER_IMAGE amrabdel/zer0-mistakes Full Docker Hub image path
PAGES_REPO_NWO ${{ github.repository }} Repository name for jekyll-github-metadata

Note: Variables are optional. Workflows use sensible defaults if not set.

Docker Hub Setup

1. Create Docker Hub Access Token

  1. Log in to Docker Hub
  2. Go to Account Settings → Security → New Access Token
  3. Name: github-actions-zer0-mistakes
  4. Access permissions: Read, Write, Delete
  5. Copy the token immediately (shown only once)

2. Add to GitHub Secrets

# Using GitHub CLI
gh secret set DOCKER_USERNAME --body "amrabdel"
gh secret set DOCKER_TOKEN --body "dckr_pat_your_token_here"

Or add via GitHub UI:

  1. Go to repository Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Add DOCKER_USERNAME and DOCKER_TOKEN

3. Set Variables (Optional)

# Using GitHub CLI
gh variable set DOCKER_IMAGE --body "amrabdel/zer0-mistakes"
gh variable set PAGES_REPO_NWO --body "bamr87/zer0-mistakes"

How Workflows Use These Values

TEST (Latest Dependencies) Workflow

env:
  # Uses variable if set, otherwise default
  DOCKER_IMAGE: ${{ vars.DOCKER_IMAGE || 'amrabdel/zer0-mistakes' }}
  PAGES_REPO_NWO: ${{ vars.PAGES_REPO_NWO || github.repository }}

Docker Login Step

- name: Login to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_TOKEN }}

Workflow Triggers

Workflow Publishes Docker Image? When
test-latest.yml ✅ Yes Push to main, daily schedule
ci.yml ❌ No All PRs and pushes
release.yml ❌ No (RubyGems only) Version tags

Forking This Repository

If you fork this repository, you'll need to:

  1. Create your own Docker Hub repository
  2. Go to Docker Hub

  3. Create repository: yourusername/zer0-mistakes

  4. Set up secrets in your fork

gh secret set DOCKER_USERNAME --body "yourusername"
gh secret set DOCKER_TOKEN --body "your_token"
  1. Set variables in your fork
gh variable set DOCKER_IMAGE --body "yourusername/zer0-mistakes"
gh variable set PAGES_REPO_NWO --body "yourusername/zer0-mistakes"

Troubleshooting

Docker Login Failed

Error: unauthorized: incorrect username or password

Solutions:

  1. Verify DOCKER_USERNAME matches your Docker Hub username exactly
  2. Regenerate DOCKER_TOKEN - tokens expire or may be revoked
  3. Check the token has Read, Write permissions

Jekyll Build Fails with "No repo name found"

Error: No repo name found. Specify using PAGES_REPO_NWO environment variables

Solution: Ensure PAGES_REPO_NWO is set in workflow env or repository variables.

Image Push Failed

Error: denied: requested access to the resource is denied

Solutions:

  1. Verify the Docker Hub repository exists
  2. Check your token has write permissions
  3. Ensure DOCKER_IMAGE matches your Docker Hub repo path

Security Best Practices

  • ✅ Use access tokens, never passwords
  • ✅ Set minimal required permissions on tokens
  • ✅ Rotate tokens periodically
  • ✅ Use repository secrets, not hardcoded values
  • ❌ Never commit secrets to code
  • ❌ Never log secret values in workflows

Local Docker Publishing

You can also publish Docker images locally using your .env file.

Setup Local Publishing

  1. Configure .env file
# Copy example and edit
cp .env.example .env

# Add your Docker Hub credentials
DOCKER_USERNAME=yourusername
DOCKER_TOKEN=dckr_pat_your_token_here
DOCKER_IMAGE=yourusername/zer0-mistakes
  1. Get Docker Hub Access Token
  2. Go to Docker Hub Security Settings
  3. Click New Access Token
  4. Name: local-development
  5. Permissions: Read, Write
  6. Copy token to .env file

Publish Commands

# Build and push with auto-generated tag (recommended)
./scripts/docker-publish

# Build and push with specific tag
./scripts/docker-publish --tag v0.20.5

# Also update :latest tag
./scripts/docker-publish --latest

# Preview without making changes
./scripts/docker-publish --dry-run

# Build only (don't push)
./scripts/docker-publish --build-only

Using Docker Compose

# Build publishable image
docker compose -f docker-compose.yml -f docker-compose.publish.yml build publish

# Set custom tag
IMAGE_TAG=v0.20.5 docker compose -f docker-compose.yml -f docker-compose.publish.yml build publish

Verify Publication

# Check Docker Hub for your image
open "https://hub.docker.com/r/$(grep DOCKER_IMAGE .env | cut -d= -f2)/tags"

# Pull and test the image
docker pull yourusername/zer0-mistakes:latest

Quick Reference

# List current secrets (names only)
gh secret list

# List current variables
gh variable list

# Set a secret
gh secret set SECRET_NAME --body "value"

# Set a variable
gh variable set VAR_NAME --body "value"

# Delete a secret
gh secret delete SECRET_NAME

# Delete a variable
gh variable delete VAR_NAME

# Local Docker publishing
./scripts/docker-publish --help