Write a work item
Create a work item, edit it in place, and see what Oxagen does in GitHub when you save.
A work item is one bounded piece of engineering work. You write it in Oxagen. If the repository has a GitHub collector that creates issues, Oxagen also makes the GitHub issue for you.
Create a work item
- Open Work and choose New work item.
- Under Describe the work, say what needs doing and why, in your own words. Choose Draft the work item to let stella fill the fields.
- Under Review the work item, check each field and change anything you want. Stella marks the fields it drafted, and you decide.
- Under Add the work item, choose Add to the inbox.
The item takes the next number in the workspace, such as WI-19, and goes to triage. Every new item is Open. Nothing is stored until you choose Add to the inbox.
Fields
| Field | What it holds |
|---|---|
| Title | One line, up to 300 characters |
| Description | Markdown, up to 20,000 characters. It can mention steering records and show attached files |
| Kind | Bug, New Feature, Improvement, Documentation, Test, or Chore. Optional. Stella picks one from your words when it can. Oxagen stores it as the item's Type label |
| Priority | P0 to P3. Optional. Triage keeps your priority and does not overwrite it |
| Assignee | A member of the workspace. Optional. It starts as you |
| Repository | owner/name. Optional. It decides which collector creates the GitHub issue |
| Labels | Up to 20 labels, each up to 100 characters |
| Attachments | Up to 20 files |
Rewrite with stella rewrites the title and description together. Read the result before you add the item, and use Undo to bring your own words back.
Attachments
Drop files on the description or choose Choose files. An image or a PDF can be up to 10 MB. A text, Markdown, CSV, or JSON file can be up to 1 MB. Oxagen checks that the bytes match the type and refuses SVG and HTML.
Oxagen scans text, Markdown, CSV, and JSON files for credentials and refuses a file that holds one. It does not scan images or PDFs. A file you upload and never save is deleted after 24 hours.
Only a signed-in person can attach a file. An API key or an agent run cannot.
Save and the GitHub issue
Saving never waits on GitHub. Oxagen stores the item first. Then, if the item names a repository, it looks for a collector to create the issue. The collector must:
- not be paused,
- read that repository, and
- have its Create the issue when a person saves a work item switch on.
If more than one collector qualifies, the oldest one creates the issue, so you never get two issues. The switch is on for every collector that writes back, including collectors added before the switch was on by default. To stop a collector from creating issues, turn the switch off in Work setup on the Collectors tab, in the collector's settings. If the repository lacks the item's kind or priority label, Oxagen creates the issue without that label.
Oxagen asks the collector to make the issue as soon as the save is stored, so the link usually shows within seconds. The collector's check every 15 minutes also makes any issue still waiting.
After you save, the dialog and the item page show where the create stands:
| Message | Meaning |
|---|---|
| Creating the issue in the tracker | The collector is making the issue. The line checks again every few seconds, for up to two minutes |
| Open the GitHub issue | The issue exists. For another tracker, the link names it, such as Open the Linear issue |
| Not created in the tracker, with a reason | No repository, no collector for that repository, or the switch is off. A failure shows the reason and Retry creating the issue |
A retry is safe. The issue carries a hidden marker with the item's id, and a retry adopts an issue that already has it.
Triage runs on the item whether or not an issue is created. Oxagen also does not import its own issue a second time as a new item.
Issue contents
- The title and the description, as Markdown.
- Each mention as the record's title in a code span, such as
@Release checklist. The text does not link to the record. A code span also keeps GitHub from pinging a user whose name matches the title. - The kind and priority as labels, and the item's other labels. The Blocked label goes only if the repository already has it.
- A link to the work item in Oxagen, when the workspace has one to give.
- An Attachments list of the item's files.
Attachment links
GitHub offers no way for an app to upload a file into an issue. So Oxagen puts a link in the issue. Each link holds a random token that is hard to guess. Oxagen keeps only a hash of it. Removing an attachment revokes its link. A link does not expire on its own.
A link works only when the deployment serves it. That depends on a deployment setting, WORK_ATTACHMENT_URL.
Links also need a private repository. On a public repository, anyone could read a linked file, so the issue lists each file by name with no link. A file with no link is listed by name only.
The server for /work-attachments/<token> still waits on a hosting decision. Until it ships, a link in an issue does not open a file.
Edit a work item
Open the item from Work. Each field saves on its own, so you change only what you mean to. Another person's edit that lands first makes your save fail, and the page shows their text.
An agent run, the in-app assistant, and a deployed agent cannot edit an item. An API key edits the title, description, labels, kind, and repository of an item that has no GitHub issue, but cannot set the assignee, priority, mentions, or files. Once an item has an issue, only a signed-in person edits its title and description.
Edits and GitHub
On an item with no GitHub issue, a title or description edit saves in Oxagen at once. On an item with a GitHub issue, the issue holds the text. Oxagen takes the edit only when the item's collector has the Update the title and description on GitHub Issues when they change in oxagen switch on. Oxagen then saves the edit and writes it to the issue.
The issue also holds the item's labels, kind, and repository. Edit those in GitHub.
- The switch is on for a new collector. A collector created before the switch existed keeps it off until a person turns it on.
- To turn it off, open the collector in Work setup, clear the switch, and save. Oxagen then refuses a title or description edit on that collector's items, and you edit the text in GitHub.
- Oxagen sends only the fields you changed. A title edit never rewrites the requester's body.
- If the issue changed in GitHub since Oxagen last read it, the write stops and the page says why. Your edit stays saved.
- A failed write shows Not updated in GitHub with the reason and Retry updating the issue.
Edits and the brief
An edit to the title or description in Oxagen keeps an approved brief approved, and triage does not run again. The item's history shows it as an edit made in Oxagen.
A change made in GitHub is different. It puts the brief out of date, and a person approves it again. A change to the labels or kind in Oxagen does the same, and it queues triage again.
Changing the assignee or priority moves only the item's version. Mentions and files save together with the description, so on an item with an issue they are written to GitHub with it.
Related pages
- Work for the path of one item from triage to done.
- Mentions and context for what the agent receives.
- GitHub for the connection and its collectors. Linear, Jira, and GitLab collectors have their own pages in Connections.