Trigger website update after mirror list changes

[zeha]

I tend to forget triggering the grml.org deploy job after accepting a PR in this repo. Would be nice to automate this.

[zeha]

Plan: Automate grml.org Website Deployment After Mirror List Changes

Problem Statement

When a PR is merged in the grml-mirrors repository, the grml.org website deployment needs to be triggered to reflect the updated mirror list. Currently, this is a manual step that is often forgotten (GitHub Issue #43).

Current State

• grml-mirrors repo: No GitHub Actions workflows exist yet
• grml.org repo: Has hugo-deploy.yml workflow that:
  • Triggers on push to master branch
  • Can be manually triggered via workflow_dispatch
  • Builds Hugo site and triggers deployment to production environment

Proposed Options

Option 1: Workflow Dispatch Trigger (Recommended)

Description: Create a GitHub Actions workflow in grml-mirrors that automatically triggers the grml.org deployment workflow when changes are merged to master.

How it works:

• Add workflow in grml-mirrors at .github/workflows/trigger-website-deploy.yml
• Triggers on push to master branch
• Uses GitHub API to trigger workflow_dispatch event on grml.org's hugo-deploy.yml
• Requires a GitHub token with repo or actions:write scope

Pros:

• Fully automated, zero manual intervention needed
• Uses existing grml.org workflow (no changes to grml.org needed)
• Clean separation of concerns
• Easy to disable if needed

Cons:

• Requires creating and storing a GitHub Personal Access Token or GitHub App token as a secret
• Adds dependency between repositories

Implementation:

1. Create .github/workflows/ directory in grml-mirrors
2. Add workflow file that triggers on push to master
3. Add secret GRML_ORG_DEPLOY_TOKEN to grml-mirrors repository
4. Workflow makes API call to trigger grml.org deployment

---

Option 2: Repository Dispatch Event

Description: Use GitHub's repository_dispatch custom event to trigger deployment.

How it works:

• grml-mirrors workflow sends a repository_dispatch event to grml.org
• grml.org's hugo-deploy.yml is modified to also listen for this custom event
• Similar token requirements as Option 1

Pros:

• More flexible - can pass custom payload data
• Can be used for other automation triggers in the future

Cons:

• Requires modifying grml.org's workflow file
• More complex setup
• Still requires GitHub token

---

Option 3: Automated Reminder (Simple Alternative)

Description: Create a workflow that posts a reminder comment when PRs are merged.

How it works:

• Workflow triggers on PR merge to master
• Posts a comment on the PR with link to manually trigger grml.org deployment
• Optionally creates a GitHub issue as a reminder

Pros:

• No tokens required
• Very simple implementation
• No cross-repo dependencies
• User maintains control over when deployment happens

Cons:

• Not fully automated - still requires manual step
• Can be ignored/forgotten

---

Recommendation

Option 1 (Workflow Dispatch Trigger) with Organization-level Secret is the best solution because:

• It fully solves the problem (zero manual intervention)
• Uses the existing grml.org workflow without modifications
• Simple and straightforward implementation
• Easy to maintain and debug
• Organization-level secrets are more secure and manageable than repo-level

Alternative if no token storage is acceptable:

• Option 3 (Automated Reminder) is the only truly token-less solution
• Still requires manual trigger, but provides automated reminders so you won't forget
• Can include direct link to trigger deployment in the reminder message

Implementation Plan

Phase 1: Create Organization-level Secret

Steps to create the fine-grained PAT:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click "Generate new token"
3. Configure:
   • Name: "grml-mirrors-website-deploy"
   • Expiration: 1 year (or custom)
   • Repository access: Only select repositories → grml.org
   • Permissions:
     • Actions: Read and write (to trigger workflow_dispatch)
4. Generate and copy the token

Steps to add as organization secret:

1. Go to grml organization Settings → Secrets and variables → Actions
2. Click "New organization secret"
3. Name: GRML_ORG_DEPLOY_TOKEN
4. Paste the token value
5. Repository access: Select "grml-mirrors" repository only (for maximum security)

Phase 2: Create GitHub Actions Workflow

Files to Create:

• .github/workflows/trigger-website-deploy.yml in grml-mirrors repository

Security Protections Against Fork Exposure:

GitHub provides multiple layers of protection to prevent secrets from being exposed to forks:

1. GitHub's Built-in Protection (Default):

   • Organization and repository secrets are NEVER available to workflows triggered from forked repositories
   • Pull requests from forks run with GITHUB_TOKEN with read-only permissions
   • This is a GitHub security policy that cannot be bypassed

2. Our Workflow Configuration (Extra Protection):

   • Workflow only triggers on push to master, NOT on pull_request events
   • Includes explicit check: if: github.repository == 'grml/grml-mirrors'
   • This ensures the job won't run even if someone copies the workflow to a fork

3. Organization Secret Configuration (Recommended):

   • When creating the organization secret, explicitly select only "grml-mirrors" repository access
   • This prevents the secret from being available to any other repositories

Result: The secret cannot be exposed to forks through pull requests or any other mechanism.

Workflow Content (.github/workflows/trigger-website-deploy.yml):

name: Trigger Website Deployment

on:
  push:
    branches: [master]

jobs:
  trigger-deploy:
    # Only run on the main repository, not on forks
    if: github.repository == 'grml/grml-mirrors'
    runs-on: ubuntu-latest
    steps:
      - name: Trigger grml.org deployment
        run: |
          curl -X POST \
            -H "Accept: application/vnd.github.v3+json" \
            -H "Authorization: token ${{ secrets.GRML_ORG_DEPLOY_TOKEN }}" \
            https://api.github.com/repos/grml/grml.org/actions/workflows/hugo-deploy.yml/dispatches \
            -d '{"ref":"master"}'

      - name: Report success
        if: success()
        run: echo "✓ Successfully triggered grml.org deployment"

      - name: Report failure
        if: failure()
        run: |
          echo "✗ Failed to trigger grml.org deployment"
          echo "Please check the GRML_ORG_DEPLOY_TOKEN secret and permissions"
          exit 1

Phase 3: Testing and Verification

Initial Setup Verification:

1. After creating the workflow, push directly to a test branch first
2. Manually trigger the workflow from Actions tab to test
3. Check grml.org Actions tab to confirm deployment was triggered
4. Verify token permissions are correct

Production Verification:

1. Merge a PR to grml-mirrors master branch
2. Check grml-mirrors Actions tab - workflow should run automatically
3. Check grml.org Actions tab - deployment should be triggered
4. Wait for deployment to complete
5. Verify website at https://grml.org/ reflects mirror changes

Rollback Plan

If automation causes issues:

1. Delete or disable the workflow file in grml-mirrors
2. Return to manual triggering of grml.org deployment

Critical Files

• New: .github/workflows/trigger-website-deploy.yml (grml-mirrors)
• Reference: .github/workflows/hugo-deploy.yml (grml.org - no changes needed)

---

Summary

This plan implements Option 1: Workflow Dispatch Trigger with Organization-level Secret to automatically trigger the grml.org website deployment whenever changes are merged to the master branch in grml-mirrors.

What you'll need to do manually (one-time setup):

1. Create a fine-grained GitHub Personal Access Token with Actions permissions for grml.org repo
2. Add it as an organization secret named GRML_ORG_DEPLOY_TOKEN

What the automation will do:

• Automatically trigger grml.org deployment on every merge to master
• No more forgetting to deploy the website
• Clear success/failure reporting in Actions tab

Benefits:

• Fully automated - zero manual intervention after setup
• Uses organization-level secrets for better security
• No changes needed to grml.org repository
• Easy to test and rollback if needed

[zeha]

The plan above was LLMed using Claude. @evgeni do you have input on the access token security?

[evgeni]

https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow says you need repo:write and doesn't mention actions:write, but GH docs (and not only those) on fine-grained tokens are shit.

Wouldn't it be simpler if all data would live in the same repo? 🤔

(np: Die Prinzen - Es ist alles nur ge-Claude)

[evgeni]

Ah yes, because the docs are shit. I was looking at the wrong page.

https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event clearly says actions:write

[evgeni]

Whether you want to allow all of https://docs.github.com/en/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28#actions is up to you

[zeha]

Wouldn't it be simpler if all data would live in the same repo? 🤔

I mean thats also an option. Bit weird maybe, but certainly easy.

@mika wdyt?

[mika]

Wouldn't it be simpler if all data would live in the same repo? 🤔

I mean thats also an option. Bit weird maybe, but certainly easy.

@mika wdyt?

Ah, include grml-mirrors inside grml.org repos? Sounds like a good idea and should simplify things for us?
Let's not forget to accordingly change existing cronjobs on server side though

[zeha]

Whether you want to allow all of https://docs.github.com/en/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28#actions is up to you

that's not really "fine-grained" 😓

[evgeni]

It's finer than "allow everything the user can do", so there is that.

But yes, there are many complaints that triggering a workflow should be an own permission.