GitLab
GitLab is a developer platform that allows developers to create, store, and manage their code. This app focuses on connecting repository events and file actions into the Blackbird ecosystem.
Before setting up
Section titled “Before setting up”Before you can connect you need to make sure that:
- You have a GitLab account.
- You have the access level required by the feature: Reporter for cross-repository polling, or Maintainer/Owner for project webhook events.
Permissions
Section titled “Permissions”Connection user needs at least the Reporter role in every selected repository. For a personal access token, grant read_api to read repository events, projects, comparisons, and commit diffs. Existing tokens with the broader api scope also work.
Connecting
Section titled “Connecting”GitLab supports the following connection types in Blackbird:
- OAuth: use this option for GitLab-hosted accounts.
- OAuth Self-managed: use this option for self-managed GitLab instances hosted on a custom domain.
- Personal Access Token (GitLab.com): use this option with a token issued by GitLab.com.
- Personal Access Token (Self-managed): use this option with a token issued by your self-managed GitLab instance.
- Navigate to apps and search for GitLab. If you cannot find GitLab then click Add App in the top right corner, select GitLab and add the app to your Blackbird environment.
- Click Add Connection.
- Name your connection for future reference e.g. ‘My GitLab connection’.
- Choose the connection type that matches your GitLab environment.
- Complete the authentication flow for the selected connection type.
- When you return to Blackbird, confirm that the connection has appeared and the status is Connected.

Connecting with OAuth
Section titled “Connecting with OAuth”- Create a new GitLab connection in Blackbird.
- Select OAuth as the connection type.
- Click Authorize connection.
- Follow the GitLab authorization flow and approve the requested access.
- Return to Blackbird and confirm that the connection status is Connected.
Connecting to self-managed GitLab
Section titled “Connecting to self-managed GitLab”To connect to your self-managed GitLab instance with OAuth, use the OAuth Self-managed connection type in Blackbird.
- In your self-managed GitLab instance, navigate to Admin area -> Applications and click Add new application.
- Enter an application name, for example Blackbird Self-Managed Test.
- Set Redirect URI to
https://bridge.blackbird.io/api/AuthorizationCode. - Save the application and copy the generated Application ID and Secret.
- In Blackbird, create a new GitLab connection and choose OAuth Self-managed as the connection type.
- Enter your GitLab instance URL as Base URL, for example
https://yourdomain.example.com. - Paste the GitLab Application ID into Client ID and the GitLab Secret into Client secret.
- Click Authorize connection and complete the OAuth consent flow in your self-managed GitLab instance.
- Return to Blackbird and confirm that the connection has appeared and the status is Connected.
Connecting with a personal access token
Section titled “Connecting with a personal access token”- Create a personal access token for your user or service account with the scopes required for the actions you want to use.
- In Blackbird, create a new GitLab connection and choose Personal Access Token (GitLab.com) or Personal Access Token (Self-managed) based on where you created the token.
- For a self-managed connection, enter the URL of the GitLab instance that issued the token in Base URL, for example
https://gitlab.example.com. - Paste the token into the API key field.
- Save the connection and confirm that the status is Connected.
Actions
Section titled “Actions”Repository
Section titled “Repository”- Create new repository Create repository with selected settings.
Advanced settings:
- User ID: User ID that owns the created repository.
- Default branch: Default branch name for the created repository.
- Namespace ID: Namespace ID for the created repository.
- Description: Repository description.
- Enable issues: Option to enable issues.
- Enable merge requests: Option to enable merge requests.
- Enable jobs: Option to enable jobs.
- Enable wiki: Option to enable wiki.
- Enable snippets: Option to enable snippets.
- Enable container registry: Option to enable the container registry.
- Enable shared runners: Option to enable shared runners.
- Visibility: Repository visibility.
- Import URL: URL to import repository content from.
- Public jobs: Option to make jobs public.
- Only allow merge if pipeline succeeds: Option to allow merges only after a successful pipeline.
- Only allow merge if all discussions are resolved: Option to allow merges only after all discussions are resolved.
- Enable LFS: Option to enable large file storage.
- Enable request access: Option to allow users to request access.
- Tags: Multiple tags to assign to the repository.
- Enable printing merge request link: Option to print merge request links.
- CI config path: CI config file path.
- Initialize with README: Option to create an initial README file.
- Download file Download a file from a repository by file path. Optionally specify Commit ID (SHA) to download the file at a specific commit, overriding the branch selection. When omitted, the selected branch (or the repository’s default branch) is used.
Advanced settings:
- Branch name: Branch to use instead of the default branch.
- Get all files in folder Get files from a repository folder.
Advanced settings:
- Folder path (e.g. “Folder1/Folder2”): Folder path to get files from.
- Include subfolders: Option to include files in nested folders.
- Get repository Get repository details.
- Search repository issues Get open issues in a repository.
- Search repository merge requests Get open merge requests in a repository.
- Search repository folder content Search folder content in a repository.
Advanced settings:
- Content type: Content type to include.
- Search repositories Search repositories available to connection.
- Search files by filepaths Get existing files from a repository by their exact paths. Missing files are skipped; if none exist, the action returns an empty list. The file paths output lists the paths of the files found.
- Check if branch exists Check whether branch exists in a repository.
Commit
Section titled “Commit”- Search commits Search commits in a repository.
Advanced settings:
- Authors to include: Multiple author names or emails to include.
- Authors to exclude: Multiple author names or emails to exclude.
- Commit after: Only commits after this date.
- Commit before: Only commits before this date.
- Commit message contains: Text that commit message must contain.
- File path: Only commits touching this file path.
- Find commit Find first commit that matches search filters in a repository.
- Get commit Get commit details by commit ID.
- List added or modified files in X hours Search files added or modified during specified number of hours.
Advanced settings:
- Path pattern: Use forward slash ’/’ to represent directory separator. Use ’*’ to represent wildcards in file and directory names. Use ’**’ to represent arbitrary directory depth.
- Upload file Create file or update existing file in a repository.
- Upload multiple files Create or update multiple files in a repository in one commit.
- Update file Update existing file in a repository.
- Delete file Delete file from a repository.
Diagnostics
Section titled “Diagnostics”- Diagnose event stream Compare the former global push feed with the repository push feed now used by On files modified across repositories. Inputs are Repository ID, Timestamp (ISO 8601 with
Zor an explicit timezone offset) and Minutes before and after (1–1440, applied on each side). For the November 4 push, use repository156239and timestamp2026-11-04T02:57:34.718-03:30or2026-11-04T06:27:34.718Z; entering 10 minutes inspects 10 minutes before through 10 minutes after that instant. The action queries/eventswithscope=alland/projects/{repositoryId}/eventswithout that scope, using the sameaction=pushed, descending order and padded date bounds. The JSON report contains separateglobal_streamandrepository_streamsections with queries, counts, event payload evidence, pagination and collection status, plus a comparison of selected-repository event IDs absent from the collected global results. Counts distinguish all global events from events for the selected repository. Events are marked inside, outside or unknown relative to the exact inclusive UTC window. Each stream is bounded to 20 pages and 1000 reported events; both share a three-minute deadline including retries, and partial results are preserved. This shows currently visible activity and does not replay historical responses, polling memory, branch/file filters or Flight creation. Collection completeness describes client retrieval, not exhaustive server-side history. - Diagnose files modified event Collect read-only evidence for investigating why a commit did not trigger On files modified across repositories. Run it with the same connection as the event. Required inputs are Repository ID, the full Commit SHA, and Expected branch.
Outputs include a summary, confirmed related push count, collection completeness, and a JSON Diagnostic report for offline analysis. The report contains repository and commit metadata, changed file paths and change flags, current branch head and commit reachability, project/global push-feed visibility, push payload completeness checks, and comparison commits with their changed files for confirmed pushes. It includes request statuses and request IDs; credentials, error response bodies, file contents and diff patches are omitted.
Repository ID and Timestamp outputs can be mapped directly into Diagnose event stream; choose Minutes before and after there. Timestamp is the UTC time of the latest confirmed push containing the commit on the expected branch, not the commit date. It is empty if no confirmed push timestamp on that branch was found. The same values are included under
event_stream_inputsin the JSON report. The action searches the previous seven days and, for older commits, an additional range two days before and after the committed timestamp. Searches are bounded to 20 pages per feed per range, 10 pages per diff/reference lookup, 30 enriched candidate pushes, 50 commits per push, 200 reported repository events, 150 request operations and three minutes including retries. Collected evidence is preserved when an API request fails or a limit is reached; Collection complete then returns false. Each operation can include retries under the shared client policy. Commit time can differ from push time, and GitLab may no longer retain an event. A missing related push only means none was confirmed within the reported ranges and limits. Current branch reachability does not prove historical branch membership. The action does not evaluate event filters, historical polling memory, baseline resets, deduplication or platform Flight creation. Compare the report with the event’s inputs and polling logs. Newly added, deleted and renamed files do not qualify as modified files in this polling event.
Merge request
Section titled “Merge request”- Search merge requests Search merge requests in a repository.
- Get merge request Get merge request details.
- Create merge request Create merge request.
- Complete merge request Complete merge request by merging it.
Advanced settings:
- Merge commit message: Text for the merge commit message.
Branch
Section titled “Branch”- Search branches Search repository branches.
- Get branch Get branch details by name.
- Create branch Create branch from a base branch.
Events
Section titled “Events”Pushes
Section titled “Pushes”- On commit pushed On commit pushed to a repository branch.
- On files added On files added by new commits. Outputs paths to added files.
- On files modified On files modified by new commits. Outputs paths to modified files.
- On files added or modified On files added or modified by new commits. Outputs paths to added or modified files.
- On files removed On files removed by new commits. Outputs paths to removed files.
For the file specific events, a path parameter can be specified in order to narrow down the event to only files in specific folders or files that have certain extensions. Use the forward slash ’/’ to represent directory separator. Use ’*’ to represent wildcards in file and directory names. Use ’**’ to represent arbitrary directory depth.
For example: when you want to create an event that triggers only when .html files are modified in a folder called locales. Then the path pattern should be: /locales/*.html

Polling for modified files across repositories
Section titled “Polling for modified files across repositories”- On files modified across repositories periodically checks push activity in multiple selected repositories. It uses read-only GitLab API requests and does not create project or group webhooks.
Inputs and matching
Section titled “Inputs and matching”Repository IDs to include is required. It is a multi-select field that displays each repository as namespace/repository while storing its stable numeric GitLab project ID.
All other inputs are optional:
- Branches to watch: case-sensitive regular expressions. A branch must match at least one when configured.
- Branches to ignore: case-sensitive regular expressions. Ignore matches take precedence over watch matches.
- File patterns to watch: glob patterns matched only against modified files. A bare filename such as
en.pomatches at any directory depth as**/en.po. Added, deleted, and renamed files do not qualify. Leaving this input empty accepts any modified file. - Commit messages to include: case-sensitive regular expressions. A commit must match at least one when configured.
- Commit messages to exclude: case-sensitive regular expressions. Exclude matches take precedence over include matches.
- Pusher user IDs to watch: GitLab user IDs. A push must come from one of these users when configured.
- Pusher user IDs to ignore: GitLab user IDs. Ignore matches take precedence over watch matches.
Commit-message and file-pattern matches must occur in the same commit. One qualifying commit makes the push qualify, but output includes every commit from that push. Matched file paths come only from qualifying commits.
Output and polling behavior
Section titled “Output and polling behavior”Each flight returns one Pushes batch containing every matching push found during that poll. Each push contains repository ID, repository name with namespace, branch name, push time, pusher user ID, matched file paths, and commits with hash, message, author name, and author email.
First poll establishes a baseline and does not trigger. Changing any input also establishes a new baseline, preventing activity selected under the new configuration from being replayed. Later polls rescan a 24-hour overlap and de-duplicate processed GitLab event IDs. Memory advances only after the complete scan and all enrichment requests succeed, so an API failure or safety-limit failure does not lose events.
Limitation of polling
Section titled “Limitation of polling”GitLab cannot provide a reliable comparison range for every push:
- Bulk pushes above GitLab’s multi-reference threshold, normally three refs, can omit branch and commit-range details. Incomplete events are recorded as processed and skipped.
- New branches, deleted branches, and force pushes with an unrecoverable comparison range are skipped.
- Diffs flagged by GitLab as collapsed or too large are skipped because matched paths may be incomplete.
- GitLab can stop very large commit diffs at the instance file limit; older versions might not flag that truncation, so matching can be less complete for unusually large commits.
- The 24-hour overlap handles ordinary delays and pagination movement, not events that become visible more than 24 hours late.
- Existing polling memory remains compatible. Previously unseen pushes still inside the scan overlap can trigger after upgrading; events already recorded as processed remain deduplicated.
Example
Section titled “Example”The following bird creates a new memoQ project whenever files are updated or added to a specific folder in a GitLab repository.

Feedback
Section titled “Feedback”Do you want to use this app or do you have feedback on our implementation? Reach out to us using the established channels or create an issue.