程式碼託管整合¶

Weblate integrates with code hosting sites in several separate places: repository access, incoming notifications, and pushing translations back. The exact setup depends on whether you use Hosted Weblate or run your own Weblate instance, and on whether Weblate should push directly or create pull requests.

Use this page as a provider-oriented checklist. The individual setting pages remain the canonical reference for setting syntax.

設定概覽¶

Grant Weblate access to the repository.
- For Hosted Weblate, add the hosted weblate user where it is available, see 從 Hosted Weblate 存取儲存庫.
- For self-hosted Weblate, create a dedicated code hosting user and grant access using Weblate's SSH key or an HTTPS token, see 在程式碼託管網站上存取儲存庫（GitHub、GitLab、Bitbucket、Azure DevOps 等）.
配置原始碼儲存庫所以 Weblate 可以複製儲存庫。
Configure incoming notifications so Weblate pulls changes soon after a push. The repository webhook or app must point to the matching Weblate hook URL, and the project must have 啟用掛勾 enabled.
Decide how Weblate should push translations back:
- 使用 Git 或 Mercurial 與儲存庫推送 URL 以直接推送。
- Use a provider-specific VCS backend, such as GitHub or GitLab, to create pull or merge requests. These backends need API credentials in the Weblate settings.
Optionally set 推送分支 when Weblate should push to a branch in the upstream repository instead of using a fork where supported.

從 Weblate 推送變更¶

Each translation component can have a push URL set up (see 儲存庫推送 URL), and in that case Weblate will be able to push changes to the remote repository. Weblate can also be configured to automatically push changes on every commit; this is enabled by default, see 提交時一併推送.

If you do not want changes to be pushed automatically, you can push manually under Repository maintenance or using the API via wlc push.

如果您不想由 Weblate 直接推送，我們支援 GitHub 拉取請求、 GitLab 合併請求、 Gitea 拉取請求、 Pagure 合併請求、 Azure DevOps 拉取請求或 Gerrit 檢閱請求檢閱。您可以透過在組件配置中選擇 GitHub 、 GitLab 、 Gitea 、 Gerrit 、 Azure DevOps 或 Pagure 作為版本控制系統來啟動它們。

Overall, following options are available with Git, Mercurial, GitHub, GitLab, Gitea, Pagure, Azure DevOps, Gerrit, Bitbucket Data Center and Bitbucket Cloud:

Desired setup	版本控制系統	儲存庫推送 URL	推送分支
不推送	Git	空白	空白
直接推送	Git	SSH URL	空白
推送至單獨的分支	Git	SSH URL	分支名稱
不推送	Mercurial	空白	空白
直接推送	Mercurial	SSH URL	空白
來自 fork 的 GitHub 拉取請求	GitHub 拉取請求	空白	空白
來自分支的 GitHub 拉取請求	GitHub 拉取請求	SSH URL [1]	分支名稱
來自 fork 的 GitLab 合併請求	GitLab 合併請求	空白	空白
來自分支的 GitLab 合併請求	GitLab 合併請求	SSH URL [1]	分支名稱
來自 fork 的 Gitea 合併請求	Gitea 拉取請求	空白	空白
來自分支的 Gitea 合併請求	Gitea 拉取請求	SSH URL [1]	分支名稱
來自分叉的Pargue合併請求	Pagure 合併請求	空白	空白
來自分支的 Pagure合併請求	Pagure 合併請求	SSH URL [1]	分支名稱
來自 fork 的 Azure DevOps 拉取請求	Azure DevOps 拉取請求	空白	空白
來自分支的 Azure DevOps 拉取請求	Azure DevOps 拉取請求	SSH URL [1]	分支名稱
Gerrit 檢閱	Gerrit 檢閱請求	SSH URL	目標分支名稱（可選）
Bitbucket Data Center pull request from fork	Bitbucket Data Center pull requests	空白	空白
Bitbucket Data Center pull request from branch	Bitbucket Data Center pull requests	SSH URL [1]	分支名稱
Bitbucket Cloud pull request from fork	Bitbucket Cloud 拉取請求	空白	空白
Bitbucket Cloud pull request from branch	Bitbucket Cloud 拉取請求	SSH URL [1]	分支名稱

GitHub¶

GitHub 儲存庫存取¶

HTTPS with personal access token¶

For a single private repository, HTTPS access with an access token is usually the simplest setup when the provider supports Git over HTTPS. Use the provider-required username and token in 原始碼儲存庫.

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

To use this approach:

Create a personal access token as described in Creating an access token for command-line use.
在您的儲存庫 URL 中包含權杖： https://username:token@github.com/owner/repo.git。

This is suitable when you are starting with Weblate or working with a single repository.

SSH with a dedicated user¶

For setups with multiple repositories, use SSH access with a dedicated code hosting user for Weblate. Add Weblate's public SSH key to that user, grant the user access to the repositories, and use SSH URLs in 原始碼儲存庫, for example git@example.com:group/project.git.

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

This also avoids provider restrictions on SSH key reuse. Some code hosting sites allow a public SSH key to be added only once, or only to a single user or deploy key entry. Keeping Weblate's SSH key on a dedicated user lets that user be granted access to multiple repositories without reusing the key in several places.

This keeps personal, project, or API access tokens out of repository URLs. Provider API credentials are still needed when using a provider-specific VCS backend to create pull or merge requests; those credentials are configured separately from the Git repository URL.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

For GitHub, create a dedicated user, for example weblate-bot, and use GitHub SSH URLs for your repositories, for example git@github.com:owner/repo.git.

This approach is also used for Hosted Weblate, which has a dedicated weblate user for that purpose.

備註

When using GitHub for pull requests, the 推送分支 configuration affects the behavior: if not set, the project is forked and changes are pushed through a fork. If set, changes are pushed to the upstream repository and the chosen branch.

GitHub 通知¶

Weblate 原生支援 GitHub。

If you are using Hosted Weblate, the recommended approach is to install the Weblate app. The app delivers GitHub notifications to Hosted Weblate, so you do not need to configure a separate Webhook in GitHub. However, it does not by itself grant Hosted Weblate write access to the repository. To push changes back, you still need to add the Hosted Weblate weblate GitHub user as a collaborator with write access, see 從 Hosted Weblate 存取儲存庫.

If you are not using the app, add the Weblate webhook in the repository settings (Webhooks) to receive notifications on every push to a GitHub repository, as shown on the image below:

The Payload URL consists of your Weblate URL appended by /hooks/github/, for example for the Hosted Weblate service, this is https://hosted.weblate.org/hooks/github/.

You can leave other values at default settings. Weblate can handle both content types and consumes just the push event.

也參考

GitHub 拉取請求¶

This adds a thin layer atop Git using the GitHub API to allow pushing translation changes as pull requests, instead of pushing directly to the repository.

Git pushes changes directly to a repository, while the GitHub backend creates pull requests. The latter is not needed for merely accessing Git repositories.

To create pull requests, select GitHub as 版本控制系統 and configure GITHUB_CREDENTIALS. For GitHub.com, use api.github.com as the API host. The token must allow Weblate to read and write repository contents and create pull requests. If Weblate should fork private repositories, the token might also need administration access.

GitLab¶

GitLab 儲存庫存取¶

HTTPS with personal or project access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

For GitLab, the token needs write_repository scope to be able to push changes to the repository. The project access token requires Developer role for pushing.

The URL needs to contain a username. For a personal access token, it is the actual username: https://user:personal_access_token@gitlab.com/example/example.git. For project access tokens it can be a non-blank value: https://example:project_access_token@gitlab.com/example/example.git.

備註

The rules for using project access tokens have changed between GitLab releases, the non-blank value is the current requirement, but older versions had different expectations (project name, bot user name). Check GitLab documentation matching your version if unsure.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

For GitLab, create a dedicated user and use GitLab SSH URLs, for example git@gitlab.com:group/project.git.

GitLab 通知¶

Weblate has support for GitLab hooks. Add a project webhook with destination to /hooks/gitlab/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/gitlab/.

疑難排解

Check GitLab webhook request history if webhooks are delivered.
The response payload contains information about matched components.

也參考

GitLab 合併請求¶

This adds a thin layer atop Git using the GitLab API to allow pushing translation changes as merge requests instead of pushing directly to the repository.

There is no need to use this to access Git repositories, ordinary Git works the same, the only difference is how pushing to a repository is handled. With Git changes are pushed directly to the repository, while the GitLab backend creates a merge request.

要建立合併請求，請選擇 GitLab 作為版本控制系統並配置 GITLAB_CREDENTIALS。

The 推送分支 configuration affects where Weblate pushes changes before opening the merge request. If it is not set, the project is forked and changes are pushed through a fork. If it is set, changes are pushed to the upstream repository and chosen branch.

Gitea、Forgejo 與 Codeberg¶

Gitea、Forgejo 與 Codeberg 儲存庫存取¶

HTTPS with an access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

For Hosted Weblate repositories on Codeberg, add the hosted weblate user where write access is needed, see 從 Hosted Weblate 存取儲存庫.

Gitea 通知¶

Weblate has support for Gitea webhooks. Add a Gitea Webhook for Push events event with destination to /hooks/gitea/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/gitea/. This can be done in Webhooks under repository Settings.

也參考

Forgejo 通知¶

Weblate has support for Forgejo webhooks. Add a Forgejo Webhook for Push events event with destination to /hooks/forgejo/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/forgejo/. This can be done in Webhooks under repository Settings.

也參考

Gitea 拉取請求¶

在 4.12 版被加入.

This adds a thin layer atop Git using the Gitea API to allow pushing translation changes as pull requests instead of pushing directly to the repository.

要建立拉取請求，請選擇 Gitea 作為版本控制系統並配置 GITEA_CREDENTIALS。

Bitbucket¶

Bitbucket repository access¶

HTTPS with an access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

Hosted Weblate has a dedicated weblate user for Bitbucket access, see 從 Hosted Weblate 存取儲存庫.

To push directly, use Git or Mercurial with 儲存庫推送 URL.

Bitbucket 通知¶

Weblate has support for Bitbucket webhooks. Add a webhook which triggers upon repository push, with destination to /hooks/bitbucket/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/bitbucket/.

也參考

Bitbucket Data Center pull requests¶

在 4.16 版被加入.

This adds a thin layer atop Git using the Bitbucket Data Center API to allow pushing translation changes as pull requests instead of pushing directly to the repository.

警告

This does not support Bitbucket Cloud API.

To create pull requests, select Bitbucket Data Center as 版本控制系統 and configure BITBUCKETSERVER_CREDENTIALS.

Bitbucket Cloud 拉取請求¶

在 5.8 版被加入.

This adds a thin layer atop Git using the Bitbucket Cloud API to allow pushing translation changes as pull requests instead of pushing directly to the repository.

警告

This is different from Bitbucket Data Center API.

To create pull requests, select Bitbucket Cloud as 版本控制系統 and configure BITBUCKETCLOUD_CREDENTIALS.

Azure DevOps¶

Azure Repos 儲存庫存取¶

HTTPS with an access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

Use the HTTPS clone URL shown by Azure Repos for the repository.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

Use the SSH URL shown by Azure Repos for the repository.

Azure Repos 通知¶

Weblate has support for Azure Repos webhooks. Add a webhook for Code pushed event with destination to /hooks/azure/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/azure/. This can be done in Service hooks under Project settings.

也參考

Azure DevOps 拉取請求¶

This adds a thin layer atop Git using the Azure DevOps API to allow pushing translation changes as pull requests, instead of pushing directly to the repository.

Git pushes changes directly to a repository, while the Azure DevOps backend creates pull requests. The latter is not needed for merely accessing Git repositories.

要建立拉取請求，請選擇 Azure DevOps 作為版本控制系統並配置 AZURE_DEVOPS_CREDENTIALS。

Pagure¶

Pagure 儲存庫存取¶

HTTPS with an access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

Pagure 通知¶

Weblate has support for Pagure hooks. Add a webhook with destination to /hooks/pagure/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/pagure/. This can be done in Activate Web-hooks under Project options:

也參考

Pagure 合併請求¶

在 4.3.2 版被加入.

This adds a thin layer atop Git using the Pagure API to allow pushing translation changes as merge requests instead of pushing directly to the repository.

要建立合併請求，請選擇 Pagure 作為版本控制系統並配置 PAGURE_CREDENTIALS。

其他工作流程¶

Gitee 儲存庫存取¶

HTTPS with an access token¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

The token needs read access for cloning and write access for pushing. Provider-specific VCS backends that create pull or merge requests might require separate API credentials.

SSH with a dedicated user¶

Configure 儲存庫推送 URL only when Weblate should push changes directly or when the chosen workflow requires a push URL, see 從 Weblate 推送變更.

On Hosted Weblate, use the hosted weblate user on supported code hosting sites, see 從 Hosted Weblate 存取儲存庫.

Gitee 通知¶

Weblate has support for Gitee webhooks. Add a WebHook for Push event with destination to /hooks/gitee/ URL on your Weblate installation, for example https://hosted.weblate.org/hooks/gitee/. This can be done in WebHooks under repository Management.

也參考

Gerrit 檢閱請求¶

Gerrit support adds a thin layer atop Git using the git-review tool to allow pushing translation changes as Gerrit review requests, instead of pushing them directly to the repository.

The optional 推送分支 setting selects the target branch for the Gerrit review. Leave it empty to use 儲存庫分支. Use the short branch name, such as main; Weblate and git-review push the review to refs/for/<branch> automatically. Do not include Gerrit push options such as %submit or %l=Code-Review+2 in the branch name.

The Gerrit documentation has the details on the configuration necessary to set up such repositories. There is no separate code hosting credential setting for this backend.

Docker 憑證¶

對於 Docker 安裝，程式碼託管 API 憑證也可以透過環境變數提供，請參閱 Code hosting sites credentials。