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

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

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

Add secrets:
- `REGISTRY_USERNAME` - Registry username
- `REGISTRY_PASSWORD` - Registry password/token

Update login step:
```yaml
- 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)**
```bash
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:
   ```yaml
   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:
   ```bash
   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:
   ```yaml
   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:

```bash
git tag v1.0.0
git push origin v1.0.0
```

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