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>

content/advanced/access-token.md

@@ -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.

content/advanced/migrating-repos.md

@@ -1,78 +1,57 @@
 ---
 eleventyNavigation:
-  key: ThirdPartyTools
-  title: Migrating repositories
+  key: MigratingRepos
+  title: Migrating Repositories
   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.
-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).
+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.
 
-But when you want to migrate your repository including the metadata (e.g. issues, wiki, labels ...) different steps need to be taken.
-But Gitea tries to make this as easy as possible.
+<picture>
+  <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
-  - 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)
-  - 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, ...)
+## Selecting your host
+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.
 
-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
-(but the general migration workflow should work identical with any other Gitea instance and similarly with other supported Git hosting platforms).
+Here we document instructions for migrating specific to each service. Once you've followed through, move on to [`Starting Migration`](#starting-migration).
 
+### 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).
-Click on the `Generate Token`-button to generate a new application token.
+### Migrating from Gitea
+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
-  - whoever is in possession of this token has almost limitless access to your account, so keep it safe
-  - don't forget to revoke the access token as soon as the migration is finished
+<picture>
+  <source srcset="/assets/images/advanced/migrating-repos/gitea-migration.webp" type="image/webp">
+  <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/).
-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.
+When the repo code appears, migration is complete!
 
+> **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).