The Work page

The Work page lists the factory’s work items. Use it to add an issue, start a build and find the items that wait on you. Select a row to open the item’s page, where you review the work. See Review and merge.

Add work

Add an issue to the Work page to make it a work item and start its build. To start work that has no issue yet, see Draft a spec on a work item. You need the Add work permission. The button is off until the factory has a connected repository. A build needs a runner. See Set up a host or Run the runner in a container.

1. Choose Add work.
2. If the factory has more than one source, pick one in Source. A source is a repository, a Linear team or a Jira project.
3. In Find an issue, type the issue’s key, its URL, or words from its title or a label.
4. To list only the issues with a label, choose Label and pick one.
5. Choose Build beside the issue.
6. If Run this build on shows, pick Managed runners or Self-hosted runners.
7. Write Instructions for the agent if you want. See Give a build instructions.
8. Choose Build.

The item’s page opens. A runner claims the item and builds it. Run this build on shows only when the factory can use managed runners, which OuterLayer runs. See Managed runners. An issue that is already on the Work page shows Already added. To build an issue in a session of your own, choose Build locally instead of Build. See Debug a build in your own session.

Give a build instructions

Instructions are text for the agent that runs one build, up to 2,000 characters. The agent reads them as guidance from you. They never change which issue is built or which checks run. The issue’s criteria win if the two disagree. You can give instructions in four places:

• Add work. Write them in Instructions for the agent, in the second step.
• The first build of an item that is not started. Write them in the note field beside Build on the item page. See Build an item that is not started.
• A rerun. Write them in the rerun dialog on the item page. See Rerun a Stuck item.
• The CLI. Pass --instructions <text> to outerlayer work build.

Instructions belong to one build request. You cannot edit them after you send the request, and a later rerun does not reuse them. The Activity section of the item page shows them with the request. A rerun of an item with an open pull request is an amend. An amend does not use instructions, and the dialog says so.

Start a build with a label

Add the label outerlayer-build to an issue in GitHub, Linear or Jira. OuterLayer adds the issue to the Work page if needed and starts a build for you. You do not open the dashboard or a terminal. The build belongs to the person who added the label. OuterLayer matches that tracker user to a member:

• GitHub: your GitHub account must be the one you signed in to OuterLayer with.
• Linear and Jira: the email on your tracker account must equal your OuterLayer sign-in email. In Jira, your profile must show your email.

You also need the Add work permission. Only adding the label starts a build. Removing it, adding another label or editing the issue starts nothing. The label matches in any letter case. If the issue’s item has an open pull request, the label starts a rerun. It starts nothing when no review waits on an agent. OuterLayer replies with one comment on the issue. The comment links to the work item, or says why no build started. A reply needs a tracker connection that can write. See Replies need a write grant. The build starts with or without the reply. An item has at most one build queued or running. If you add the label again during a build, no second build starts. A label on an issue in a repository, team or project that the factory does not read starts nothing.

Change the label or turn it off

You need the Edit factory settings permission.

1. Open Settings, then Automations.
2. Under Issues, choose Start a build from a label.
3. To stop labels starting builds, turn the switch off.
4. To change the label, choose Edit, enter the label and choose Save.

The label has 1 to 50 characters and no spaces. It applies to every repository, Linear team and Jira project of the factory. The same page shows the run log: each time someone added the label, and what OuterLayer did. See Read the run log of a built-in automation. To act on new or labelled issues with rules of your own, see Automations.

Build an item that is not started

Some items are on the Work page with no build. An automation adds one when its issue must wait for a member. Build locally adds one for a session of your own. Such an item reads Not started. Read the issue before you build it. You need the Add work permission to start the build.

1. Open the item from the Work list.
2. To give the agent instructions, write them in the note field at the foot of the page.
3. Choose Build at the foot of the page.

The foot of the page then says that the build is queued, and who asked for it. A runner takes the item as it takes any other build. If no runner can take it, the item reads Not picked up. See When nothing is building an item. You can also start the build in one of these ways:

• Run outerlayer work build --item <number>. The number is the one before the item’s title on the Work page. See outerlayer work build.
• Add the build label to the issue. See Start a build with a label.

The Work list

The list has two tabs. Open groups its items by status, with the items that wait on a person first. Closed holds every item that shipped or whose issue closed, the most recently closed first. Each tab shows 25 items on a page.

Filter the list

The box above the list holds the whole filter as text, such as is:open status:stuck sort:cost. Type in it, or use the Status, Repository, Label, Builder, Asked by and Sort menus beside it. Each menu writes its choice into the box. The filter is in the page address. Bookmark a filtered view, or send its address to someone.

• A comma means OR within one qualifier: status:stuck,back.
• Different qualifiers combine with AND. Two label: qualifiers also mean AND: label:bug label:ui matches only an item with both.
• Any other word matches the item’s title, its number, its issue key or one of its labels. Every word must match.
• builder: and by: match only an item that someone builds now, so they match nothing on Closed.
• On Closed, status: matches only shipped.

Saved filters

The Saved filters menu, beside Add work, replaces the text in the box with one of five filters: Waiting on me leaves out an item with a failing check. To see every item that waits on a person, choose Needs you in the Status menu. To remove a filter, choose Clear current filters under the box.

What a row shows

A row whose pull request changes a file under .outerlayer/ says that it changes the repository’s rules. See Require a person’s review of rules changes. Press J and K to move between rows, and Enter to open the selected row.

Statuses

Each item has one status, on its row and on its page. The status says whose turn it is. An item moves to Closed when its issue closes in the tracker. Each tracker has its own rule for a closed issue. See Connect an issue tracker.

Find an item by its status

To filter by a status you read, use the Status menu or one of these words: The saved filters use a second set of words. These words also look at the item’s checks and reviews. Each item matches one word, the first of these that applies:

1. shipped: on Closed, every linked pull request merged.
2. stuck: the last build or amend failed or timed out, and nobody has asked again.
3. building: no pull request is open, a check has not passed, or a declared proof is missing.
4. with-agent: an agent holds the item, or a review waits for an agent’s answer.
5. merging: a person approved the latest push.
6. back: a person reviewed the item, and it is your turn again.
7. ready: nobody has reviewed the item yet.

The two sets do not match one to one. An item that reads Ready for review while a check fails matches status:building, not status:ready.

Remove an item from Work

Remove an item when nobody will build it, such as a duplicate issue or a dropped idea. Removing deletes nothing and does not close the issue. The item leaves the Open tab, and its history, sessions and cost stay. To bring the item back, add the issue again with Add work.

1. Open the item.
2. Select Remove from Work at the top right.
3. Read what the dialog says the removal stops.
4. To leave an open pull request open on GitHub, clear its Close … on GitHub box.
5. Enter a reason.
6. Select the button. It reads Remove from Work, Stop build and remove or Close pull request and remove.

OuterLayer records who removed the item, with the reason. If GitHub refuses to close a pull request, the dialog names it and the item stays on Work. You cannot remove an item that is already on Closed. You need the Add work permission to remove an item that you added. You need Withdraw others’ work when someone else added the item, or when it has a running build or an open pull request. See Roles and permissions. To remove an item from a terminal, see outerlayer work remove.