GitLab

The GitLab integration brings your projects into the conversation, on GitLab.com or on a GitLab server you run yourself. Once an admin connects GitLab:

• Channels subscribe to projects and get a card for each merge request, issue, release and deployment, and, if you pick them, comments, pushes, tags and pipelines.
• The same card stays current. When a pipeline passes or fails, someone approves, or the merge 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 GitLab.
• Links show a preview. Paste a link to a merge request, issue or commit, and everyone in the conversation sees what it is, even in a private project.
• /gitlab subscribes a channel from the chat, and Create GitLab issue in any message’s ⋯ menu turns the message into an issue.

GitLab posts as its own member, GitLab, so its cards are easy to tell apart from people.

Connect GitLab

Only owners and admins can connect it. Freesbe acts in GitLab as the person who connects it, so connect with a GitLab account that’s a member of the projects your channels will follow. Adding Freesbe’s webhook to a project needs the Maintainer role on it.

GitLab.com

1. Open Workspace settings → Integrations & apps → Integrations → Dev tools and click Connect GitLab.com.
2. GitLab asks you to authorize Freesbe. Click Authorize.
3. GitLab brings you back to Freesbe, which says GitLab connected.

Your own GitLab server

A self-managed server connects through an application you make on it, so Freesbe never needs an admin password or token.

1. In Freesbe, click Self-managed next to Connect GitLab.com, and pick Yes, it’s on the internet. Copy the redirect URI it shows.
2. On your GitLab server, open Admin area → Applications (or a group’s Settings → Applications) and click Add new application. Name it Freesbe, paste the redirect URI, tick Confidential and the api scope, and save.
3. Back in Freesbe, enter your server’s address (https://gitlab.northwind.example), the Application ID and the Secret, and click Continue to GitLab.
4. Click Authorize on your server. Freesbe says GitLab connected.

This needs your server to be reachable from the internet over https, so Freesbe can call it.

A private server behind your firewall

If only your own network or VPN reaches your GitLab, connect it as a private server. Freesbe never calls it: your server’s webhooks send Freesbe the events, and everything else opens GitLab in the person’s browser, which is on your network.

1. In Freesbe, click Self-managed, pick No, it’s private, enter your server’s address, and click Connect. There’s no sign-in.
2. Freesbe shows a Webhook for your projects: a URL and a secret token.
3. In GitLab, for each project you’ll subscribe a channel to, open Settings → Webhooks → Add new webhook. Paste the URL and the secret token, tick Push, Tag push, Comments, Issues, Merge request, Pipeline, Deployment and Releases events, and save. Leave confidential issues and comments unticked. You can add it to a group instead, on GitLab Premium.

Your server needs to be able to send to Freesbe over the internet (most can; if yours can’t, allow api.freesbe.net). On a private server:

• Cards post and stay current just the same.
• The cards’ only button is Open in GitLab.
• Create GitLab issue and /gitlab open give you a link per project that opens GitLab’s new issue page with the title and description already filled in from the message.
• Links get no previews, and you type a project’s path when subscribing, since Freesbe can’t look your projects up.

A workspace connects one GitLab server. Changes made from Freesbe show in GitLab under the connecting person’s name, and the comment says who in Freesbe made them. To stop, click Disconnect: Freesbe takes its webhooks off your projects, and cards, previews, /gitlab and Create GitLab issue stop. To remove Freesbe’s access in GitLab too, revoke it under Preferences → Applications. If the access is revoked there first, Freesbe shows Needs reconnecting until someone connects again.

Subscribe a channel

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

• In settings: under Channel subscriptions, click Subscribe a channel, pick the project and the channel, and tick what to post.
• In the channel: type /gitlab subscribe northwind/storefront, with the project’s path. Anyone in the channel can do it, for a project the connecting person is a member of.

When a channel first subscribes to a project, Freesbe adds a webhook to it in GitLab (you’ll see it under the project’s Settings → Webhooks). If the connecting person isn’t a Maintainer there, the subscription says Nothing posts yet and why; ask a Maintainer to connect GitLab, or turn the subscription off and on again once you have the role.

A new subscription posts merge requests, issues, releases and deployments. You can also pick:

Pick	Posts
Merge requests	A card when one is opened, ready, merged or closed
Issues	A card when one is opened, closed or reopened
Comments	A reply under the card for each comment on an issue or merge request
Pushes	Commits pushed to the default branch, or the branch you name
Tags	Each new tag
Releases	Each new release, with its notes
Deployments	A card per deployment that follows it from running to success or failure
Pipelines	Each finished pipeline on the default branch or yours

Two filters keep a busy project quiet:

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

Draft merge requests wait until they’re ready. Confidential issues and internal comments never post. Open a subscription’s ⋯ menu to Post a sample card, Edit it, turn it off for a while, or delete it.

The cards

A merge request’s card shows its title, number and author, the branches, its labels and reviewers. As GitLab tells Freesbe more, the card adds:

• Pipeline: running, passed, failed or canceled.
• Approvals: who approved.
• The end: merged by whom, or closed without merging.

Issue cards show the labels and who it’s assigned to. Deployment cards say which environment, and change from running to success or failure.

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

Act from the card

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

Anyone in the channel can use them, without a GitLab account of their own.

Create an issue from a message

In any message’s ⋯ menu, click Create GitLab issue (or type /gitlab open). Pick the project, and Freesbe fills in the title and description from the message for you to change. The projects 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 merge request, issue or commit on your connected GitLab, Freesbe adds a preview under the message: its state, author, branches and pipeline. A message gets up to three previews. Links to other GitLab servers get none.

Previews come from the connecting person’s access, so people see what’s in a private project even if they have no GitLab account. Turn off Show a preview under GitLab links if you’d rather they didn’t.

/gitlab

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

The features are merge_requests, issues, comments, pushes, tags, releases, deployments and pipelines.

Privacy

Freesbe keeps your server’s address, which projects each channel follows, and the access GitLab gives it, encrypted, along with a self-managed application’s ID and secret. It reads merge requests, issues and commits only to show cards and previews, and doesn’t copy your code anywhere. Each project’s webhook sends to an address that doesn’t name your workspace, with a secret token Freesbe checks on every delivery.

Troubleshooting

• A private server’s cards don’t arrive: check the project’s webhook in Settings → Webhooks and click Test next to it. A failure there usually means your server can’t send to the internet, or the URL or secret token was pasted wrong.

• Connect GitLab.com is greyed out: GitLab.com isn’t set up on this server yet. A self-managed server can still connect.

• GitLab says the redirect URI is invalid: the application on your server needs exactly the redirect URI Freesbe shows.

• Nothing posts: check the subscription doesn’t say Nothing posts yet, that it’s on, and that the webhook is listed under the project’s Settings → Webhooks. Post a sample card checks the channel side.

• A link gets no preview: it’s on another GitLab server, the connecting person can’t see the project, or previews are off.