GitHub

The GitHub integration brings your repositories into the conversation. Once an admin installs the Freesbe app on your GitHub organization:

• Channels subscribe to repositories and get a card for each pull request, issue, release and deployment, and, if you pick them, reviews, comments, commits and workflow runs.
• The same card stays current. When checks pass or fail, someone approves, or the pull request is merged or closed, its card changes in place instead of adding another message.
• Close issue, Reopen and Comment buttons on the cards act in GitHub.
• Links show a preview. Paste a link to a pull request, issue, commit or lines of code, and everyone in the conversation sees what it is, even in a private repository.
• /github subscribes a channel from the chat, and Create GitHub issue in any message’s ⋯ menu turns the message into an issue.

GitHub posts as its own member, GitHub, so its cards are easy to tell apart from people. It works with organizations and personal accounts on github.com.

Connect GitHub

Only owners and admins can connect it. You need to be an owner of the GitHub organization, or be allowed to install apps on it.

1. Open Workspace settings → Integrations & apps → Integrations → Dev tools and click Connect GitHub.
2. GitHub asks where to install the Freesbe app. Pick your organization, then pick All repositories or Only select repositories. Freesbe only sees the repositories you pick here, and you can change them in GitHub later.
3. Click Install. GitHub brings you back to Freesbe, which says GitHub connected.

A workspace connects one GitHub organization or account. To stop, click Disconnect: cards, previews, /github and Create GitHub issue stop, and your subscriptions are kept for when you connect again. To take the app off your organization too, uninstall it in GitHub under Settings → GitHub Apps. If someone uninstalls or suspends it in GitHub, Freesbe shows Needs reconnecting until it’s installed again.

Subscribe a channel

A subscription says which repository posts into which channel, and what about. Add one in either place:

• In settings: under Channel subscriptions, click Subscribe a channel, pick the repository and the channel, and tick what to post.
• In the channel: type /github subscribe northwind-traders/storefront. Anyone in the channel can do it, for a repository the app can see.

A new subscription posts pull requests, issues, releases and deployments, like GitHub’s app for other chat tools. You can also pick:

Pick	Posts
Pull requests	A card when one is opened, ready for review, merged or closed
Reviews	A reply under the pull request’s card for each review
Issues	A card when one is opened, closed or reopened
Comments	A reply under the card for each comment on an issue or pull request
Commits	Pushes to the default branch, or the branch you name
Releases	Each published release, with its notes
Deployments	A card per deployment that follows it from pending to success or failure
Workflow runs	Each finished GitHub Actions run on the default branch or yours

Two filters keep a busy repository quiet:

• Only these labels: issues and pull requests with one of the labels you list, like bug, customer. In the channel, add label:bug to the command.
• Branch: commits and workflow runs on that branch instead of the default one. In the channel, add branch:release.

Draft pull requests wait until they’re ready for review. Open a subscription’s ⋯ menu to Post a sample card, Edit it, turn it off for a while, or delete it.

The cards

A pull request’s card shows its title, number and author, the branches, how many lines it adds and removes, its labels, and who’s asked to review. As GitHub tells Freesbe more, the card adds:

• Checks: running, passed or failed.
• Reviews: who approved and who asked for changes.
• The end: merged by whom, or closed without merging.

Issue cards show the labels and who it’s assigned to, and turn grey when the issue is closed. Deployment cards say which environment, and change from pending to success or failure.

When the same delivery comes from GitHub twice, it’s posted once. Cards stay current for 90 days; after that, a new event about an old pull request posts a new card.

Act from the card

• Close issue and Reopen, on issue cards, change the issue in GitHub with a comment saying who pressed it (Closed from Freesbe by Maya Chen), and the card changes right away.
• Comment, on issue and pull request cards, asks for a comment and adds it in GitHub, signed with your name.
• Open on GitHub opens it in your browser.

GitHub records these as the Freesbe app, with your name in the comment, so anyone in the channel can use them without a GitHub account.

Create an issue from a message

In any message’s ⋯ menu, click Create GitHub issue (or type /github open). Pick the repository, and Freesbe fills in the title and description from the message for you to change. The repositories the channel is subscribed to come first.

The issue links back to the message, and its card is posted in the message’s thread, so the conversation and the issue point at each other.

Link previews

When someone posts a link to a pull request, issue, commit or a few lines of code (…/blob/main/src/tax.ts#L10-L20) in a repository the app can see, Freesbe adds a preview under the message: its state, author and checks, or up to 20 lines of the code. A message gets up to three previews.

Previews come from the app’s access, so people see what’s in a private repository the workspace connected even if they have no GitHub account. Turn off Show a preview under GitHub links if you’d rather they didn’t. Links to repositories the app can’t see get no preview.

/github

Command	Does
/github subscribe owner/repo [features]	Subscribes the channel, optionally to the features you list
/github unsubscribe owner/repo [features]	Stops some or all of what it posts
/github list	Lists what this channel follows
/github open	Opens a new issue
/github help	Shows these

The features are pulls, reviews, issues, comments, commits, releases, deployments and workflows.

Privacy

Freesbe keeps the installation’s id and which repositories each channel follows. It reads pull requests, issues, commits and file lines only to show cards and previews, and doesn’t copy your code anywhere else. GitHub’s access token is kept encrypted and lasts an hour at a time.

Troubleshooting

• Connect GitHub is greyed out: GitHub isn’t set up on this server yet.
• Nothing posts: check the repository is one you gave the app in GitHub (Settings → GitHub Apps → Freesbe → Configure), and that the subscription is on. Post a sample card checks the channel side.
• A link gets no preview: the repository isn’t one the app can see, or previews are off.
• The install went to the wrong organization: click Disconnect, uninstall the app there in GitHub, and connect again.