Gitea Integration
Follow the instructions on this page to integrate your project with VCS repositories that are hosted on a self-hosted Gitea server.
A Gitea integration enables the following features in YouTrack:
Apply commands to YouTrack issues in commit messages. For more information, see Apply Commands in VCS Commits.
Track commits that are related to specific issues in the activity stream for each issue. For more information, see Commits.
Display the status of pull (merge) requests directly in the activity stream of any issue that is referenced in the title or description of the pull request. For details, see Pull Requests.
Add links to YouTrack issues in commit messages or branch names. For more information, see Link Issues in VCS Commits.
Prerequisites
YouTrack is accessible to inbound connections. Specifically, you need to make sure that your network doesn't block connections between your VCS server and YouTrack.
The account that you use to connect to Gitea has access to the Gitea repository that you want to use with this integration. This is the user account whose private token is used for authentication. You can either use an account that has at least Master or Owner access level in the project or a Gitea administrator account.
If you're integrating with a Gitea installation and want to establish a secure (HTTPS) connection with the server, you may need to import the SSL certificate for your Gitea server into YouTrack.
If your Gitea server has a valid certificate that is signed by a well-known certificate authority (CA), the JVM vendor may have already added the root (CA) certificate to the certificate store. You should be able to connect to the server without importing its SSL certificate.
If the certificate for your server is self-signed, you need to import the certificate and public key to establish a secure connection. For security, use this option only when both YouTrack and your Gitea server run on a private computer network. This operation is only available to users with Low-level Admin Read and Low-level Admin Write permissions. For details, see SSL Certificates.
Gitea only supports webhooks that send requests to a predefined list of allowed hosts. To call a webhook from YouTrack through a local network, you must update the value for the ALLOWED_HOST_LIST
in the Gitea configuration file to include the IP address that identifies your YouTrack service.
Generate an Access Token in Gitea
The first thing you should do is generate an access token in Gitea. This token grants YouTrack access to the repository based on the access that is granted to your Gitea account.
To generate token in Gitea:
Access the repository that you want to integrate with in Gitea.
Log into Gitea, and click your avatar to open the user menu, then select Settings item.
When the settings section opens, select the Applications tab.
In the Generate New Token section, type a name for the token and click Generate Token button.
When the new token is generated, copy it - you will need it to configure the integration in YouTrack.
Configure the Gitea Integration
Next, you need to establish a connection with a Gitea repository. You can use a single access token to set up multiple integrations.
To connect to a Gitea repository:
In the administration menu, select VCS Integrations.
Click the New VCS Integration button.
The New VCS Integration dialog opens.
From the Main YouTrack project list, select the name of the primary project that you want to integrate with the VCS repository. You can add integrations with additional YouTrack projects after you have set up the connection to the repository.
For the Server type, select Gitea.
Paste the URL that points to your Gitea repository into the Repository URL input field.
Paste the access token that you have generated into the Personal access token field.
Click the Save button.
Your YouTrack project is integrated with the selected repository in Gitea.
Commits from the Gitea repository that reference an issue in the project are displayed in the activity stream of the referenced issue.
The sidebar displays additional settings for configuring the VCS integration.
To learn more about these settings, see Integration Settings.
Advanced Server Settings
If you are unable to establish a connection to your repository using the basic settings on the New VCS Integration dialog, click the Show advanced server settings link.
You only need to enter values for these settings when you haven't set up a VCS integration with the target server. If you already have a working integration with a single repository on the server, you can add integrations with other repositories without setting these parameters again.
Use the following guidelines to set the values for these settings:
Setting | Description |
---|---|
URL | This setting helps to identify the path to the Gitea repository. If the repositories for your Gitea server are available under To resolve this problem, enter the base URL for your Gitea server. For example: |
SSL keys | If your server environment is set up to require client SSL authentication, select the keystore that contains the private key for your YouTrack server. This key identifies your YouTrack server when it tries to establish a connection with Gitea. This setting is only used to support HTTPS authentication as required by connections to your internal network. The list only displays SSL keys that are already imported into YouTrack. To learn how to generate keystore files and upload them to YouTrack, see SSL Keys. |
Integration Settings
By default, the VCS integration processes changes that are committed to the repository by any user in any branch. Any user who has access to the issue in YouTrack can view these changes in the issue activity stream.
If you only want to process changes by specific users in designated branches or restrict the visibility of VCS changes in YouTrack, you can customize the integration settings. Use following settings to customize the integration:
Setting | Description |
---|---|
Repository | Displays the path to the repository in the integrated version control system. If needed, you can edit the location of the repository after you have set up the integration. For instructions, see Edit Repository Settings. |
Main YouTrack project | Sets the primary project in which the VCS integration is active. |
Additional projects | Integrates the linked repository with one or more additional projects. |
Committers | Restricts the ability to update issues with commands in commit messages to members of the specified group. VCS changes from users who are not members of the selected group are still attached to related issues, but any commands that are specified in their commits are ignored. |
Processing scheme for VCS changes | Choose how to process VCS changes when the commit message references an issue ID. The following options are supported:
|
Monitored branches | Stores the names of the branches that you want to monitor for changes.
If the address that you entered as the Repository URL when you connected to the repository points to a specific branch, this branch is automatically added to the list of monitored branches when you set up the connection. |
Parse commits for issue comments | When enabled, specific segments of commit message text are copied to issues as comments. When you copy parts of the commit message to the issue as comments, you can trigger @mention notifications and expose information to users who don't have access to VCS changes. This setting does not affect how commit messages are shown in VCS changes. The entire commit message, including commands and issue comments, is always shown as part of the VCS change record in the activity stream. You should only enable this option when:
To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits. |
Check branch names for issue references | When enabled, the integration checks for references to issues in branch names for commits and pull requests. This option was added for teams that use a branch-per-ticket process, so their developers don't have to mention issue IDs in their commit messages explicitly. |
VCS changes visibility | Restricts the visibility of VCS changes to one or more groups of users in YouTrack. When unrestricted, the list of VCS changes is visible to any user who has permission to read the issue. |
Available Actions
When you select an integrated version control system in the list, the following actions are available in the toolbar:
Action | Description |
---|---|
Disable | Shuts off the connection between the integrated project and the VCS repository. The configuration is not changed and can be enabled at any time. |
Edit | Opens the integration settings dialog in the sidebar for the selected project and repository. |
Delete | Removes the settings for the integrated project from YouTrack. This action also removes all VCS changes that were added to issues for commits in the linked repository. While the action itself cannot be undone, you can use the Import action to restore VCS changes that were removed accidentally. |