Add GitHub Actions primer guide to documentation #12755
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Add primer guide on GitHub actions
Add GitHub Actions primer guide to documentation
Jan 30, 2026
pelikhan
reviewed
Jan 30, 2026
Comment on lines
14
to
27
| ### Brief History | ||
|
|
||
| GitHub Actions launched in **November 2019** as GitHub's answer to the growing need for built-in CI/CD (Continuous Integration/Continuous Deployment) capabilities within the development platform. Before Actions, developers relied on external services like Travis CI, CircleCI, or Jenkins that required separate configuration and maintenance. | ||
|
|
||
| **Key milestones in GitHub Actions evolution:** | ||
|
|
||
| - **2019**: Initial release with workflow automation and CI/CD capabilities | ||
| - **2020**: Added Docker container actions and improved marketplace | ||
| - **2021**: Expanded to include deployment environments and reusable workflows | ||
| - **2022**: Introduced larger runners, deployment protection rules, and enhanced security features | ||
| - **2023**: Added OpenID Connect (OIDC) support for secure cloud deployments | ||
| - **2024-2026**: Integration with AI agents and Model Context Protocol (MCP) servers | ||
|
|
||
| Today, GitHub Actions processes billions of workflow runs monthly and has become the de facto standard for automating GitHub-based development workflows. |
Contributor
Author
There was a problem hiding this comment.
Removed the "Brief History" section in commit 604e74d.
| **Using workflow_dispatch for testing:** | ||
|
|
||
| 1. **Create test workflow** with `workflow_dispatch` trigger in a feature branch | ||
| 2. **Push to your branch** - the workflow file is now visible in the Actions tab |
Contributor
Author
There was a problem hiding this comment.
Fixed the workflow_dispatch instructions to clarify that the workflow must be merged to main branch first, then you can choose which branch to run from. Updated in commit 604e74d.
| > - `ACTIONS_RUNNER_DEBUG: true` - Enables runner diagnostic logging | ||
|
|
||
| **Limitations of branch-based testing:** | ||
| - Cannot access repository secrets from feature branches (security restriction) |
Contributor
Author
There was a problem hiding this comment.
Removed the incorrect statement about secrets access restrictions. Updated in commit 604e74d.
Comment on lines
311
to
444
| ### Enhanced Sandboxing in Agentic Workflows | ||
|
|
||
| Agentic workflows implement **defense-in-depth security** beyond standard GitHub Actions: | ||
|
|
||
| ```mermaid | ||
| flowchart TB | ||
| subgraph Traditional["Traditional GitHub Actions"] | ||
| A1["Workflow File (.yml)"] | ||
| A2["Runner VM"] | ||
| A3["Steps with $GITHUB_TOKEN"] | ||
| A4["Direct API Access"] | ||
|
|
||
| A1 --> A2 | ||
| A2 --> A3 | ||
| A3 --> A4 | ||
| end | ||
|
|
||
| subgraph Agentic["Agentic Workflows"] | ||
| B1["Workflow File (.md)"] | ||
| B2["Compiled Lock File (.lock.yml)"] | ||
| B3["Agent Sandbox"] | ||
| B4["MCP Gateway"] | ||
| B5["Network Firewall"] | ||
| B6["Safe Outputs Job"] | ||
| B7["Sanitized API Access"] | ||
|
|
||
| B1 --> B2 | ||
| B2 --> B3 | ||
| B3 --> B4 | ||
| B4 --> B5 | ||
| B3 --> B6 | ||
| B6 --> B7 | ||
| end | ||
| ``` | ||
|
|
||
| **Agentic workflow security enhancements:** | ||
|
|
||
| 1. **Agent Sandbox**: AI agent runs with **read-only** permissions by default | ||
| 2. **MCP Gateway**: Controls tool access and filters communications | ||
| 3. **Network Firewall**: Blocks all egress except explicitly allowlisted domains | ||
| 4. **Safe Outputs**: Agent writes are buffered, validated, and sanitized before execution | ||
| 5. **Secret Redaction**: Automatic removal of credentials from agent outputs | ||
| 6. **Tool Allowlisting**: Only explicitly permitted tools are available to the agent | ||
|
|
||
| ### Example: Issue Triage | ||
|
|
||
| **Traditional GitHub Actions** (explicit YAML steps): | ||
|
|
||
| ```yaml | ||
| name: Issue Triage | ||
| on: | ||
| issues: | ||
| types: [opened] | ||
|
|
||
| jobs: | ||
| triage: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| issues: write | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
|
|
||
| - name: Check if bug report | ||
| id: check | ||
| run: | | ||
| if echo "${{ github.event.issue.body }}" | grep -i "bug"; then | ||
| echo "is_bug=true" >> $GITHUB_OUTPUT | ||
| fi | ||
|
|
||
| - name: Add bug label | ||
| if: steps.check.outputs.is_bug == 'true' | ||
| uses: actions/github-script@v7 | ||
| with: | ||
| script: | | ||
| await github.rest.issues.addLabels({ | ||
| owner: context.repo.owner, | ||
| repo: context.repo.repo, | ||
| issue_number: context.issue.number, | ||
| labels: ['bug'] | ||
| }); | ||
| ``` | ||
|
|
||
| **Agentic Workflow** (natural language): | ||
|
|
||
| ```markdown | ||
| --- | ||
| on: | ||
| issues: | ||
| types: [opened] | ||
| permissions: read-all | ||
| safe-outputs: | ||
| add-label: | ||
| add-comment: | ||
| --- | ||
| # Issue Triage | ||
|
|
||
| Analyze the issue content and: | ||
| - Add appropriate labels (bug, feature, documentation) | ||
| - Ask for clarification if the issue is unclear | ||
| - Suggest related issues if similar problems exist | ||
| ``` | ||
|
|
||
| **Key differences:** | ||
|
|
||
| - **Agentic approach**: Describes **intent** rather than exact steps | ||
| - **AI decision-making**: Agent determines appropriate labels based on content understanding | ||
| - **Safe-outputs**: Labels and comments validated before posting | ||
| - **Adaptability**: Handles edge cases without explicit programming | ||
| - **Sandboxing**: Agent cannot directly modify issues—all changes go through safe-output validation | ||
|
|
||
| ### When to Use Each Approach | ||
|
|
||
| **Use Traditional GitHub Actions when:** | ||
| - Fixed, deterministic workflows (build, test, deploy) | ||
| - Performance-critical operations (large-scale builds) | ||
| - Existing YAML workflows that work well | ||
| - Simple automation without context analysis | ||
|
|
||
| **Use Agentic Workflows when:** | ||
| - Natural language processing of issues, PRs, or comments | ||
| - Context-aware decision-making required | ||
| - Complex triage, analysis, or research tasks | ||
| - Want to describe intent rather than implementation | ||
| - Need enhanced security for AI-powered operations | ||
|
|
||
| ## Next Steps | ||
|
|
||
| Now that you understand GitHub Actions fundamentals, explore how agentic workflows build upon this foundation: | ||
|
|
||
| - **[Quick Start](/gh-aw/setup/quick-start/)** - Create your first agentic workflow | ||
| - **[Security Best Practices](/gh-aw/guides/security/)** - Deep dive into agentic security model | ||
| - **[Safe Outputs](/gh-aw/reference/safe-outputs/)** - Learn about validated GitHub operations | ||
| - **[Workflow Structure](/gh-aw/reference/workflow-structure/)** - Understand markdown workflow syntax | ||
| - **[Examples](/gh-aw/examples/scheduled/research-planning/)** - Real-world agentic workflow patterns |
Contributor
Author
There was a problem hiding this comment.
Removed the enhanced sandboxing diagram, example comparison, and when-to-use sections (lines 311-444) in commit 604e74d.
…tch testing instructions Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Contributor
Author
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New users need foundational GitHub Actions knowledge before understanding how agentic workflows extend the platform. Guide covers core concepts and comparison with agentic workflows.
Changes
New guide:
/docs/src/content/docs/guides/github-actions-primer.md.github/workflows/), jobs (parallel/sequential execution), steps (actions + commands)workflow_dispatchfor testing (must be merged to main first), debug loggingNavigation: Added as first item in Guides sidebar
Key sections
Workflows, Jobs & Steps: Explains the fundamental building blocks of GitHub Actions with practical YAML examples showing how workflows are triggered, how jobs execute on runners, and how steps perform individual tasks.
Security Model: Covers workflow storage requirements (must be in
.github/workflows/on main branch), permission declarations using principle of least privilege, and secret management with automatic redaction.Testing with workflow_dispatch: Demonstrates how to test workflows by adding a
workflow_dispatchtrigger, merging to main, then selecting any branch to run from in the Actions UI.Comparison Table: Shows key differences between traditional GitHub Actions and agentic workflows across dimensions like definition language, decision-making, security model, write operations, network access, and execution environment.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.