Skip to content

Commit

Permalink
Docs: Clarify methods for configuring repository URLs
Browse files Browse the repository at this point in the history 
- Move all docs into single place
- Place Hosted Weblate docs into separate section
- Better link this from settings and continuous localization

Fixes #3533
  • Loading branch information
@nijel
nijel committed Mar 27, 2020
1 parent 1f94ddf commit 58a8ee6
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 78 deletions.
45 changes: 13 additions & 32 deletions docs/admin/continuous.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,49 +255,30 @@ nightly merges as well, by enabling :setting:`AUTO_UPDATE`.
Pushing changes
---------------

Each translation component can have a push URL set up (see :ref:`component`),
and in that case Weblate will be able to push change to the remote repository.
Weblate can be also be configured to automatically push changes on every commit
(this is default, see :ref:`component`). If you do not want changes to be
pushed automatically, you can do that manually under :guilabel:`Repository
maintenance` or using API via :option:`wlc push`.

If you are using SSH to push, you will need to have a key without a passphrase
(or use ssh-agent for Django), and the remote server needs to be verified by you
via the admin interface first, otherwise pushing will fail.
Each translation component can have a push URL set up (see
:ref:`component-push`), and in that case Weblate will be able to push change to
the remote repository. Weblate can be also be configured to automatically push
changes on every commit (this is default, see :ref:`component-push_on_commit`).
If you do not want changes to be pushed automatically, you can do that manually
under :guilabel:`Repository maintenance` or using API via :option:`wlc push`.

The push options differ based on the :ref:`vcs` used, more details are found in that chapter.

In case you do not want direct pushes by Weblate, there is support for
:ref:`vcs-github`, :ref:`vcs-gitlab` pull requests or :ref:`vcs-gerrit`
reviews, you can activate these by choosing :guilabel:`GitHub`,
:guilabel:`GitLab` or :guilabel:`Gerrit` as :ref:`component-vcs` in :ref:`component`.

.. note::

You can also enable automatic pushing of changes on commits, this can be done in
:ref:`component`.
You can also enable automatic pushing of changes after Weblate commits, this can be done in
:ref:`component-push_on_commit`.

.. seealso::

See :ref:`vcs-repos` for setting up SSH keys, and :ref:`lazy-commit` for
info about when Weblate decides to commit changes.

.. _hosted-push:

Pushing changes from Hosted Weblate
+++++++++++++++++++++++++++++++++++

For Hosted Weblate there is a dedicated push user registered on GitHub, Bitbucket
and GitLab (with username :guilabel:`weblate` named
:guilabel:`Weblate push user`). You need to add this user as a collaborator and
give it permission to push to your repository.

The user is added to the repository (in some cases this happens immediately, on
GitHub it typically happens after accepting invitations what happens
automatically every hour), you can configure your component push URL to a ssh
URL of your repository (see :ref:`component`) and enjoy Weblate automatically
pushing changes to your repository.

In case you do not want direct pushes by Weblate, there is support for GitHub,
GitLab pull requests or Gerrit reviews, you can activate these by choosing
`GitHub`, `GitLab` or `Gerrit` as VCS in :ref:`component`.

Protected branches
++++++++++++++++++

Expand Down
22 changes: 16 additions & 6 deletions docs/admin/projects.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -251,20 +251,30 @@ VCS to use, see :ref:`vcs` for details.
Source code repository
++++++++++++++++++++++

VCS repository used to pull changes, see :ref:`vcs-repos` for more details.
VCS repository used to pull changes.

This can either be a real VCS URL or ``weblate://project/component``
indicating that the repository should be shared with another component.
See :ref:`internal-urls` for more details.
.. seealso::

See :ref:`vcs-repos` for more details on specifying URLs.

.. hint::

This can either be a real VCS URL or ``weblate://project/component``
indicating that the repository should be shared with another component.
See :ref:`internal-urls` for more details.

.. _component-push:

Repository push URL
+++++++++++++++++++

Repository URL used for pushing. This is completely optional and push
support is turned off when this is empty. See :ref:`vcs-repos` for more
details on how to specify a repository URL.
support is turned off when this is empty.

.. seealso::

See :ref:`vcs-repos` for more details on how to specify a repository URL and
:ref:`push-changes` for more details on pushing changes from Weblate.

.. _component-repoweb:

Expand Down
98 changes: 58 additions & 40 deletions docs/vcs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,28 @@ Accessing repositories
----------------------

The VCS repository you want to use has to be accessible to Weblate. With a
publicly available repository you just need to enter the correct URL (for example
``git@github.com:WeblateOrg/weblate.git`` or
``https://github.com/WeblateOrg/weblate.git``), but for private repositories the
setup might be more complex.
publicly available repository you just need to enter the correct URL (for
example ``https://github.com/WeblateOrg/weblate.git``), but for private
repositories or for push URLs the setup is more complex and requires
authentication.

.. _internal-urls:
.. _hosted-push:

Weblate internal URLs
+++++++++++++++++++++
Accessing repositories from Hosted Weblate
++++++++++++++++++++++++++++++++++++++++++

To share one repository between different components you can use a special URL
like ``weblate://project/component``. This way, the component will share the VCS
repository configuration with the referenced component, and the VCS repository will
be stored just once on the disk.
For Hosted Weblate there is a dedicated push user registered on GitHub, Bitbucket
and GitLab (with username :guilabel:`weblate` named
:guilabel:`Weblate push user`). You need to add this user as a collaborator and
give it appropriate permission to your repository (read only is okay for
cloning, write is required for pushing). Depending on service and your
organization settings, this happens immediately or requires confirmation from
Weblate side. The invitations on GitHub are accepted automatically within five
minutes, on other services manual processing is needed, so please be patient.

Once the :guilabel:`weblate` user is added, you can configure
:ref:`component-repo` and :ref:`component-push` using SSH protocol (for example
``git@github.com:WeblateOrg/weblate.git``).

.. _ssh-repos:

Expand All @@ -39,8 +47,8 @@ repository this way.

.. warning::

On GitHub, the key can be added to only one repository. Other solutions
are to be found in the corresponding sections below.
On GitHub, each key can be added to only one repository, see
:ref:`vcs-repos-github` and :ref:`hosted-push`.

Weblate also stores the host key fingerprint upon first connection, and fails to
connect to the host should it be changed later (see :ref:`verify-ssh`).
Expand All @@ -55,12 +63,11 @@ In case adjustment is needed, do so from the Weblate admin interface:
Weblate SSH key
~~~~~~~~~~~~~~~

Generate or display the public key currently used by Weblate in the (from :guilabel:`SSH keys`)
on the admin interface landing page. Once done, Weblate should be able to
access your repository.

The Weblate public key is visible to all users browsing the :guilabel:`About` page.

Admins can generate or display the public key currently used by Weblate in the
(from :guilabel:`SSH keys`) on the admin interface landing page.

.. note::

The corresponding private SSH key can not currently have a password, so make sure it is
Expand All @@ -87,6 +94,40 @@ confirmation message:

.. image:: images/ssh-keys-added.png

.. _vcs-repos-github:

GitHub repositories
+++++++++++++++++++

Access via SSH is possible (see :ref:`ssh-repos`), but in case you need to
access more than one repository, you will hit a GitHub limitation on allowed
SSH key usage (since one key can be used only for one repository).

For smaller deployments, use HTTPS authentication with a personal access
token and your GitHub account, see `Creating an access token for command-line use`_.

.. _Creating an access token for command-line use: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

For bigger setups, it is usually better to create a dedicated user for Weblate,
assign it the public SSH key generated in Weblate (see :ref:`weblate-ssh-key`)
and grant it access to all the repositories you want to translate. This
approach is also used for Hosted Weblate, there is dedicated
:guilabel:`weblate` user for that.

.. seealso::

:ref:`hosted-push`

.. _internal-urls:

Weblate internal URLs
+++++++++++++++++++++

To share one repository between different components you can use a special URL
like ``weblate://project/component``. This way, the component will share the VCS
repository configuration with the referenced component, and the VCS repository will
be stored just once on the disk.


HTTPS repositories
++++++++++++++++++
Expand Down Expand Up @@ -151,29 +192,6 @@ for translations.
Use with caution, as this easily leads to lost commits in your
upstream repository.

.. _vcs-repos-github:

GitHub repositories
+++++++++++++++++++

Access via SSH is possible (as mentioned above), but in case you need to access more
than one repository, you will hit a GitHub limitation on allowed SSH key
usage (since one key can be used only for one repository).

For smaller deployments, use HTTPS authentication with a personal access
token and your GitHub account, see `Creating an access token for command-line use`_.

.. _Creating an access token for command-line use: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

For bigger setups, it is usually better to create a dedicated user for Weblate,
assign it the public SSH key generated in Weblate and grant it access to all
the repositories you want to translate.

On Hosted Weblate, adding the ``weblate`` user is enough to grant the service
access to a repository. Once invited, the bot accepts the invitation
within five minutes, and as with :ref:`hosted-push`, you can use the SSH URL
to access your repo (for example ``git@github.com:WeblateOrg/weblate.git```).

Customizing Git configuration
+++++++++++++++++++++++++++++

Expand Down

0 comments on commit 58a8ee6

Please sign in to comment.