GitHub and Linear

Owners and admins connect GitHub accounts and Linear workspaces under Settings → Integrations, and choose the repositories and teams that take issues. Every member of your team then creates and links issues from a post's page.

Connect GitHub#

1. Under Settings → Integrations, choose GitHub and click Connect GitHub.
2. On GitHub, authorize the Swingback app as yourself. If the app isn't installed on your account or organization yet, GitHub's install page comes next: choose the repositories it may reach.
3. GitHub sends you back to Settings → Integrations, which lists the account's repositories. Enable the ones that take issues.

Some details:

• Finish within 10 minutes, in the browser where you started. Otherwise, start again.
• You see the repositories your own GitHub account reaches, and nothing else. A colleague with more access, or a repository created since, shows after Connect … again on the account.
• In your repositories, the app reads and writes issues and their comments. It never asks for your code.
• GitHub's page says that the app may act on your behalf: it says so of every GitHub App a person authorizes. When you connect, Swingback uses that to ask GitHub which accounts and repositories you reach, and for nothing else. It keeps no token of yours, and what it writes on GitHub is written as the app.
• If you may not install apps on an organization, GitHub sends its owners a request instead. Connect again once they agreed.
• When the app is installed on several accounts you reach, the page lists them: pick the one to connect. Connect another account adds the next one. A product spread over several organizations connects each of them.

Connect Linear#

1. Under Settings → Integrations, choose Linear and click Connect Linear.
2. On Linear's page, an admin of your Linear workspace installs the Swingback application and picks the teams it may reach.
3. Linear sends you back to Settings → Integrations, which lists those teams. Enable the ones that take issues.

Some details:

• Finish within 10 minutes, in the browser where you started.
• The application acts as itself, not as you. What it creates and writes in Linear shows as the application's, and it takes no paid seat.
• A Linear workspace connects to one Swingback workspace at a time.
• A team the application gains in Linear shows in Swingback within a day, or right after Connect … again.

Choose where issues go#

A connection lists every repository or team it reaches under Other repositories or Other teams. Nothing takes issues until you click Enable on it.

• Enabling shares it with your workspace. Every member may then search its issues and create issues there, whether or not they have an account on GitHub or in Linear.
• Say what each one holds. What it holds starts from the repository's or the team's own description. The dialog that creates an issue shows it under the name, and the AI reads it when it suggests where a post could go.
• A workspace takes issues in up to 50 repositories and teams, all connections together.
• Disable stops new issues there. The issues already linked stay linked, and keep following their posts.
• An archived repository can't be enabled. A repository or a team the connection no longer reaches is marked as such, and takes no new issue.

Create and link issues#

A post's page in the dashboard has a Linked issues card. It shows each issue with its state, and what that state makes of the post.

Create an issue from a post#

Click Create issue. The dialog lists the repositories and teams that take issues, each with a box:

• Check every place the request needs work: one issue is created in each. A request for offline mode may need the web app, the mobile app and the backend.
• With routing rules, the places they name for the post are already checked.
• The title and the text start as the post's. Change them for the people who will do the work.
• Labels are optional, separated by commas, up to ten an issue. In Linear, they are the team's or the workspace's labels, by name; one Linear doesn't have is left out.

The issue is created a moment later, and the card follows it without a reload. If one of several can't be created, the others still are, and the dialog says why beside the one that failed.

What leaves for the tracker is the title and the text you confirmed, plus the post's two addresses (in your dashboard and on your portal) and its number of votes. Never a customer's name, email or company. Mentions and references in the text are taken out of action, so an issue pings no one and links nothing by accident.

Link an issue that exists#

Click Link an issue, pick the repository or team, then find the issue: the field searches as you type, and also takes an issue's address, its number on GitHub (#123) or its key in Linear (ENG-123).

A post links up to 20 issues. Unlink removes the link from the post: the issue stays as it is on its tracker, no longer lists the post, and no longer moves it. The notes that came from its comments go with the link.

Public repositories#

Anyone on the internet reads a public repository's issues. So a post that not everyone may see on your portal (a private post, a post on a private board, a post held for review) goes to a public repository only with your word: the dialog shows a warning and a box to check, and never checks a public repository for such a post by itself.

What engineers see on the issue#

Each issue says which posts ask for it:

• On GitHub, one comment by the app lists the posts that link the issue, each with its number of votes and its two addresses. The app keeps that comment up to date; it never rewrites what a person wrote.
• In Linear, each post is two attachments on the issue: its page in your dashboard, with its votes, and its page on your portal.

Statuses, both ways#

Each direction has its switch, per connection, under Statuses and comments. Both are on by default.

An issue moves its posts#

About a minute after an issue changes, the posts that link it take the status its state gives.

On GitHub, you choose what each state gives, under the connection's Statuses and comments:

The two labels are empty until you name them: type the name of a label your repositories use.

In Linear, each workflow state speaks by its type until you say otherwise, under the team's Workflow states:

A post with several issues follows them together:

• It is Completed once every issue that still counts is done.
• It is In progress as soon as one is under way or done while others remain.
• It is Closed only when every issue was closed as not planned or canceled.
• Otherwise it takes the most advanced of Planned and Under review that its issues give.

Followers hear of a status the issues gave as of any status change. Tell followers when issues move a post turns that off for a connection.

A post moves its issues#

When a person on your team, or an API key, sets a post's status, its issues move too. Before you save, the status form says what the change asks of each issue ("acme/web #12 closes as completed"), and Move the linked issues too lets you change the post alone.

• With one issue, the issue mirrors the post, forward or back: it closes, reopens, or takes the label or the workflow state of the status.
• With several, issues only move forward: open issues close with the post, and those behind move up to it. Nothing is reopened, since the post can't say which part of the work went back.
• On GitHub, "Planned" and "In progress" are the two labels above. In Linear, a status sends issues to the first workflow state that gives it, or to the one you choose under Workflow states.

A status the sync set is never sent back: the two sides settle instead of answering each other.

Comments, both ways#

An issue's comments on its posts#

What people write on a linked issue shows on its posts as internal notes, with who wrote it and a link to the comment. Your portal never shows them.

• Only people's comments come in: never a bot's, never the app's own.
• A note from an issue is read-only in Swingback. It changes when its comment is edited, and goes when the comment is deleted or the issue is unlinked.
• Comments written before the issue was linked stay where they are.

A post's comments on its issues#

A post's comments and internal notes are copied to its issues about half a minute after they are written. Each copy says what kind of person wrote it ("A customer commented", "The team wrote an internal note") and never a name.

You choose where each kind goes, per connection:

A public repository only ever gets the comments anyone may see on your portal. Sending internal notes to every repository asks for a confirmation first, since anyone could then read them on a public one. A Linear team is private to its workspace: its two choices are its issues, or nowhere.

A setting applies to what is written from then on. A tighter one also removes the copies it no longer allows.

Publish an issue's comment on the portal#

An engineer's answer on an issue is often what customers wait for. A connection can publish such comments on the issue's posts, as public comments instead of internal notes. Both ways are off until you turn them on, under Comments published on the portal:

• With a line in the comment. With Let a comment's author publish it on, the author of a comment writes /swingback-public alone on its first or last line. The comment then shows on the portal, without that line. It works on any repository and in Linear. Taking the line away takes the comment back.
• By itself, on public repositories. With Publish what the team writes on public repositories on, the comments that a repository's own people write there are published without a line, from the moment you turn it on.

Only your team's words are published:

• On a public repository, where anyone may comment, the team is who GitHub says belongs to the repository: its owner, the members of the organization that owns it, and its collaborators. What anyone else writes there stays an internal note, with the line or without.
• On a private repository, whoever may comment is your team.
• In Linear, a guest of the workspace publishes nothing.

A published comment carries its text and nothing else: no issue name, no number, no link, and not its author's name. On the portal it is signed "GitHub" or "Linear", with your team's badge, and the post's followers hear of it as of any comment. Customers can't reply to it in place; they comment on the post.

To take one off the portal, open the post in the dashboard and choose Hide from the portal in the comment's menu. Turning a setting off takes nothing back by itself: it applies to comments written or changed from then on.

Routing rules#

Routing answers "where does this post's issue go?" before anyone has to. Once GitHub or Linear is connected, Issue routing at the top of Settings → Integrations opens its page.

A rule sends the posts of a board, the posts that have one of some tags, or both, to one or more repositories and teams, each with the labels its issues take. For example: every post of the board "Mobile" goes to acme/ios with the label feedback, and posts tagged "sync" go to acme/api.

• A post's issues go to the places of every rule that matches it, in the rules' order, each once.
• When you click Create issue on a post, those places are checked and their labels are set. You still decide.
• A rule needs a board or a tag: no rule takes every post.
• A rule whose tags were all deleted says Matches nothing until you give it tags again.
• A rule keeps a repository or team that stopped taking issues, and says so beside it. No issue goes there meanwhile.
• A workspace has up to 50 rules.

Automatic issues#

By default, a rule only prepares the dialog. With Create a post's issues when it takes a status on, the rules create the issues themselves: when a person on your team or an API key gives a post the status you chose ("Planned" unless you change it), each place its rules name gets an issue with the post's title and text.

• It starts with the posts that take the status after you turn it on. Posts that already had it get nothing.
• Once per post and place, and up to 50 issues a day for the workspace.
• Never for a post that not everyone may see in a public repository. Create that one by hand, where the dialog asks first.
• A status that the sync itself gave a post creates nothing.

Posts that wait for an issue#

A post that reached the status you chose, or a later one up to "In progress", and has no issue shows under Review → Waiting for an issue, with the places its rules would send it to. Create issue opens the post on the dialog.

AI suggestions and drafts#

The model helps with the two questions an issue asks. It only suggests: a person or a rule creates an issue, never the AI.

• Where could it go? In the dialog, Ask AI where it could go has the model pick up to three of your repositories and teams for the post. Its picks are marked Suggested by AI and are never checked by themselves: check one to use it, or Dismiss it, and it isn't suggested for that post again.
• By itself, for the posts no rule routes. With Ask AI where the posts no rule routes could go on, each such post that waits for an issue is asked about once. The suggestions show under Review → Waiting for an issue, where you create the issue or dismiss the suggestion.
• What should it say? Draft with AI rewrites the dialog's title and text for engineers, from the post. Read the draft and change it before you create the issue.

The post's title and text go to Anthropic, with the names and descriptions of your repositories and teams when it suggests one. Asking where an issue could go counts the post as one AI read of your plan, unless the AI already read it this month; asking again about the same post is another read. Each draft counts as one AI draft. See AI features.

When a connection stops#

A connection stops when its tracker takes the access away: the app was removed from the GitHub account or suspended there, or the application was removed from the Linear workspace. Settings → Integrations marks it Stopped and says why.

• Nothing syncs meanwhile, and no issue is created. Your links, your settings and your rules are kept.
• For a removed app or application, click Connect … again on the connection. For a suspended GitHub app, the account's owner lifts the suspension on GitHub, then you click Check the connection.

Short outages don't stop a connection: when GitHub or Linear asks to slow down, Swingback waits as long as it's told, and tries again.

Disconnect#

Disconnect removes a connection from your workspace:

• Its repositories or teams, every link to their issues, the notes that came from those issues and the comments published from them all go.
• Posts keep the status they have.
• The issues stay on GitHub and in Linear. The comments Swingback copied to GitHub issues are deleted; what the application wrote in Linear stays, since disconnecting ends its access there.
• On GitHub, the app stays installed until the account's owner removes it there.

Read a post's issues from the API#

An API key reads the issues a post links, with their states. Creating and linking are done by your team in the dashboard; no key does either.

curl https://api.swingback.dev/v1/workspaces/$SWINGBACK_WORKSPACE_ID/posts/$POST_ID/issue-links \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"

An agent connected to the MCP server sees the same issues on a post it reads. API keys are part of the Pro plan: see the REST API.