turbovault-app/.github/SECRETS_SETUP.md

GitHub Secrets Setup

This guide explains how to configure GitHub Secrets for the CI/CD workflows.

Default: GitHub Container Registry

Good news! The default workflow uses GitHub Container Registry (ghcr.io), which requires no secrets to set up. It uses the built-in GITHUB_TOKEN automatically.

Just push a tag and it works:

git tag v1.0.0
git push origin v1.0.0

Your image will be at: ghcr.io/YOUR_USERNAME/turbovault:v1.0.0

Optional: Use a Different Registry

If you want to use a different registry (Docker Hub, private registry, etc.), you'll need to modify the workflow and add secrets.

Example: Docker Hub

Edit .github/workflows/build-and-push.yml:

env:
  REGISTRY: docker.io
  IMAGE_NAME: your-username/turbovault

Add secrets:

• DOCKERHUB_USERNAME - Your Docker Hub username
• DOCKERHUB_TOKEN - Access token from Docker Hub

Update login step:

- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

Example: Private Registry

Edit .github/workflows/build-and-push.yml:

env:
  REGISTRY: registry.example.com
  IMAGE_NAME: turbovault

Add secrets:

• REGISTRY_USERNAME - Registry username
• REGISTRY_PASSWORD - Registry password/token

Update login step:

- name: Log in to Registry
  uses: docker/login-action@v3
  with:
    registry: ${{ secrets.REGISTRY_URL }}
    username: ${{ secrets.REGISTRY_USERNAME }}
    password: ${{ secrets.REGISTRY_PASSWORD }}

Verify Setup

Test the Workflow

Option A: Create a tag (triggers automatically)

git tag v1.0.0
git push origin v1.0.0

The workflow will automatically build and push to GitHub Container Registry.

Option B: Manual trigger

1. Go to Actions tab
2. Click Build and Push Docker Image
3. Click Run workflow
4. Enter tag: test
5. Click Run workflow
6. Watch the build progress

View Your Images

GitHub Container Registry:

1. Go to your GitHub profile
2. Click Packages tab
3. You'll see turbovault package
4. Images are at: ghcr.io/YOUR_USERNAME/turbovault:TAG

Troubleshooting

Error: "denied: permission_denied"

Cause: GitHub Container Registry permissions issue

Fix:

1. Make sure your repository has packages: write permission
2. The workflow already has this set:

   permissions:
     contents: read
     packages: write
   

Error: "unable to login to registry"

Cause: Using custom registry without proper credentials

Fix:

1. Verify secrets are set correctly
2. Test locally:

   docker login your-registry.com
   

3. Update workflow with correct registry URL and credentials

Workflow doesn't trigger

Cause: Wrong tag format

Fix:

• Workflow triggers on tags like v1.0.0, v2.1.0
• Must start with v
• Or use manual trigger (workflow_dispatch)

Image not appearing in packages

Cause: First time pushing to ghcr.io

Fix:

1. Go to your GitHub profile → Packages
2. Find turbovault package
3. Click Package settings
4. Make it public (if desired):
   • Change visibility to Public
5. Link to repository for better discoverability

Security Best Practices

✅ DO:

• Use access tokens (not passwords)
• Set minimum required permissions
• Rotate tokens regularly
• Use organization secrets for team projects
• Use GitHub Container Registry (free, built-in, secure)

❌ DON'T:

• Commit secrets to repository
• Share tokens publicly
• Use personal passwords
• Give tokens more permissions than needed

Advanced: Environment Secrets

For multiple environments (staging, production):

1. Create Environments in GitHub:

   • Settings → Environments → New environment
   • Name: production

2. Add environment-specific secrets:

   • PRODUCTION_GITEA_TOKEN
   • STAGING_GITEA_TOKEN

3. Update workflow to use environment:

   jobs:
     build:
       environment: production
       steps:
         - run: echo "${{ secrets.PRODUCTION_GITEA_TOKEN }}"
   

Workflow Files

Your repository includes these workflows:

.github/workflows/build-and-push.yml

• Triggers: Git tags (v*) or manual
• Purpose: Build Docker image and push to GitHub Container Registry
• Required secrets: None (uses built-in GITHUB_TOKEN)

.github/workflows/ci.yml

• Triggers: Push to main/develop, Pull Requests
• Purpose: Run tests, linting, security scans
• Required secrets: None (RAILS_MASTER_KEY optional)

Getting Started Checklist

Using GitHub Container Registry (Default - No Setup Required!)

• Push code to GitHub
• Create a tag: git tag v1.0.0 && git push origin v1.0.0
• Watch Actions tab for the build
• View image in GitHub Packages
• Update k8s deployment with new image
• Deploy to Kubernetes

Using Custom Registry (Optional)

• Create registry access token
• Add registry secrets to GitHub
• Modify .github/workflows/build-and-push.yml
• Test workflow manually
• Verify image appears in your registry
• Deploy to Kubernetes

Support

If you encounter issues:

1. Check the Actions logs: https://github.com/YOUR_USERNAME/turbovault/actions
2. Read the error messages carefully
3. For custom registries, test login locally first
4. Open an issue if you're stuck

---

Next Steps: Create a tag to trigger your first build:

git tag v1.0.0
git push origin v1.0.0

Then check the Actions tab and Packages tab to see your image! 🚀