Git service settings and administration

As a project administrator or Git service administrator, you can configure each Git repository: default branch, access permissions, notifications, webhooks, and advanced options. These settings are accessible via the "Settings" button in the breadcrumb of a repository page.

General settings

The "General settings" tab groups the fundamental parameters of the repository.

Description

A Description field lets you add descriptive text to the repository. This description is displayed in the project repository list and on the repository browsing page. It is particularly useful for clarifying the role or content of the repository (e.g. "Project backend API", "Technical documentation").

Default branch

In a repository with multiple branches, you can choose the default branch. The selected branch:

• Is displayed when users open the repository through the web interface.

• Is used when cloning the repository.

• Cannot be deleted.

• Is the branch used for automatic Artifact closure via commit messages.

Allow artifact closure

The "Allow artifact closure" checkbox enables the ability to automatically close an Artifact from your Trackers by referencing it in a Git commit message with a closing keyword (see the Automatic Artifact Closure section for full details).

Access control

The "Access control" tab lets you manage who can read, write, and administer the repository.

Basic permissions

By default, a repository is readable by all active platform users, but only project members can modify it. You can adjust permissions by user groups for three levels:

• Read: read access to the repository (clone, fetch).

• Write: push content to the repository (commits, new branches, etc.).

• Rewind: deletion of references (branches, tags) and full history rewriting.

Fine-grained permissions

For more precise control, you can manage permissions branch by branch and tag by tag.

1. Enable fine-grained permissions in the repository settings, then save.

2. Define patterns for branches and tags (for example refs/heads/main, refs/tags/v*).

3. Assign permissions by user groups for each pattern.

CI Builds (Commit Status)

The "CI Builds" tab allows you to configure build statuses associated with commits.

Tuleap allows you to associate a CI build status with a Git commit. This status is displayed as a badge on commits in the web interface and on Pull Requests.

A CI system (Jenkins, GitLab CI, etc.) can send a build result to Tuleap via the REST API:

POST /api/git/{id}/statuses/{commit_reference}

The state parameter accepts the values: success, failure, or pending.

By default, any user with write permission can send a build status. From this tab, you can restrict this capability to specific user groups, to limit triggering to authorized CI systems only.

Information

The Tuleap API for Jenkins plugin automatically handles sending the build status. If you use another CI system, you must implement the REST call manually.

Email notifications

The "Notifications" tab allows you to configure the repository to send an email on every push. This notification keeps the entire team informed of changes made to the code.

You can customize:

• The subject prefix: a text added at the beginning of the subject of each notification email (e.g. [MyProject]).

• The recipient list: Tuleap users, user groups, or free email addresses (such as a mailing list).

The email content includes:

• The list of commits pushed to the repository.

• The modified files (with diffstats).

• For each commit, a link to the diff in the Tuleap web interface.

• For each reference detected in the commit description, the corresponding automatic link to the Artifact.

Information

Cross-reference extraction from commit messages only works if email notification is configured.

Webhooks

The "Webhooks" tab allows you to configure your repository so that an HTTP endpoint is called on every push.

Custom webhooks

Custom webhooks send an HTTP POST call to the URL of your choice on every push. The payload contains information about the push (updated references, author, commits).

Information

For more details on the payload format, refer to the Git Webhook section of the technical documentation.

Jenkins webhooks

A Jenkins webhook notifies your Jenkins instance on every push. To configure it:

1. Navigate to the repository settings, Webhooks section.

2. Add a Jenkins webhook by providing the URL of your Jenkins instance and the notifyCommit access token (generated from the Jenkins Global Security page).

You can create one Jenkins webhook per repository. At the project Git service administration level, you can also add Jenkins webhooks that will be triggered for all repositories in the project.

The log of triggered jobs is visible in the History section of the webhook.

Usage note

The hudson_git plugin must be installed on your Tuleap instance to create Jenkins webhooks.

Jenkins webhooks for Tuleap Branch Source

This feature enables full and automated integration with Jenkins via the Tuleap Git Branch Source Jenkins plugin. Jenkins automatically discovers the repositories, branches, and Pull Requests of your project.

Information

The detailed configuration is described in the Tuleap Git / Jenkins integration documentation.

Delete tab

The "Delete" tab allows you to delete the Git repository from the project.

Procedure

1. Navigate to the Delete tab in the repository settings.

2. Click the (red) "Delete this repository" button.

Warning

Deletion is irreversible from the project interface. All associated data (branches, tags, history, Pull Requests) will be lost.

If the repository is connected to a Gerrit server, it must first be disconnected before it can be deleted. The following message is displayed: "The repository cannot be deleted before being disconnected from Gerrit".

A platform administrator can view "Deleted Git repositories" in the site administration and restore a deleted repository, provided that a repository with the same name does not already exist in the project.

Additional features

Git LFS (Large File Storage)

Git does not handle large binary files (videos, images, audio files) efficiently. Git LFS solves this problem by storing these files separately.

Usage note

The gitlfs plugin must be installed and enabled to use Git LFS.

Information

For more details, refer to the official Git LFS website and the Git LFS wiki.

File size restrictions

Files larger than 50 MB are automatically rejected by Tuleap. These large files must be managed via Git LFS.

Information

A platform administrator can grant an exception for your project. Refer to the Increase max file size section of the technical documentation.

Automatic Artifact closure

You can close an Artifact from your Trackers by referencing it in a Git commit message with a closing keyword.

To use this feature, enable the "Allow artifact closing" option in the General settings of your repository.

For the closure to work, all of the following conditions must be met:

1. The "Allow artifact closing" option is enabled on the repository.

2. The commit is pushed to the default branch of the repository.

3. The reference has the form <closing keyword> <reference keyword> #<id> (for example: Implements story #123 or Fixes bug #456).

4. The referenced Artifact belongs to the same project as the Git repository.

5. The Artifact status is not already closed.

6. The "Done" semantic of the Tracker is defined (otherwise the "Status" semantic must have at least one "closed" value).

7. The Tracker workflow allows the transition.

8. Field dependencies do not prevent the closure.

Closing keywords

The following keywords (case-insensitive) can be used:

• Closes / Close / Closed / Closing / chore:

• Fixes / Fix / Fixed / Fixing / fix:

• Implements / Implement / Implemented / Implementing / feat:

• Resolves / Resolve / Resolved / Resolving

Examples:

Closes art #123
fix: art #456
Implements story #789, Fixes bug #101

When all conditions are met, the Artifact status is changed to the first valid value of the "Done" semantic. The closure is performed by a Tuleap bot named "Tracker Workflow Manager" with a follow-up comment explaining the reason for the closure.

Tip

You can close multiple Artifacts at once in a single commit message.

Create a branch from an Artifact

Since Tuleap 13.11, you can create a Git branch and its associated Pull Request directly from an Artifact in your Trackers.

Usage note

The Git, Tracker, and Pull Request plugins must be installed. Git repositories must exist in the same project as the Artifact.

Procedure

1. Open an Artifact in a Tracker.

2. In the Artifact actions, select "Create branch on a Git repository".

3. In the modal:

   • Select a repository from the project repositories (not personal forks).

   • Choose the base reference (the default branch is automatically suggested, or enter another branch / a SHA-1).

   • A preview of the branch name is displayed. The format is fixed: tuleap-{artifact_id}-{artifact-title}.

   • The "Create a pull request based on this new branch to the default branch" checkbox is checked by default.

4. Click "Create branch".

Pre-receive Hook (Technology Preview)

Tuleap offers the ability to execute custom scripts during the Git pre-receive hook. These scripts can validate or reject a push according to business rules.

Scripts must be WASM modules (WebAssembly) compiled with WASI Preview 1 support.

Warning

This feature is in Technology Preview and may change in future versions.

Information

For technical details (input/output format, limitations, installation), refer to the Pre-receive hook section of the technical documentation.

Build status (Commit Status)

Tuleap allows you to associate a CI build status with a Git commit. This status is displayed as a badge on commits in the web interface and on Pull Requests.

How it works

A CI system (Jenkins, GitLab CI, etc.) can send a build result to Tuleap via the REST API:

POST /api/git/{id}/statuses/{commit_reference}

The state parameter accepts the values: success, failure, or pending.

Permissions

By default, any user with write permission can send a build status. You can restrict this capability to specific Access Keys via the repository administration, to limit triggering to authorized CI systems only.

Info

The Tuleap API for Jenkins Jenkins plugin automatically handles sending the build status. If you use another CI system, you must implement the REST call manually.

Git administration at project level

In addition to per-repository settings, the Git service provides a centralized administration at the project level. This page is accessible from the "Administration" link in the "Git repositories" breadcrumb dropdown menu.

The administration page is organized into five tabs:

• Gerrit Templates: creation and management of reusable Gerrit permission configuration templates (requires a configured Gerrit server).

• Git administrators: management of user groups with the Git service administrator role.

• Git settings template: default access permissions applied to new repositories.

• GitLab Group link: configuration of the GitLab integration at the project level (see the GitLab Integration chapter).

• Jenkins: Jenkins webhooks applied to all repositories in the project.

Git administrators

By default, project administrators are also Git service administrators. From the "Git administrators" tab, you can add other user groups as Git administrators.

A Git administrator can:

• Create, modify, and delete repositories.

• Manage permissions for all repositories.

• Configure webhooks and integrations.

• Access the Git administration page.

Git repositories template

The "Git repositories template" tab allows you to define default access permissions that will be automatically applied to each new repository created in the project.

1. Navigate to the "Git repositories template" tab in the Git administration.

2. Configure the Read, Write, and Rewind permissions by user groups.

3. If fine-grained permissions are enabled, you can also define default rules for branches and tags.

Info

These default settings apply only to new repositories. Existing repositories are not modified.

Jenkins

The "Jenkins" tab allows you to add Jenkins webhooks that will be triggered for all repositories in the project, avoiding the need to configure a webhook on each repository individually.