Handing work to Scaling from Linear

Connect Linear once, and your team can hand Scaling an issue the way they hand it to a colleague: by assigning it. Scaling shows up in the assignee menu of the Linear teams you map. Nothing else in Linear starts work: creating an issue, labelling it, mentioning Scaling in it or commenting on it does nothing.

​

Before you start

• You need to be an admin in your Scaling organisation. A member cannot see the Linear page in the product.
• You also need to be an admin of your Linear workspace. Linear only lets a workspace admin approve an app that can be assigned issues, so a Scaling admin who is only a member of the Linear workspace cannot finish connecting.
• Scaling needs at least one connected repository, because a team is mapped to one. See Connecting a repository.

​

Connect Linear

Choose Settings at the foot of the sidebar, then Linear, and choose Connect Linear. Linear opens and shows what Scaling is asking for. Approve it, and Linear sends you back to Scaling, which is now linked to your organisation. The page then says Connected to and the name of your Linear workspace, and the date you connected it. A workspace belongs to one Scaling organisation at a time. If yours is already connected to another organisation, the page says so, and nothing is linked until an admin there disconnects it. If you decline on Linear’s screen, nothing is connected and you can start again from Connect Linear. The link between the two screens works once and for ten minutes, so connect in one sitting.

​

What Scaling asks for, and why

Scaling asks Linear for four permissions and no others. It never asks for the admin permission. Be plain with yourself about what write is. Linear does not split it any finer, so it would let the app change any field of any issue in the teams it can reach: the title, the description, the assignee, the priority, labels and more. Scaling itself only ever does two things to an issue: it adds a comment, and it moves the issue’s workflow status. It changes the workflow status only on issues in teams you have mapped. In a team that is not mapped, the one thing Scaling does is leave a single comment on an issue that someone assigned to it, saying that no repository is mapped for the team. It changes nothing else there, and it does nothing on an issue nobody assigned to it. Limiting the app on Linear’s side, in the next section, is what turns that promise into a boundary you control.

​

Limit Scaling to your mapped teams

After you connect, open Scaling’s entry in your Linear workspace’s settings as a workspace admin, and limit its team access to the teams you map in Scaling. Do this for every team you add or remove later. A team the app cannot reach is a team where Scaling can neither read nor change an issue, whatever the permissions say.

​

Map a team to a repository

Under Teams on the same page, each Linear team in your workspace has its own form. An issue assigned to Scaling is built in the repository its team is mapped to. A team maps to one repository.

1. Choose the Repository.
2. Choose the state under When a run starts, move the issue to. This one is required, and the team’s first started state is chosen for you.
3. Choose the state under When a draft pull request opens, move the issue to. If the team has one started state the choice starts as None - leave it where it is. If it has two or more, the last started state is chosen for you. Choose None - leave it where it is to leave the issue where it is when the draft opens.
4. Choose Save mapping.

The states are listed in the team’s own order, as Linear’s workflow settings show them, and you can pick any of them. Scaling keeps each state by the state itself and not by its name, so renaming a state in Linear changes nothing. Remove mapping takes the team back out. An issue assigned to Scaling in a team that is not mapped starts nothing. Scaling leaves a comment on the issue that says no repository is mapped for its team and that an admin of your Scaling organisation can map one.

​

Hand an issue to Scaling

Open an issue in a mapped team and choose Scaling from the assignee menu. Scaling becomes the issue’s delegate and you stay the assignee, so the issue is still yours. This is the only thing that will start a run. Creating the issue, labelling it, mentioning Scaling in it and commenting on it all start nothing.

​

Disconnect

On Settings, Linear, choose Disconnect and confirm. Scaling gives back its access to your Linear workspace, forgets every team mapping, and holds nothing for the workspace afterwards. Scaling can no longer be chosen from the assignee menu, and an issue that still has Scaling as its delegate starts nothing. Disconnecting does not delete the comments Scaling already left or undo any state it moved. If Linear does not answer, the page says that disconnecting did not finish and that Scaling still holds its access. Choose Try again to carry on from where it stopped. You can connect again, to the same workspace or another, once it has finished. Removing the app in Linear’s own settings has the same effect as disconnecting.