diff --git a/gitlab/5-migrate.md b/gitlab/5-migrate.md index fa42794..da0e78d 100644 --- a/gitlab/5-migrate.md +++ b/gitlab/5-migrate.md @@ -1,58 +1,55 @@ # Perform a production migration of a GitLab pipeline -In this lab, we will use the Valet `migrate` command to migrate a GitLab pipeline to GitHub Actions. -The previous commands used in the labs, such as `audit` and `dry-run` have prepared us to run a migration. -The `migrate` command will transform the Gitlab pipeline into a GitHub Actions workflow like the `dry-run` command did, but instead of writing these files locally, it will open a pull request with the files. -The pull request will contain a checklist of `Manual Tasks` if required. These tasks are changes that Valet could not do on our behalf, like creating a runner or adding a secret to a repository. -- [Prerequisites](#prerequisites) -- [Preparing for migration](#preparing-for-migration) -- [Performing the migration](#performing-a-migration) -- [Reviewing the pull request](#reviewing-the-pull-request) -- [Next Lab](#next-lab) +In this lab, you will use the `migrate` command to convert a GitLab pipeline and open a pull request with the equivalent Actions workflow. ## Prerequisites -1. Followed [steps](../gitlab#readme) to set up your codespace environment. -2. Completed the [configure lab](../gitlab/valet-configure-lab.md) -3. Completed the [dry-run lab](../gitlab/valet-dry-run-lab.md) -4. Completed the [dry-run lab with custom transformer](../gitlab/valet-custom-transformers-lab.md) - -## Preparing for migration - -Before running the command we need to collect some information: - 1. What is the project we want to migrate? __rails-example__ - 2. What is the namespace for that project? __Valet. In this case the namespace is the same as the group the project is in__ - 3. Where do we want to store the logs? __./tmp/migrate__. - 4. What is the URL for the GitHub repository we want to add the workflow too? __this repo!__. *When constructing the value for the migrate command it should match this url https://github.com/GITHUB-ORG-USERNAME-HERE/GITHUB-REPO-NAME-HERE with `GITHUB-ORG-USERNAME` and `GITHUB-REPO-NAME` substitued with your values* +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your Codespace environment and start a GitLab server. +2. Completed the [configure lab](./1-configure-lab.md#configuring-credentials). +3. Completed the [dry-run lab](./3-dry-run.md). +4. Completed the [custom transformers lab](./4-custom-transformers.md). ## Performing a migration -1. Run `migrate` command using the information collected above, make sure to update the `--target-url` value with the information from step 4. +We need to answer the following questions before running a `migrate` command: -``` -gh valet migrate gitlab --target-url https://github.com/GITHUB-ORG-USERNAME-HERE/GITHUB-REPO-NAME-HERE --output-dir ./tmp/migrate --namespace valet --project rails-example -``` +1. What is the project we want to migrate? + - __rails-example__ +2. What is the namespace for that project? + - __Valet__ +3. Where do we want to store the logs? + - __./tmp/migrate__ +4. What is the URL for the GitHub repository to add the workflow to? + - __this repository__. The URL should should follow the pattern with `:owner` and `:repo` replaced with your values. -2. Valet will create a pull request directly in the target GitHub repository. +### Steps -4. Open the pull request by clicking the green pull request link in the output of the migrate command, if you have trouble clicking it you can always copy and paste the url in your browser. +1. Run the following `migrate` command in the codespace terminal: -![pr-screen-shot](https://user-images.githubusercontent.com/18723510/184953133-9bafd9a1-c3f0-40b3-8414-f23cea698c8e.png) + ```bash + gh valet migrate gitlab --target-url https://github.com/:owner/:repo --output-dir ./tmp/migrate --namespace valet --project rails-example + ``` -## Reviewing the pull request +2. The command will write the URL to the pull request that was created when the command succeeds. -1. Lets first look at the `Conversation` tab of the PR. It tells us we have a manual task to perform before the GitHub Actions workflow is functional. We need to add a secret. We can use the GitHub [documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for secrets and add a `actions` secret for `PASSWORD` with any value. + ![img](https://user-images.githubusercontent.com/18723510/184953133-9bafd9a1-c3f0-40b3-8414-f23cea698c8e.png) -2. Review the workflow we are adding by clicking on `Files changed` tab. This is where you would double check everything looks good. If it didn't you could push commits with the required changes, prior to merging. +3. Open the generated pull request in a new browser tab. -3. Go back to the `Conversation` tab and click `Merge pull request` +### Inspect the pull request -4. Once the PR is merged the new workflow should start and we can view it by clicking `Actions` in the top navigation bar +The first thing we should notice about the PR is that there is a list of manual steps for us to complete. + +Next, let's review the workflow we are adding by clicking on `Files changed` tab. This is where you would double check everything looks good. If it didn't you could push commits with the required changes, prior to merging. + +Next, you can inspect the "Files changed" in this PR and see the converted workflow that is being added. Any additional changes or code reviews that were needed should be done in this PR. + +Finally, you can merge the PR once your review has completed. We can then view the workflow running by selecting the "Actions" menu in the top navigation bar in GitHub. -actions-screen-shot +![img](https://user-images.githubusercontent.com/18723510/184960870-590b1a28-422f-4350-9ec0-0423bf7ad445.png) -5. The migration is complete and we have successfully transformed a pipeline from GitLab into a GitHub Actions workflow, added it to a GitHub Repository, and run the workflow in Actions. +At this point, the migration has completed and you have successfully migrated a GitLab pipeline to Actions! ### Next Lab -This concludes the Valet labs for GitLab, if you are interested exploring the power of Valet more. You can leverage the demo GitLab Instance and modify and add new projects that more closely match your needs and try out the commands again! +[Forecast potential build runner usage](6-forecast.md)