Skip to content

[task] Create minimal "Your First Workflow" tutorial (5-minute quick win) #1472

New issue
New issue
Closed as not planned
Closed as not planned
[task] Create minimal "Your First Workflow" tutorial (5-minute quick win)#1472
Labels
ai-generatedtask

Description

@github-actions
github-actions
bot
opened on Oct 10, 2025

Objective

Create a single, focused tutorial that gets a new user from zero to their first working agentic workflow in 5 minutes with a guaranteed success.

Context

The scout report emphasizes a "single success path" with copy-paste ready examples. This is the crucial first tutorial that builds confidence. Part of issue #1433.

Approach

Create docs/src/content/docs/tutorials/your-first-workflow.md with:

  1. Prerequisites (1 sentence): GitHub repository with Actions enabled
  2. Learning Goal (1 sentence): Create a workflow that greets new issues
  3. Steps (3-4 steps max):
    • Create .github/workflows/issue-greeter.md
    • Paste minimal workflow code
    • Create a test issue
    • See the AI response
  4. Working Example: Complete, copy-paste ready code
  5. What You Learned (2-3 bullets)
  6. Next Steps: Link to next tutorial

Example Code Structure

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
engine: copilot
safe-outputs:
  add-comment:
---

# Issue Greeter

Welcome new contributors to the repository with a friendly message.

Files to Create

  • docs/src/content/docs/tutorials/your-first-workflow.md

Writing Guidelines

  • Use imperative mood: "Create a file", "Paste the code"
  • No optional parameters or advanced features
  • Complete working example that requires zero modifications
  • Test the workflow yourself before submitting
  • Time yourself - must be completable in 5 minutes

Acceptance Criteria

  • Tutorial can be completed in 5 minutes or less
  • Code example is complete and copy-paste ready
  • Code example works without modification
  • No advanced features or optional parameters
  • Clear success indicator (comment appears on issue)
  • Links to next tutorial in sequence
    Related to Simplify docs scaffolding #1433

AI generated by Plan Command

Activity

  1. github-actions
    added
    task
    ai-generated
    on Oct 10, 2025
  2. pelikhan
    assigned
    Copilot
    and unassigned
    Copilot
    on Oct 10, 2025

  3. pelikhan commented on Oct 10, 2025

    @pelikhan
    pelikhan
    on Oct 10, 2025
    Collaborator

    /scout find another minimal relevant example. Not first contribution.

    Agentic Scout triggered by this comment

  4. github-actions commented on Oct 10, 2025

    @github-actions
    github-actionsBot
    on Oct 10, 2025 – with GitHub Actions
    ContributorAuthor

    🔍 Scout Research Report

    Triggered by @pelikhan

    Executive Summary

    Found several minimal, beginner-friendly workflow alternatives to the "issue greeter" pattern. The most promising options focus on repository analysis, auto-labeling, and PR summaries - all providing immediate visible value with copy-paste simplicity.

    Click to expand detailed findings

    Research Findings

    Alternative Minimal Workflow Ideas

    Based on analysis of successful beginner tutorials and automation patterns, here are viable alternatives to the issue greeter:

    1. PR Summary Generator (Recommended)

    • Trigger: When a pull request is opened
    • Action: AI reads the PR diff and generates a brief summary comment
    • Why it works:
      • Immediate visible output (comment appears on PR)
      • Uses both read (PR content) and write (comment) capabilities
      • Practical value - helps reviewers understand changes quickly
      • Natural learning progression to more complex PR workflows

    Example use case: "Summarize the changes in this pull request in 2-3 sentences"

    2. Code Change Analyzer

    • Trigger: Push to main branch
    • Action: AI analyzes recent commits and creates a summary issue
    • Why it works:
      • Demonstrates safe-outputs pattern (issue creation)
      • Shows how to work with git history
      • Introduces on: push trigger (very common)
      • Creates visible artifact (issue) as proof of success

    Example use case: "Analyze the last 3 commits and create an issue summarizing what changed"

    3. Label Suggester

    • Trigger: Issue opened without labels
    • Action: AI reads issue content and suggests appropriate labels in a comment
    • Why it works:
      • Simple, focused task with clear success criteria
      • Teaches conditional logic (if no labels exist)
      • Practical for repository maintenance
      • Non-invasive (suggests but doesn't auto-apply)

    Example use case: "Read this issue and suggest 2-3 appropriate labels"

    4. Weekly Repository Report

    • Trigger: Scheduled (weekly)
    • Action: AI generates a summary issue of repository activity
    • Why it works:
      • Introduces cron/schedule triggers
      • Demonstrates data aggregation
      • Creates tangible output (issue)
      • Can be tested immediately with workflow_dispatch

    Example use case: "Every Monday, create an issue summarizing last week's activity"

    Comparison to "Issue Greeter"

    Current approach (issue greeter):

    • ✅ Very simple
    • ✅ Clear success indicator
    • ❌ Limited practical value
    • ❌ Feels like "hello world" toy example
    • ❌ Doesn't showcase AI capabilities well

    Recommended alternative (PR Summary):

    • ✅ Still very simple (4-5 lines of frontmatter)
    • ✅ Clear success indicator (comment appears)
    • ✅ High practical value (helps code review)
    • ✅ Demonstrates AI understanding of code
    • ✅ Natural pathway to advanced PR workflows

    Recommendations

    Primary Recommendation: PR Summary Generator

    Create the tutorial around this workflow:

    ---
on:
  pull_request:
    types: [opened]
permissions:
  contents: read
engine: copilot
safe-outputs:
  add-comment:
---

# PR Summary Generator

Read the changes in this pull request and write a brief 2-3 sentence summary as a comment. Focus on what was changed and why it might matter.

    Why this is the best choice:

    1. Practical value: Actually useful in real repositories
    2. Simple setup: Works exactly as shown, no modifications needed
    3. Clear success: Comment appears on PR within minutes
    4. Teaches key concepts: Triggers, permissions, safe-outputs, AI prompts
    5. Natural progression: Next tutorial can build on PR workflows (review comments, code suggestions, etc.)

    Alternative Recommendation: Code Change Analyzer

    If PR-based workflow is too similar to issue workflows, use the push-triggered analyzer:

    ---
on: push
permissions:
  contents: read
  actions: read
engine: copilot
safe-outputs:
  create-issue:
    title-prefix: "[analysis] "
---

# Code Change Analyzer

Analyze the changes in this push. Create an issue with:
- What files were modified
- A brief summary of the changes
- Any potential concerns or improvements

    Advantages:

    • Different trigger type (push vs issues)
    • Demonstrates safe-outputs.create-issue pattern
    • Can be tested with a simple commit
    • More "proactive" feel vs "reactive" issue greeting

    Key Sources

    • GitHub Actions Tutorial Examples: Everhour Blog - Common beginner patterns
    • Workflow Automation Best Practices: Spacelift Tutorial - Start small, build complexity
    • Agentic AI Design Patterns: AIMultiple Research - Tool activation and response creation patterns

    Suggested Next Steps

    1. Choose the workflow type: PR Summary (recommended) or Code Analyzer
    2. Test the workflow: Ensure it completes in under 5 minutes end-to-end
    3. Write the tutorial: Follow the structure from issue [task] Create minimal "Your First Workflow" tutorial (5-minute quick win) #1472
    4. Create follow-up tutorials: Build on the chosen workflow type
      • For PR Summary: Next tutorial could be "Review-specific files" or "Suggest code improvements"
      • For Code Analyzer: Next tutorial could be "Weekly digest" or "Security scan summary"

    Bottom line: Replace the issue greeter with PR Summary Generator for a minimal example that's both beginner-friendly AND practically useful.

    AI generated by Scout

  5. pelikhan
    added a parent issue on Oct 11, 2025
  6. dsyme
    closed this as not plannedon Oct 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ai-generatedtask

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions