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

📝 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¶

Log in to Docker Hub
Go to Account Settings → Security → New Access Token
Name: github-actions-zer0-mistakes
Access permissions: Read, Write, Delete
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 }}

- 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:

Create your own Docker Hub repository
Go to Docker Hub
Create repository: yourusername/zer0-mistakes

Set up secrets in your fork

gh secret set DOCKER_USERNAME --body "yourusername"
gh secret set DOCKER_TOKEN --body "your_token"

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¶

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¶

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

Get Docker Hub Access Token
Go to Docker Hub Security Settings
Click New Access Token
Name: local-development
Permissions: Read, Write
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