GitHub Actions

Overview

GitHub Actions automates your daily story generation. The workflow runs on a schedule, generates a new story using AI, and commits the results back to your repository.

Workflow File Breakdown

The complete workflow is defined in .github/workflows/actualizar.yml:

.github/workflows/actualizar.yml

name: Actualizar Historia Diaria

on:
  schedule:
    # Los servidores usan la hora universal (UTC).
    # Las 13:00 UTC equivalen exactamente a las 8:00 AM en Lima.
    - cron: '0 13 * * *'
  workflow_dispatch: # Este comando nos permite ejecutarlo manualmente con un botón para probar

jobs:
  generar-pagina:
    runs-on: ubuntu-latest # Encendemos una máquina virtual con Linux
    permissions:
      contents: write # Le damos permiso a la máquina para modificar tu repositorio

    steps:
      - name: 1. Descargar tu código a la máquina virtual
        uses: actions/checkout@v4

      - name: 2. Preparar e instalar Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: 3. Instalar dependencias (NUEVO PASO)
        run: |
          python -m pip install --upgrade pip
          pip install requests

      - name: 4. Ejecutar tu script
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: python generar_historia.py

      - name: 5. Guardar los cambios (Hacer Commit y Push)
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add .
          git diff --quiet && git diff --staged --quiet || git commit -m "Actualizar historia e historial"
          git push

Workflow Components

Workflow Name

name: Actualizar Historia Diaria

The name appears in the GitHub Actions tab. You can change this to any descriptive name:

name: Daily Story Generator
name: Auto Historia Bot

Triggers

on:
  schedule:
    - cron: '0 13 * * *'
  workflow_dispatch:

Two trigger types:

Schedule (cron): Runs automatically at specified time
workflow_dispatch: Allows manual triggering via GitHub UI button

Job Configuration

jobs:
  generar-pagina:
    runs-on: ubuntu-latest
    permissions:
      contents: write

runs-on: Specifies Ubuntu Linux virtual machine
permissions: Grants write access to commit files back to repository

Steps

The workflow executes 5 sequential steps:

Checkout code: Downloads repository to VM
Setup Python: Installs Python 3.10
Install dependencies: Installs requests library
Run script: Executes generar_historia.py with API key
Commit & push: Saves generated files back to repository

Schedule Configuration (Cron Syntax)

Understanding Cron

The cron expression defines when the workflow runs:

cron: '0 13 * * *'

Format: minute hour day month weekday

Position	Current Value	Meaning
Minute	`0`	At minute 0
Hour	`13`	At 1:00 PM (UTC)
Day	`*`	Every day
Month	`*`	Every month
Weekday	`*`	Every day of week

Important: GitHub Actions uses UTC timezone. Convert your local time to UTC.Example: 8:00 AM Lima (UTC-5) = 13:00 UTC

Common Schedule Examples

schedule:
  - cron: '0 9 * * *'  # 9:00 AM UTC daily

Timezone Conversion Table

Your Local Time	Timezone	UTC Equivalent	Cron Expression
8:00 AM	EST (UTC-5)	13:00	`0 13 * * *`
9:00 AM	PST (UTC-8)	17:00	`0 17 * * *`
12:00 PM	GMT (UTC+0)	12:00	`0 12 * * *`
3:00 PM	CET (UTC+1)	14:00	`0 14 * * *`
10:00 AM	IST (UTC+5:30)	04:30	`30 4 * * *`

Use crontab.guru to validate and understand cron expressions.

Manual Triggers

The workflow_dispatch trigger enables manual workflow execution:

.github/workflows/actualizar.yml

on:
  workflow_dispatch:  # Enables manual trigger button

How to Manually Run

Navigate to Actions Tab

Go to your GitHub repository → Actions tab

Select Workflow

Click on Actualizar Historia Diaria in the left sidebar

Run Workflow

Click Run workflow dropdown → Select branch (usually main) → Click Run workflow

Monitor Progress

The workflow will appear in the runs list. Click it to see live logs.

Manual triggers are perfect for testing changes without waiting for the scheduled time.

Permissions Setup

The workflow requires write permissions to commit generated files:

.github/workflows/actualizar.yml

permissions:
  contents: write  # Allows the workflow to push commits

Verifying Permissions

Check Repository Settings

Go to Settings → Actions → General

Workflow Permissions

Scroll to Workflow permissions section

Enable Write Access

Select Read and write permissions and save

If permissions are set to “Read repository contents only”, the workflow will fail at the push step with a 403 error.

Viewing Workflow Logs

Logs help you understand what happened during each run.

Accessing Logs

Open Actions Tab

Navigate to Actions in your repository

Select a Run

Click on any workflow run to see its details

View Step Logs

Click on generar-pagina job, then click any step to expand its logs

Understanding Log Output

Each step shows its output:

Example Success Log

✓ 1. Descargar tu código a la máquina virtual
✓ 2. Preparar e instalar Python
✓ 3. Instalar dependencias
✓ 4. Ejecutar tu script
  Output: ¡Página y menú generados con éxito!
✓ 5. Guardar los cambios
  [main abc1234] Actualizar historia e historial
   3 files changed, 45 insertions(+)

Troubleshooting Failed Runs

Common Errors

Error: API Key Not Found

Symptom:

Fallo al conectar con la API.

Cause: Missing or incorrect OPENROUTER_API_KEY secretSolution:

Go to Settings → Secrets and variables → Actions
Verify OPENROUTER_API_KEY exists
If missing, add it with your OpenRouter API key
Re-run the workflow

Error: Permission Denied (403)

Symptom:

remote: Permission to user/repo.git denied
fatal: unable to access 'https://github.com/user/repo/': The requested URL returned error: 403

Cause: Workflow lacks write permissionsSolution:

Go to Settings → Actions → General
Under Workflow permissions, select Read and write permissions
Save and re-run the workflow

Error: Module Not Found

Symptom:

ModuleNotFoundError: No module named 'requests'

Cause: Dependencies not installed properlySolution: Ensure step 3 in your workflow includes:

- name: 3. Instalar dependencias
  run: |
    python -m pip install --upgrade pip
    pip install requests

Error: Nothing to Commit

Symptom:

nothing to commit, working tree clean

Cause: Script didn’t generate or modify any filesSolution: This can be normal if the script had an error. Check step 4 logs:

- name: 4. Ejecutar tu script

Look for Python errors or API failures.

Error: Rate Limit Exceeded

Symptom:

HTTP 429: Too Many Requests

Cause: OpenRouter rate limit reached (common with free models)Solution:

Wait 1-2 hours and try again
Switch to a paid model
Reduce workflow frequency

Error: Workflow Didn't Run

Symptom: Scheduled workflow didn’t execute at expected timeCause: GitHub Actions can be delayed by up to 15 minutes during high loadSolution:

Wait 15-30 minutes past scheduled time
Check Actions tab for any queued runs
Manually trigger to test if workflow works

Debugging Steps

Check Workflow Status

Go to Actions and look for failed runs (red X icon)

Read Error Logs

Click the failed run → Click the failed step → Read error message

Verify Secrets

Ensure OPENROUTER_API_KEY is properly set in repository secrets

Test Locally

Run python generar_historia.py on your local machine with the API key set as an environment variable:

export OPENROUTER_API_KEY="your-key-here"
python generar_historia.py

Manual Trigger

Use Run workflow button to test without waiting for schedule

Advanced Workflow Customization

Adding Notifications

Send yourself an email when workflow fails:

Add Email Notification

- name: Notify on Failure
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: Historia Diaria Workflow Failed
    body: Check the logs at ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
    to: your-email@example.com
    from: GitHub Actions

Run Only on Specific Branches

Branch-Specific Trigger

on:
  schedule:
    - cron: '0 13 * * *'
  workflow_dispatch:
  push:
    branches:
      - main  # Only run on main branch

Add Timeout Protection

Prevent Long Runs

jobs:
  generar-pagina:
    runs-on: ubuntu-latest
    timeout-minutes: 10  # Cancel if runs longer than 10 minutes
    permissions:
      contents: write

Multiple Python Dependencies

If you add more Python libraries:

requirements.txt Approach

- name: 3. Instalar dependencias
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

Create requirements.txt in your repository:

requirements.txt

requests==2.31.0
Pillow==10.0.0
beautifulsoup4==4.12.0

Workflow Best Practices

Test First

Always use manual triggers to test changes before relying on scheduled runs

Monitor Costs

Check OpenRouter usage regularly if using paid models

Keep Secrets Safe

Never commit API keys directly in code. Always use GitHub Secrets

Review Logs

Check workflow logs weekly to catch any silent failures

Next Steps

API Setup

Configure OpenRouter API and select models

Customization

Customize prompts, templates, and styling

Get Started

Core Concepts

Configuration

Reference

Help

Overview

Workflow File Breakdown

Workflow Components

Schedule Configuration (Cron Syntax)

Understanding Cron

Common Schedule Examples

Timezone Conversion Table

Manual Triggers

How to Manually Run

Permissions Setup

Verifying Permissions

Viewing Workflow Logs

Accessing Logs

Understanding Log Output

Troubleshooting Failed Runs

Common Errors

Debugging Steps

Advanced Workflow Customization

Adding Notifications

Run Only on Specific Branches

Add Timeout Protection

Multiple Python Dependencies

Workflow Best Practices

Test First

Monitor Costs

Keep Secrets Safe

Review Logs

Next Steps

API Setup

Customization

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Reference

Help

​Overview

​Workflow File Breakdown

​Workflow Components

​Schedule Configuration (Cron Syntax)

​Understanding Cron

​Common Schedule Examples

​Timezone Conversion Table

​Manual Triggers

​How to Manually Run

​Permissions Setup

​Verifying Permissions

​Viewing Workflow Logs

​Accessing Logs

​Understanding Log Output

​Troubleshooting Failed Runs

​Common Errors

​Debugging Steps

​Advanced Workflow Customization

​Adding Notifications

​Run Only on Specific Branches

​Add Timeout Protection

​Multiple Python Dependencies

​Workflow Best Practices

Test First

Monitor Costs

Keep Secrets Safe

Review Logs

​Next Steps

API Setup

Customization

Build docs developers (and LLMs) love

Overview

Workflow File Breakdown

Workflow Components

Schedule Configuration (Cron Syntax)

Understanding Cron

Common Schedule Examples

Timezone Conversion Table

Manual Triggers

How to Manually Run

Permissions Setup

Verifying Permissions

Viewing Workflow Logs

Accessing Logs

Understanding Log Output

Troubleshooting Failed Runs

Common Errors

Debugging Steps

Advanced Workflow Customization

Adding Notifications

Run Only on Specific Branches

Add Timeout Protection

Multiple Python Dependencies

Workflow Best Practices

Next Steps