From 22160957a8824f97bdda4a4f0198be253e527ec2 Mon Sep 17 00:00:00 2001
From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com>
Date: Mon, 14 Jul 2025 12:12:13 +0000
Subject: [PATCH 1/2] docs: add GitHub Actions integration for AI agents

Adds comprehensive documentation for the start-workspace-action GitHub Action
that enables automatic workspace creation from GitHub issues and comments.

- Created docs/ai-coder/github-actions.md with usage examples and configuration
- Updated manifest.json to include new documentation in navigation
- Added GitHub Actions section to ai-coder/index.md for discoverability

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>
---
 docs/ai-coder/github-actions.md | 187 ++++++++++++++++++++++++++++++++
 docs/ai-coder/index.md          |   4 +
 docs/manifest.json              |   5 +
 3 files changed, 196 insertions(+)
 create mode 100644 docs/ai-coder/github-actions.md

diff --git a/docs/ai-coder/github-actions.md b/docs/ai-coder/github-actions.md
new file mode 100644
index 0000000000000..f3c479e86836e
--- /dev/null
+++ b/docs/ai-coder/github-actions.md
@@ -0,0 +1,187 @@
+# GitHub Actions Integration
+
+Coder provides a GitHub Action that automatically starts workspaces from GitHub issues and comments, enabling seamless integration between your development workflow and AI coding agents.
+
+## Start Workspace Action
+
+The [start-workspace-action](https://github.com/coder/start-workspace-action) creates Coder workspaces triggered by GitHub events and posts status updates directly to GitHub issues.
+
+### Features
+
+- **Automatic workspace creation** from GitHub issues or comments
+- **Real-time status updates** posted as GitHub issue comments
+- **User mapping** between GitHub and Coder accounts
+- **Configurable triggers** based on your workflow requirements
+- **Template parameters** for customizing workspace environments
+
+### Basic Usage
+
+Here's an example workflow that starts a workspace when issues are created or when comments contain "@coder":
+
+```yaml
+name: Start Workspace On Issue Creation or Comment
+
+on:
+  issues:
+    types: [opened]
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+
+jobs:
+  start-workspace:
+    runs-on: ubuntu-latest
+    if: >
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@coder')) || 
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@coder'))
+    environment: coder-production
+    timeout-minutes: 5
+    steps:
+      - name: Start Coder workspace
+        uses: coder/start-workspace-action@v0.1.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          github-username: >
+            ${{ 
+              (github.event_name == 'issue_comment' && github.event.comment.user.login) || 
+              (github.event_name == 'issues' && github.event.issue.user.login)
+            }}
+          coder-url: ${{ secrets.CODER_URL }}
+          coder-token: ${{ secrets.CODER_TOKEN }}
+          template-name: ${{ secrets.CODER_TEMPLATE_NAME }}
+          parameters: |-
+            Coder Image: codercom/oss-dogfood:latest
+            Coder Repository Base Directory: "~"
+            AI Code Prompt: "Use the gh CLI tool to read the details of issue https://github.com/${{ github.repository }}/issues/${{ github.event.issue.number }} and then address it."
+            Region: us-pittsburgh
+```
+
+### Configuration
+
+#### Required Inputs
+
+| Input | Description |
+|-------|-------------|
+| `coder-url` | Your Coder deployment URL |
+| `coder-token` | API token for Coder (requires admin privileges) |
+| `template-name` | Name of the Coder template to use |
+| `parameters` | YAML-formatted parameters for the workspace |
+
+#### Optional Inputs
+
+| Input | Description | Default |
+|-------|-------------|----------|
+| `github-token` | GitHub token for posting comments | `${{ github.token }}` |
+| `github-issue-number` | Issue number for status comments | Current issue from context |
+| `github-username` | GitHub user to map to Coder user | - |
+| `coder-username` | Coder username (alternative to github-username) | - |
+| `workspace-name` | Name for the new workspace | `issue-{issue_number}` |
+
+### User Mapping
+
+The action supports two methods for mapping users:
+
+1. **GitHub Username Mapping** (Coder 2.21+): Set `github-username` to automatically map GitHub users to Coder users who have logged in with the same GitHub account.
+
+2. **Direct Coder Username**: Set `coder-username` to specify the exact Coder user.
+
+### Security Best Practices
+
+Since this action requires a Coder admin API token, follow these security recommendations:
+
+1. **Use GitHub Environments**: Store sensitive secrets in a GitHub environment (e.g., "coder-production")
+2. **Restrict Branch Access**: Limit the environment to specific branches (e.g., main)
+3. **Minimal Permissions**: Use the least privileged token possible
+
+```yaml
+jobs:
+  start-workspace:
+    runs-on: ubuntu-latest
+    # Restrict access to secrets using environments
+    environment: coder-production
+    steps:
+      - name: Start Coder workspace
+        uses: coder/start-workspace-action@v0.1.0
+        with:
+          coder-token: ${{ secrets.CODER_TOKEN }}
+          # other inputs...
+```
+
+### AI Agent Integration
+
+This action works particularly well with AI coding agents by:
+
+- **Providing context**: Pass issue details to agents via template parameters
+- **Automating setup**: Pre-configure workspaces with necessary tools and repositories
+- **Enabling collaboration**: Allow agents to work on issues triggered by team members
+
+#### Example AI Agent Prompt
+
+```yaml
+parameters: |-
+  AI Code Prompt: |
+    You are an AI coding assistant. Your task is to:
+    1. Read the GitHub issue at https://github.com/${{ github.repository }}/issues/${{ github.event.issue.number }}
+    2. Analyze the requirements and existing codebase
+    3. Implement the requested changes
+    4. Run tests to ensure functionality
+    5. Create a pull request with your solution
+```
+
+### Workflow Examples
+
+#### Issue-Triggered Workspaces
+
+```yaml
+on:
+  issues:
+    types: [opened, labeled]
+
+jobs:
+  start-workspace:
+    if: contains(github.event.issue.labels.*.name, 'ai-assist')
+    # ... rest of configuration
+```
+
+#### Comment-Triggered Workspaces
+
+```yaml
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  start-workspace:
+    if: |
+      github.event.issue.pull_request == null &&
+      contains(github.event.comment.body, '/coder start')
+    # ... rest of configuration
+```
+
+### Requirements
+
+- Coder deployment with API access
+- Coder 2.21+ for GitHub username mapping (earlier versions can use `coder-username`)
+- GitHub repository with appropriate secrets configured
+- Coder template configured for AI agent workflows
+
+### Troubleshooting
+
+#### Common Issues
+
+- **Authentication failures**: Ensure `CODER_TOKEN` has admin privileges
+- **User mapping errors**: Verify GitHub users have logged into Coder with the same account
+- **Template not found**: Check that `template-name` exists and is accessible
+- **Parameter validation**: Ensure template parameters match expected format
+
+#### GitHub Enterprise
+
+This action supports GitHub Enterprise with the exception of the `github-username` input. Use `coder-username` instead for GitHub Enterprise deployments.
+
+## Next Steps
+
+- [Configure Coder Tasks](./tasks.md) for running AI agents
+- [Set up custom agents](./custom-agents.md) in your templates
+- [Review security considerations](./security.md) for AI agent deployments
diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md
index bb4d8ccda3da5..dd201b3680ca6 100644
--- a/docs/ai-coder/index.md
+++ b/docs/ai-coder/index.md
@@ -8,6 +8,10 @@ Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as C
 
 These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor.
 
+## GitHub Actions Integration
+
+Coder provides a [GitHub Action](./github-actions.md) that automatically starts workspaces from GitHub issues and comments, enabling seamless integration between your development workflow and AI coding agents. This is particularly useful for automated code reviews, issue resolution, and collaborative development with AI agents.
+
 ## Agents with Coder Tasks (Beta)
 
 In cases where the IDE is secondary, such as protyping or long-running background jobs, agents like Claude Code or Aider are better for the job and new SaaS interfaces like [Devin](https://devin.ai) and [ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging.
diff --git a/docs/manifest.json b/docs/manifest.json
index 65555caa0df4f..a7e0328708894 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -833,6 +833,11 @@
 					"description": "Run IDE agents with Coder",
 					"path": "./ai-coder/ide-agents.md"
 				},
+				{
+					"title": "GitHub Actions",
+					"description": "Integrate AI agents with GitHub workflows",
+					"path": "./ai-coder/github-actions.md"
+				},
 				{
 					"title": "Coder Tasks",
 					"description": "Run Coding Agents on your Own Infrastructure",

From 8419992d4d782107c8dcd089a8b1d566718c853f Mon Sep 17 00:00:00 2001
From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com>
Date: Mon, 14 Jul 2025 12:15:19 +0000
Subject: [PATCH 2/2] fix: format markdown tables in github-actions.md

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>
---
 docs/ai-coder/github-actions.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/ai-coder/github-actions.md b/docs/ai-coder/github-actions.md
index f3c479e86836e..3a6c0acf0c4cb 100644
--- a/docs/ai-coder/github-actions.md
+++ b/docs/ai-coder/github-actions.md
@@ -62,22 +62,22 @@ jobs:
 
 #### Required Inputs
 
-| Input | Description |
-|-------|-------------|
-| `coder-url` | Your Coder deployment URL |
-| `coder-token` | API token for Coder (requires admin privileges) |
-| `template-name` | Name of the Coder template to use |
-| `parameters` | YAML-formatted parameters for the workspace |
+| Input           | Description                                     |
+|-----------------|-------------------------------------------------|
+| `coder-url`     | Your Coder deployment URL                       |
+| `coder-token`   | API token for Coder (requires admin privileges) |
+| `template-name` | Name of the Coder template to use               |
+| `parameters`    | YAML-formatted parameters for the workspace     |
 
 #### Optional Inputs
 
-| Input | Description | Default |
-|-------|-------------|----------|
-| `github-token` | GitHub token for posting comments | `${{ github.token }}` |
-| `github-issue-number` | Issue number for status comments | Current issue from context |
-| `github-username` | GitHub user to map to Coder user | - |
-| `coder-username` | Coder username (alternative to github-username) | - |
-| `workspace-name` | Name for the new workspace | `issue-{issue_number}` |
+| Input                 | Description                                     | Default                    |
+|-----------------------|-------------------------------------------------|----------------------------|
+| `github-token`        | GitHub token for posting comments               | `${{ github.token }}`      |
+| `github-issue-number` | Issue number for status comments                | Current issue from context |
+| `github-username`     | GitHub user to map to Coder user                | -                          |
+| `coder-username`      | Coder username (alternative to github-username) | -                          |
+| `workspace-name`      | Name for the new workspace                      | `issue-{issue_number}`     |
 
 ### User Mapping