chore: update README.md

README.md

@@ -2,12 +2,87 @@
 
 This GitHub action starts a [Coder Task](https://coder.com/docs/ai-coder/tasks) and optionally posts a comment on a GitHub issue. It's designed to be used as part of a wider workflow.
 
-## Features
+## Overview
 
-- Starts a Coder Task using your specified template and preset
-- Posts a single status comment on a GitHub issue
-- Maps GitHub users to Coder users
+- When creating a Coder task, you must specify the Github user ID as an input.
+- The action then queries the Coder deployment to find the Coder user associated with the given Github user ID.
+  - Note that this requires the Coder deployment to be configured with [GitHub OAuth](https://coder.com/docs/admin/external-auth#configure-a-github-oauth-app) and for the Coder user to have linked their GitHub account.
+  - If no corresponding Coder user is found, the action will fail.
+- The action will then create a [Coder Task](https://coder.com/docs/ai-coder/tasks) for the user with the given template and prompt.
+- Once the task has been created successfully, the action will post a comment on the GitHub issue with the task URL.
+
+## Requirements
+
+- A running Coder deployment (v2.28 or higher) accessible to the GitHub Actions runner.
+- A [Tasks-capable](https://coder.com/docs/ai-coder/tasks#getting-started-with-tasks) Coder template
+- A Coder session token with the required permissions to:
+  - Read all users in the given organization
+  - Create tasks for any user in the given organization
 
 ## Example Usage
 
-TODO
+The below example will start a Coder task when the `coder` label is applied to an issue.
+
+```yaml
+name: Start Coder Task
+
+on:
+  issues:
+    types:
+      - labeled
+
+permissions:
+  issues: write
+
+jobs:
+  start-coder-task:
+    runs-on: ubuntu-latest
+    if: github.event.label.name == 'coder'
+    steps:
+      - name: Start Coder Task
+        uses: coder/start-coder-task@v0.0.2
+        with:
+          coder-url: ${{ secrets.CODER_URL }}
+          coder-token: ${{ secrets.CODER_TOKEN }}
+          coder-organization: "default"
+          coder-template-name: "my-template"
+          coder-task-name-prefix: "gh-task"
+          coder-task-prompt: "Use the gh CLI to read ${{ github.event.issue.html_url }}, write an appropriate plan for solving the issue to PLAN.md, and then wait for feedback."
+          github-user-id: ${{ github.event.sender.id }}
+          github-issue-url: ${{ github.event.issue.html_url }}
+          github-token: ${{ github.token }}
+          comment-on-issue: true
+```
+
+## Inputs
+
+<!--
+yq -r '.inputs | to_entries[] | "| \(.key) | \(.value.description) | \(.value.required // false ) | \(.value.default // \"-\") |"' action.yaml
+-->
+
+| Name                   | Description                             | Required | Default   |
+| ---------------------- | --------------------------------------- | -------- | --------- |
+| coder-task-prompt      | Prompt/instructions to send to the task | true     | -         |
+| coder-token            | Coder session token for authentication  | true     | -         |
+| coder-url              | Coder deployment URL                    | true     | -         |
+| coder-template-name    | Coder template to use for workspace     | true     | -         |
+| github-issue-url       | GitHub issue URL to link this task to   | true     | -         |
+| github-token           | GitHub token for API operations         | true     | -         |
+| github-user-id         | GitHub user ID to create task for       | true     | -         |
+| coder-organization     | Coder organization name                 | false    | "default" |
+| coder-task-name-prefix | Prefix for task name                    | false    | "gh"      |
+| coder-template-preset  | Template preset to use (optional)       | false    | -         |
+| comment-on-issue       | Whether to comment on the GitHub issue  | false    | true      |
+
+## Outputs
+
+<!--
+yq -r '.outputs | to_entries[] | "| \(.key) | \(.value.description) |"' action.yaml
+-->
+
+| Name           | Description                                                          |
+| -------------- | -------------------------------------------------------------------- |
+| coder-username | The Coder username resolved from GitHub user                         |
+| task-name      | The task name                                                        |
+| task-url       | The URL to view the task in Coder                                    |
+| task-created   | Whether the task was newly created (true) or already existed (false) |

action.yaml

@@ -15,14 +15,6 @@ inputs:
     description: "Coder deployment URL"
     required: true
 
-  coder-organization:
-    description: "Coder organization name"
-    required: true
-
-  coder-task-name-prefix:
-    description: "Prefix for task name"
-    required: true
-
   coder-template-name:
     description: "Coder template to use for workspace"
     required: true
@@ -40,6 +32,16 @@ inputs:
     required: true
 
   # Optional inputs
+  coder-organization:
+    description: "Coder organization name"
+    required: false
+    default: "default"
+
+  coder-task-name-prefix:
+    description: "Prefix for task name"
+    required: false
+    default: "gh"
+
   coder-template-preset:
     description: "Template preset to use (optional)"
     required: false

dist/index.js

@@ -26928,6 +26928,7 @@ class CoderTaskAction {
     if (!this.inputs.coderTaskNamePrefix || !this.inputs.githubIssueURL) {
       throw new Error("either taskName or both taskNamePrefix and issueURL must be provided");
     }
+    core.info(`Coder organization: ${this.inputs.coderOrganization}`);
     const taskNameString = `${this.inputs.coderTaskNamePrefix}-${githubIssueNumber}`;
     const taskName = TaskNameSchema.parse(taskNameString);
     core.info(`Coder Task name: ${taskName}`);
@@ -27004,12 +27005,12 @@ var ActionInputsSchema = exports_external.object({
   coderTaskPrompt: exports_external.string().min(1),
   coderToken: exports_external.string().min(1),
   coderURL: exports_external.string().url(),
-  coderOrganization: exports_external.string().min(1),
-  coderTaskNamePrefix: exports_external.string().min(1),
   coderTemplateName: exports_external.string().min(1),
   githubIssueURL: exports_external.string().url(),
   githubToken: exports_external.string(),
   githubUserID: exports_external.number().min(1),
+  coderOrganization: exports_external.string().min(1).optional().default("default"),
+  coderTaskNamePrefix: exports_external.string().min(1).optional().default("gh"),
   coderTemplatePreset: exports_external.string().optional(),
   commentOnIssue: exports_external.boolean().default(true)
 });

src/action.ts

@@ -119,6 +119,7 @@ export class CoderTaskAction {
 				"either taskName or both taskNamePrefix and issueURL must be provided",
 			);
 		}
+		core.info(`Coder organization: ${this.inputs.coderOrganization}`);
 		const taskNameString = `${this.inputs.coderTaskNamePrefix}-${githubIssueNumber}`;
 		const taskName = TaskNameSchema.parse(taskNameString);
 		core.info(`Coder Task name: ${taskName}`);

src/schemas.ts

@@ -7,13 +7,13 @@ export const ActionInputsSchema = z.object({
 	coderTaskPrompt: z.string().min(1),
 	coderToken: z.string().min(1),
 	coderURL: z.string().url(),
-	coderOrganization: z.string().min(1),
-	coderTaskNamePrefix: z.string().min(1),
 	coderTemplateName: z.string().min(1),
 	githubIssueURL: z.string().url(),
 	githubToken: z.string(),
 	githubUserID: z.number().min(1),
 	// Optional
+	coderOrganization: z.string().min(1).optional().default("default"),
+	coderTaskNamePrefix: z.string().min(1).optional().default("gh"),
 	coderTemplatePreset: z.string().optional(),
 	commentOnIssue: z.boolean().default(true),
 });