Skip to content

Commit 212ab2f

Browse files
hugodutkahugodutka
committed
update readme and add a license
1 parent 094e9ea commit 212ab2f

File tree

2 files changed

+117
-38
lines changed

2 files changed

+117
-38
lines changed

‎LICENSE

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright (c) 2025 Coder Technologies, Inc.
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 110 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,116 @@
1-
# start-workspace-action
2-
3-
This GitHub Action starts a Coder workspace in response to GitHub issues and comments containing @coder.
4-
5-
## Development
6-
7-
To install dependencies:
8-
9-
```bash
10-
bun install
11-
```
12-
13-
### Building
14-
15-
The GitHub Action runs from the compiled code in the `dist/` directory. You must build the project after making changes:
16-
17-
```bash
18-
bun run build
1+
# Start Coder Workspace GitHub Action
2+
3+
This GitHub Action starts a [Coder](https://coder.com) workspace and posts status updates as comments on a GitHub issue. It's designed to be used as part of a workflow triggered by events you configure.
4+
5+
## Features
6+
7+
- Starts a Coder workspace using your specified template
8+
- Posts status comments on a GitHub issue
9+
- Configurable workspace parameters
10+
- Maps GitHub users to Coder users
11+
12+
## Usage
13+
14+
This action only handles the workspace creation and status updates. You need to configure your own workflow triggers based on your requirements.
15+
16+
Here's an example workflow that triggers on issue creation or comments containing "@coder":
17+
18+
```yaml
19+
name: Start Workspace On Issue Creation or Comment
20+
21+
on:
22+
issues:
23+
types: [opened]
24+
issue_comment:
25+
types: [created]
26+
27+
permissions:
28+
issues: write
29+
30+
jobs:
31+
comment:
32+
runs-on: ubuntu-latest
33+
# You control the trigger conditions:
34+
if: >-
35+
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@coder')) ||
36+
(github.event_name == 'issues' && contains(github.event.issue.body, '@coder'))
37+
environment: start-ai-workspace
38+
timeout-minutes: 5
39+
steps:
40+
- name: Start Coder workspace
41+
uses: coder/start-workspace-action@main
42+
with:
43+
github-token: ${{ secrets.GITHUB_TOKEN }}
44+
github-issue-number: ${{ github.event.issue.number }}
45+
github-username: >-
46+
${{
47+
(github.event_name == 'issue_comment' && github.event.comment.user.login) ||
48+
(github.event_name == 'issues' && github.event.issue.user.login)
49+
}}
50+
coder-url: ${{ secrets.CODER_URL }}
51+
coder-token: ${{ secrets.CODER_TOKEN }}
52+
template-name: ${{ secrets.CODER_TEMPLATE_NAME }}
53+
workspace-name: issue-${{ github.event.issue.number }}
54+
parameters: |-
55+
Coder Image: codercom/oss-dogfood:latest
56+
Coder Repository Base Directory: "~"
57+
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."
58+
Region: us-pittsburgh
1959
```
2060
21-
This command will:
22-
1. Compile the TypeScript source code
23-
2. Bundle it into a single file (dist/index.js)
24-
3. Add a source hash to the file
25-
26-
### Build Verification
27-
28-
This project includes a build verification system that ensures the compiled code matches the source code. A hash of all files in the `src/` directory is stored in the compiled output file.
29-
30-
To verify the build is up to date:
31-
32-
```bash
33-
bun run verify-build
61+
## Inputs
62+
63+
| Input | Description | Required | Default |
64+
| --------------------- | ------------------------------------------------------------------------------------------------------- | -------- | --------------------- |
65+
| `github-token` | GitHub token for posting comments | No | `${{ github.token }}` |
66+
| `github-issue-number` | GitHub issue number where comments will be posted | Yes | - |
67+
| `github-username` | GitHub username of the user for whom the workspace is being started | No | - |
68+
| `coder-username` | Coder username to override default user mapping (only set one of `github-username` or `coder-username`) | No | - |
69+
| `coder-url` | Coder deployment URL | Yes | - |
70+
| `coder-token` | API token for Coder | Yes | - |
71+
| `template-name` | Name of the Coder template to use | Yes | - |
72+
| `workspace-name` | Name for the new workspace | Yes | - |
73+
| `parameters` | YAML-formatted parameters for the Coder workspace | Yes | - |
74+
75+
## How It Works
76+
77+
1. The action posts an initial comment on the GitHub issue
78+
2. If `github-username` is set, it looks up the Coder user that matches the GitHub user. The Coder user must've either logged into Coder or connected external auth using the same GitHub account. If `coder-username` is set, it uses that Coder user instead.
79+
3. It starts a Coder workspace using the specified template and parameters
80+
4. If successful, it updates the comment with the workspace URL
81+
5. If it fails, it updates the comment with an error message
82+
83+
## Requirements
84+
85+
- A Coder deployment with API access
86+
- Appropriate secrets configured in your repository or environment
87+
88+
## Security Recommendations
89+
90+
This action requires a Coder admin API token to create workspaces. To limit access to this sensitive token:
91+
92+
1. Create a GitHub environment (e.g., "coder-production")
93+
2. Store your `CODER_TOKEN` and other secrets in this environment
94+
3. Restrict the environment to specific branches (e.g., main)
95+
96+
Example workflow configuration:
97+
98+
```yaml
99+
jobs:
100+
start-workspace:
101+
runs-on: ubuntu-latest
102+
# Important: Use an environment to restrict access to secrets
103+
environment: coder-production
104+
steps:
105+
- name: Start Coder workspace
106+
uses: coder/start-workspace-action@main
107+
with:
108+
coder-token: ${{ secrets.CODER_TOKEN }}
109+
# other inputs...
34110
```
35111

36-
### Pre-commit Hook
37-
38-
A pre-commit hook is set up to automatically build and verify the code before each commit. This ensures that the `dist/index.js` file is always up to date with the source code in the `src/` directory.
39-
40-
## CI/CD
112+
This ensures the Coder API token is only accessible to workflows running on approved branches.
41113

42-
A GitHub workflow is set up to verify that the build is up to date on each push and pull request. This prevents commits with outdated builds from being merged into the main branch.
114+
## License
43115

44-
This project was created using `bun init` in bun v1.2.6. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
116+
[MIT](LICENSE)

0 commit comments

Comments
 (0)