GitLab Slack App Manifest Update: Self-Managed Checklist

GitLab documents that new GitLab for Slack app features may require manually updating the private app copy on Self-Managed instances. This checklist covers reviewing that manifest change and validating the integration afterward. See the official administration guide.

Updating the Slack app manifest is operational maintenance, not a copy-paste job. When GitLab publishes a new manifest, it often adds OAuth scopes, changes event subscriptions, or introduces redirect URLs. Slack applies these changes as a live configuration update. If a new scope triggers a workspace reinstall prompt, the app can sit in an unverified state until an admin steps in.

This checklist walks through updating the private GitLab for Slack app manifest safely. Before you touch production Slack settings, make sure you have instance administrator access to your GitLab Self-Managed deployment and app management privileges in your Slack workspace.

Step 1: Confirm you need a manifest update (and what this guide does not cover)

You need a manifest update when your upgraded GitLab Self-Managed instance introduces features that depend on newer Slack bot scopes, event subscriptions, or modified webhook callback paths. If your installed Slack app still runs on an older JSON definition, the GitLab backend rejects incoming events, or Slack drops them because the bot lacks the permissions.

Skip this guide if you run the legacy GitLab Slack Notifications integration built on incoming webhooks. That mechanism relies on static webhook URLs pasted into individual project settings and has no app manifest. If you're diagnosing a broken pipeline ping on a legacy webhook, read our guide on self-hosted GitLab Slack webhook troubleshooting instead.

This guide is for administrators maintaining a private GitLab for Slack app. MergeMe is a separate option supporting GitHub.com, GitLab.com and self-hosted GitLab in one workspace, with one updating Slack card per PR/MR.

Step 2: Save a baseline copy of the current Slack manifest securely

Never modify a production Slack app without capturing its current configuration. If you overwrite the manifest and break message routing, there's no undo button to restore your prior settings.

Log in to api.slack.com/apps with an account that has administrative permissions for your target workspace. Select your private GitLab app from the list. In the left navigation menu, go to Features and click App Manifest. Choose the JSON tab.

Copy the current JSON into a restricted local file. Use encrypted storage according to your organization policy; umask limits file permissions but does not encrypt contents:

umask 077 cat << 'EOF' > /tmp/slack_manifest_baseline.json { ... paste manifest here ... } EOF

Verify that the saved baseline is valid JSON by passing it through jq:

jq empty /tmp/slack_manifest_baseline.json

If jq returns no errors, your baseline is clean. Keep this terminal session open. If you need to revert quickly, this file is your recovery artifact. Check whether your existing manifest contains custom redirect URLs or non-standard bot scopes that your security team added during initial onboarding. Pasting an upstream manifest straight from GitLab wipes those additions unless you track them in this baseline.

Step 3: Download the latest manifest from Admin > Settings > General > GitLab for Slack app

Your GitLab Self-Managed instance generates an app manifest matched to its exact version and public hostname. Don't copy a generic template from community forums. Grab the payload from your GitLab administrative interface.

In GitLab, select Admin > Settings > General and expand GitLab for Slack app. Select Download latest manifest file to download slack_manifest.json, as described in the official administration guide.

Save the downloaded JSON as /tmp/slack_manifest_upstream.json using restricted permissions. If copying its contents into a file, use:

umask 077 cat << 'EOF' > /tmp/slack_manifest_upstream.json { ... paste upstream manifest here ... } EOF

Run jq validation on this file too:

jq empty /tmp/slack_manifest_upstream.json

Look at the URLs inside this file. If your GitLab instance sits behind an internal reverse proxy, or an ingress controller terminates TLS under a different domain name, check that these generated URLs match the publicly reachable endpoint Slack expects. If the domains don't line up, fix the GitLab external_url or your reverse proxy configuration before continuing.

Step 4: Compare baseline and new manifests with redacted jq commands

Never replace a manifest blind. Inspect the structural differences between your running app and the new definition. Upgrades routinely alter oauth_config scopes, slash command targets, and event subscriptions.

To see the operational changes without leaking internal callback tokens or project-specific paths into terminal logs, run a filtered jq diff:

diff -u
<(jq -S 'del(.settings.event_subscriptions.request_url, .settings.interactivity.request_url)' /tmp/slack_manifest_baseline.json)
<(jq -S 'del(.settings.event_subscriptions.request_url, .settings.interactivity.request_url)' /tmp/slack_manifest_upstream.json)

Watch changes under oauth_config.scopes.bot. If the diff shows newly requested scopes, such as chat:write.customize or users:read, Slack demands a full workspace reauthorization the moment you save. If scopes were removed, check whether any existing automations rely on them.

Next, inspect the slash commands section. The /gitlab command configuration should show matching endpoints in baseline and upstream. If you customized the command description or added auxiliary slash commands, merge those keys by hand into /tmp/slack_manifest_upstream.json before touching Slack.

If notification mapping across multiple teams is getting unwieldy, consider channel-level routing rules. GitLab supports instance-level settings, but you can also read up on how to route GitHub PRs and GitLab MRs to Slack channels by label to clean up noisy alerts once the base app connection is stable.

Step 5: Stage the change: edit in Slack App Manifest > JSON, Save Changes, and check whether Slack asks for a reinstall

With your diff analyzed and any custom paths merged, apply the changes in your Slack workspace. Return to api.slack.com/apps and go back to Features > App Manifest for your private GitLab app. Make sure the JSON tab is selected.

Paste your prepared JSON payload from /tmp/slack_manifest_upstream.json into the editor. Slack lints the text automatically. If you introduced a syntax error or referenced an unsupported scope string, the editor highlights the broken line in red and disables the Save Changes button.

Click Save Changes. Once saved, look at the top of the page right away. If the new manifest modified any OAuth scopes or token handlers, Slack shows a yellow banner: 'You need to reinstall your app to workspace to apply these changes.'

If the banner appears, your GitLab integration won't work on the new scopes until you finish the reauthorization handshake. Click Reinstall to Workspace. Slack sends you through the standard permissions consent screen. Confirm that the listed access matches what you reviewed in your Step 4 diff. Click Allow.

If your organization enforces workspace permission policies where Slack admins must approve all scope upgrades, talk to your workspace owner before you click save. An unapproved app stuck in pending review silently halts outgoing notifications. If credentials change unexpectedly during this phase, check our runbook on GitLab Slack notifications after token rotation to keep your tokens synchronized.

Step 6: Validate with /gitlab help, then a real event in a permitted project

Don't declare success because Slack accepted the JSON. Verify in two stages: an interactive command check, then an asynchronous event test.

Open your Slack client and go to a private test channel where the GitLab bot is an invited member. Run the slash command:

/gitlab help

If the command responds with the GitLab help dialog, your bot token and interactivity endpoints work. But slash commands only prove inbound routing from Slack to GitLab. They say nothing about whether GitLab can publish notifications back to Slack when project activity happens.

To validate outbound event delivery, open a test repository on your Self-Managed instance. Make sure the project settings integrate with your Slack workspace. Create a test merge request, push a commit, or post a comment. Watch your test channel in Slack.

If the slash command worked but the merge request notification never posted, you likely have an authorization mismatch or a channel permission failure, not a manifest syntax error. Admins hit this often: the GitLab Slack test works but merge request notifications missing. Verify that the bot user was invited to the Slack channel with the /invite @gitlab command. Private Slack channels drop automated messages entirely if the bot user hasn't been explicitly added.

Step 7: Roll back or troubleshoot, and where the permissions, webhook and token guides take over

If testing reveals systemic failures, such as 500 errors on slash commands or total notification silence, run your rollback plan immediately. Open api.slack.com/apps, go to Features > App Manifest, paste the baseline JSON from /tmp/slack_manifest_baseline.json, and click Save Changes. Reinstall the app to the workspace if prompted. This restores the known working OAuth scopes and endpoints while you inspect instance logs.

If you'd rather diagnose forward, pull the GitLab production logs on your server:

gitlab-ctl tail gitlab-rails/production_json.log | jq 'select(.meta.caller_id // "" | contains("Slack"))'

Review relevant logs without sharing credentials or private payloads. HTTP status codes alone do not identify the root cause; correlate the exact error response with configuration and permissions.

MergeMe supports GitHub.com, GitLab.com and self-hosted GitLab in one workspace and posts one updating Slack card per PR/MR. Evaluate its setup separately from the official app manifest workflow.

Conclusion

Updating your private GitLab Slack app manifest keeps your Self-Managed instance secure and compatible with new API requirements, but it demands strict operational hygiene. Always save a JSON baseline, diff scope changes before applying them, and confirm asynchronous delivery with a real merge request event instead of relying on /gitlab help alone.

MergeMe supports GitHub pull requests and GitLab merge requests in Slack as one updating card per PR/MR. Self-hosting is available by enquiry at hello@mergeme.dev.