Expand repo migration guide (#142)
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/142 Co-authored-by: n <n@noreply.codeberg.org> Co-committed-by: n <n@noreply.codeberg.org>
BIN
assets/images/advanced/access-token/generate-token.png
Normal file
After Width: | Height: | Size: 50 KiB |
BIN
assets/images/advanced/access-token/generate-token.webp
Normal file
After Width: | Height: | Size: 20 KiB |
BIN
assets/images/advanced/access-token/token-generated.png
Normal file
After Width: | Height: | Size: 19 KiB |
BIN
assets/images/advanced/access-token/token-generated.webp
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
assets/images/advanced/migrating-repos/git-migration.png
Normal file
After Width: | Height: | Size: 26 KiB |
BIN
assets/images/advanced/migrating-repos/git-migration.webp
Normal file
After Width: | Height: | Size: 7.7 KiB |
BIN
assets/images/advanced/migrating-repos/gitea-migration.png
Normal file
After Width: | Height: | Size: 38 KiB |
BIN
assets/images/advanced/migrating-repos/gitea-migration.webp
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
assets/images/advanced/migrating-repos/new-migration.png
Normal file
After Width: | Height: | Size: 16 KiB |
BIN
assets/images/advanced/migrating-repos/new-migration.webp
Normal file
After Width: | Height: | Size: 8.6 KiB |
38
content/advanced/access-token.md
Normal file
|
@ -0,0 +1,38 @@
|
||||||
|
---
|
||||||
|
eleventyNavigation:
|
||||||
|
key: AccessToken
|
||||||
|
title: Generating an Access Token
|
||||||
|
parent: AdvancedUsage
|
||||||
|
---
|
||||||
|
|
||||||
|
Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password.
|
||||||
|
|
||||||
|
> This guide explains how to generate an access token from the website. However, you can also generate access tokens from the API. Read more at [Gitea's documentation](https://docs.gitea.io/en-us/api-usage/#generating-and-listing-api-tokens).
|
||||||
|
|
||||||
|
## Generating an Access Token
|
||||||
|
Access tokens grant full access to your account. You must handle them securely.
|
||||||
|
|
||||||
|
<picture>
|
||||||
|
<source srcset="/assets/images/advanced/access-token/generate-token.webp" type="image/webp">
|
||||||
|
<img src="/assets/images/advanced/access-token/generate-token.png">
|
||||||
|
</picture>
|
||||||
|
|
||||||
|
1. In a web browser, go to Codeberg and click on the `Profiles and Settings` button on the top right. The button will be your profile picture.
|
||||||
|
2. Click on [`Settings`](https://codeberg.org/user/settings) in the dropdown.
|
||||||
|
3. Navigate to the [`Applications`](https://codeberg.org/user/settings/applications) settings tab.
|
||||||
|
4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field.
|
||||||
|
5. Click the generate token button.
|
||||||
|
|
||||||
|
<picture>
|
||||||
|
<source srcset="/assets/images/advanced/access-token/token-generated.webp" type="image/webp">
|
||||||
|
<img src="/assets/images/advanced/access-token/token-generated.png">
|
||||||
|
</picture>
|
||||||
|
|
||||||
|
Your access token has now been generated! Copy your token and store it securely.
|
||||||
|
|
||||||
|
> Be sure to generate new access tokens for each app you use, and delete them once they are not in use.
|
||||||
|
|
||||||
|
## Deleting an Access Token
|
||||||
|
Once you are done using an access token, you should delete an access token. Deleting an access token revokes access to your account for apps using the token.
|
||||||
|
|
||||||
|
To delete an access token, click the red `Delete` button next to the access token you want to delete, then click `Yes` in the popup. Your access token is now deleted.
|
|
@ -1,78 +1,57 @@
|
||||||
---
|
---
|
||||||
eleventyNavigation:
|
eleventyNavigation:
|
||||||
key: ThirdPartyTools
|
key: MigratingRepos
|
||||||
title: Migrating repositories
|
title: Migrating Repositories
|
||||||
parent: AdvancedUsage
|
parent: AdvancedUsage
|
||||||
---
|
---
|
||||||
|
|
||||||
## Migrating repositories
|
Using a distributed version control software system (like Git) allows you to keep control of the data inside the repository.
|
||||||
|
If you want to download a local copy of your files, you can `git clone` your repo, or download the repo from the web interface.
|
||||||
|
|
||||||
Using a distributed version control software system (like Git) allows you to easily keep in control of the data inside the repository.
|
This works well for moving files, but when you want to migrate metadata like issues, releases and a wiki, you can use the migration tool.
|
||||||
If you want to download a local copy of your data (not the metadata), just run `git clone </path/to/provider>/<user>/<project>.git` (or use the `Download Repository`-button on the main page) for that
|
|
||||||
(and replace `</path/to/provider>` with your privider, e.g. https://codeberg.org as well as `<user>` and `<project>` with your user and project name, respectively).
|
|
||||||
|
|
||||||
But when you want to migrate your repository including the metadata (e.g. issues, wiki, labels ...) different steps need to be taken.
|
<picture>
|
||||||
But Gitea tries to make this as easy as possible.
|
<source srcset="/assets/images/advanced/migrating-repos/new-migration.webp" type="image/webp">
|
||||||
|
<img src="/assets/images/advanced/migrating-repos/new-migration.png">
|
||||||
|
</picture>
|
||||||
|
|
||||||
For this you need to do the following:
|
On Codeberg, you can click on the plus symbol on the top right, and then select [`New Migration`](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool.
|
||||||
|
|
||||||
- create an access token on your primary Gitea-instance
|
## Selecting your host
|
||||||
- find an alternate Gitea instance (e.g. on https://codeberg.org, on another hosted Gitea-platform or run a local copy of Gitea yourself on your own machine)
|
Once you're at the [`New Migration`](https://codeberg.org/repo/migrate) page, you can select the Git host you are migrating from. If it's not on the list, you will have to select the Git option. This will not migrate metadata.
|
||||||
- create a new migration on your alternate Gitea instance where you supply the access token from your primary Gitea instance
|
|
||||||
- be sure to enable the migration items you want to use (e.g. issues, wiki, labels, ...)
|
|
||||||
|
|
||||||
For this documentation it is assumed that your primary Gitea instance is located on [Codeberg](https://codeberg.org) and your alternate Gitea instance is a private instance on your personal machine
|
Here we document instructions for migrating specific to each service. Once you've followed through, move on to [`Starting Migration`](#starting-migration).
|
||||||
(but the general migration workflow should work identical with any other Gitea instance and similarly with other supported Git hosting platforms).
|
|
||||||
|
|
||||||
|
### Migrating from Git
|
||||||
|
<picture>
|
||||||
|
<source srcset="/assets/images/advanced/migrating-repos/git-migration.webp" type="image/webp">
|
||||||
|
<img src="/assets/images/advanced/migrating-repos/git-migration.png">
|
||||||
|
</picture>
|
||||||
|
|
||||||
### Create access token
|
Here's an explanation of some fields on the [Git migration page](https://codeberg.org/repo/migrate?service_type=1):
|
||||||
|
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git`.
|
||||||
|
- **Username and Password**: Optionally, if authentication is required to access the repo, you can enter a username and password here.
|
||||||
|
|
||||||
On your primary Gitea instance at [Codeberg](https://codeberg.org) you need to go to `Profiles and Settings...` (on the top right corner), then to [`Settings`](https://codeberg.org/user/settings) (the option with the wrench symbol) and then to the [`Applications`-option](https://codeberg.org/user/settings/applications) (in the middle of the top bar).
|
### Migrating from Gitea
|
||||||
Click on the `Generate Token`-button to generate a new application token.
|
To migrate a repo with its metadata from a Gitea instance, you will first need to [create an access token](/advanced/access-token/) on the Gitea instance with your repository. Don't forget to delete the access token when you are finished.
|
||||||
|
|
||||||
Be aware that:
|
> You can also use this method to migrate your repos away from Codeberg to another Gitea instance.
|
||||||
|
|
||||||
- this token is not stored anywhere so write it down immediately
|
<picture>
|
||||||
- whoever is in possession of this token has almost limitless access to your account, so keep it safe
|
<source srcset="/assets/images/advanced/migrating-repos/gitea-migration.webp" type="image/webp">
|
||||||
- don't forget to revoke the access token as soon as the migration is finished
|
<img src="/assets/images/advanced/migrating-repos/gitea-migration.png">
|
||||||
|
</picture>
|
||||||
|
|
||||||
|
Here's an explanation of some fields on the [Gitea migration page](https://codeberg.org/repo/migrate?service_type=3):
|
||||||
|
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://gitea.com/gitea/tea`.
|
||||||
|
- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata.
|
||||||
|
- **Migration Items**: Here you can select the metadata you want migrated.
|
||||||
|
|
||||||
### Find (or install) alternate Gitea instance
|
<h2 id=starting-migration>Starting Migration</h2>
|
||||||
|
|
||||||
A list of Git hosting options can be found [here](https://git.wiki.kernel.org/index.php/GitHosting).
|
Once you've filled out all the fields, click the `Migrate Repository` button.
|
||||||
|
Migration might take a while, depending on how large the repo is.
|
||||||
|
|
||||||
If you want to install Gitea locally have a look [here](https://docs.gitea.io/en-us/).
|
When the repo code appears, migration is complete!
|
||||||
Some GNU/Linux distributions have Gitea already [prepackaged](https://docs.gitea.io/en-us/install-from-package/), for more details on what version is packaged see [here](https://repology.org/project/gitea/versions).
|
|
||||||
|
|
||||||
[Be](https://docs.gitea.io/en-us/install-from-binary/)
|
|
||||||
[sure](https://wiki.archlinux.org/title/Gitea#Installation)
|
|
||||||
[to](https://atetux.com/how-to-install-gitea-git-server-on-debian-10)
|
|
||||||
[look](https://linuxize.com/post/how-to-install-gitea-on-ubuntu-20-04/)
|
|
||||||
[for](https://linuxhint.com/install_gitea_ubuntu_self_hosted_git/)
|
|
||||||
[tutorials](https://www.howtoforge.com/how-to-install-gitea-with-https-on-debian-10/)
|
|
||||||
[on](https://www.howtoforge.com/how-to-install-gitea-code-hosting-platform-with-https-on-centos-8/)
|
|
||||||
[how](https://www.techrepublic.com/article/how-to-install-the-self-hosted-git-server-gitea-on-ubuntu-18-04/)
|
|
||||||
[to](https://techviewleo.com/how-to-install-gitea-on-amazon-linux/)
|
|
||||||
[install](https://www.cyberithub.com/10-simple-and-best-steps-to-install-gitea-on-ubuntu-20-04/)
|
|
||||||
[Gitea](https://www.osradar.com/install-gitea-ubuntu-20-04/)
|
|
||||||
[in](https://computingforgeeks.com/how-to-install-gitea-git-service-on-ubuntu/)
|
|
||||||
[case](https://linuxhostsupport.com/blog/how-to-install-gitea-on-ubuntu-18-04/)
|
|
||||||
[of](https://websiteforstudents.com/how-to-install-gitea-on-ubuntu-20-04-18-04/)
|
|
||||||
[doubt](https://morioh.com/p/b86cbaa47e8c)
|
|
||||||
(Codeberg does not guarantee for the correctness and actuality of these resources).
|
|
||||||
|
|
||||||
|
|
||||||
### Migrate your repository to your alternate Gitea instance
|
|
||||||
|
|
||||||
On your alternate Gitea instance, go to `Create...` (on the top right, the option with the `+` symbol) and then to [`New Migration`](https://codeberg.org/repo/migrate).
|
|
||||||
Then select the [Gitea-symbol](https://codeberg.org/repo/migrate?service_type=3&org=&mirror=) (the teacup).
|
|
||||||
In the field `Migrate / Clone From URL`, supply the url to your `Codeberg`-repository (`https://codeberg.org/<user>/<project>.git`).
|
|
||||||
Next add the access token to the appropriate field.
|
|
||||||
Be sure to check the `Migration Items` you want to transfer.
|
|
||||||
Then complete the rest of the form (`Owner`, `Repository Name`, ...).
|
|
||||||
When finished, press the `Migrate Repository` button.
|
|
||||||
|
|
||||||
That's it!
|
|
||||||
|
|
||||||
Just remember to revoke the access token as soon as you are finished.
|
|
||||||
|
|
||||||
|
> **Troubleshooting**: The migration process may time out after a while. If this happens, or if you have any other issues with migration, feel free to open an issue in the [Community Issue Tracker](https://codeberg.org/Codeberg/Community/issues).
|