GitLab setup guide

Agents work with your code, deployments and incidents.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open GitLab, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

GitLab can be connected 2 ways. Where there’s a key or token to paste, that’s usually the quickest.

Personal access token

API key.

1. Sign in as the GitLab user the agent should act as. A dedicated user (or a service account on Premium and Ultimate) keeps its work easy to spot. Give it at least the Reporter role in the projects the agent works in.
2. Select your avatar > Edit profile > Access > Personal access tokens (on GitLab.com: https://gitlab.com/-/user_settings/personal_access_tokens).
3. Choose Generate token > Fine-grained token (GitLab 19.2 and later). Limit Group and project access to the groups or projects the agent works in, then add these permissions: on the Group and project tab, Work Item (Read, Create, Update), Merge Request (Read, Create; Create is what lets it comment on merge requests) and Repository (Read); on the User tab, User (Read) and Project (Read, for listing projects). On older GitLab versions choose Legacy token instead and tick the api scope (read_api cannot comment or change issues).
4. Set an expiry date (GitLab allows up to 365 days unless your administrator changed the limit), generate the token and paste it into the form with your GitLab address.
5. You don't need to add a webhook: live updates from GitLab (starting work when an issue, comment or merge request changes) aren't available yet, so leave the webhook signing token empty.

Field	What to enter
GitLab address (optional)	Web address. Starts as https://gitlab.com. Change this only for GitLab Self-Managed or Dedicated, for example https://gitlab.example.com (no trailing slash).
Personal access token	A secret: Everdeck saves it encrypted and never shows it again. Where to find it.
Webhook signing token (optional, not used yet)	A secret: Everdeck saves it encrypted and never shows it again. Live updates from GitLab aren't available yet; leave this empty.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at GitLab until you delete or rotate it there.

Your GitLab OAuth application

Your OAuth app.

This way signs in with an OAuth app you create for GitLab, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

Its OAuth app belongs to one company and is tied to the token endpoint it was registered for: Everdeck sends the app’s secret only there.

1. Sign in as the GitLab user the agent should act as, select your avatar > Edit profile > Applications and select Add new application. (A group owner can instead create a group-owned application under the group's Settings > Applications.)
2. Name it "Everdeck", enter the redirect URI https://everdeck.io/api/oauth/callback and tick the api scope.
3. Select Save application, then copy the Application ID and the Secret into the form with your GitLab address.
4. You don't need to add a webhook: live updates from GitLab aren't available yet, so leave the webhook signing token empty.
5. Select Connect and approve access.

Field	What to enter
GitLab address (optional)	Web address. Starts as https://gitlab.com. Change this only for GitLab Self-Managed or Dedicated (no trailing slash).
Webhook signing token (optional, not used yet)	A secret: Everdeck saves it encrypted and never shows it again. Live updates from GitLab aren't available yet; leave this empty.

The scopes Everdeck asks for:

• api

When you disconnect, Everdeck asks GitLab to revoke the sign-in, then deletes the tokens it saved.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• List projectsTier 0 · ReadReads outside contentgitlab_list_projects

  List the projects you are a member of, most recently active first, with id, full path, default branch and web address. Use the numeric id as project_id in the other actions.

• List issues in a projectTier 0 · ReadReads outside contentgitlab_list_issues

  List a project's issues, most recently updated first. Filter by state, labels, assignee, text in the title or description, or changes since a time. iid is the number shown in GitLab (#12).

• Read an issueTier 0 · ReadReads outside contentgitlab_get_issue

  Read one issue: description (Markdown), state, labels, assignees, milestone, due date, confidentiality and comment count. Use list_notes for the discussion.

• Open an issueTier 3 · ExternalReads outside contentgitlab_create_issue

  Open an issue in a project. Labels that do not exist yet are created. Lines may not start with "/" because GitLab runs them as quick actions (such as /close or /assign); put paths in backticks. Visible to everyone who can see the project.

• Triage an issueTier 2 · ReversibleReads outside contentgitlab_update_issue

  Close or reopen an issue, add or remove labels, change assignees, milestone, due date or weight. Send only what changes. Participants are notified.

• Read commentsTier 0 · ReadReads outside contentgitlab_list_notes

  Read the comments (notes) on an issue or merge request, oldest first. Notes GitLab writes itself (such as "changed the label") have system true; internal notes have internal true; comments on diff lines have type DiffNote and a position.

• Add an internal noteTier 2 · Reversiblegitlab_add_internal_note

  Add an internal note to an issue or merge request. Only project members with at least the Reporter role can see it, so it suits hand-offs and triage notes; replies to it stay internal. Lines may not start with "/" (GitLab would run them as quick actions).

• Comment on an issue or merge requestTier 3 · Externalgitlab_add_comment

  Add a comment that everyone who can see the issue or merge request can read; participants are notified. Use add_internal_note for team-only notes. Lines may not start with "/" (GitLab would run them as quick actions such as /merge).

• List merge requestsTier 0 · ReadReads outside contentgitlab_list_merge_requests

  List a project's merge requests, most recently updated first. Filter by state, reviewer, author, labels, draft status, text or changes since a time.

• Read a merge requestTier 0 · ReadReads outside contentgitlab_get_merge_request

  Read one merge request: description, state, draft, branches, reviewers, whether it can be merged (detailed_merge_status), conflicts, unresolved threads, latest pipeline status and number of changes. Use get_merge_request_diffs for the code.

• Read a merge request's changesTier 0 · ReadReads outside contentgitlab_get_merge_request_diffs

  List the files a merge request changes with their diffs (unified format). Very large or generated files may be collapsed or marked too_large without a diff.

• Read a fileTier 0 · ReadReads outside contentgitlab_read_file

  Read a text file from a project's repository at a branch, tag or commit (the default branch when ref is left out), or list a directory. Long files are cut short; binary files return only their size.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If GitLab later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using GitLab, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.