Skip to content

Latest commit

 

History

History
266 lines (224 loc) · 7.73 KB

4-dry-run.md

File metadata and controls

266 lines (224 loc) · 7.73 KB

Perform a dry-run migration of a GitLab pipeline

In this lab you will use the dry-run command to convert a GitLab pipeline to its equivalent GitHub Actions workflow.

Prerequisites

  1. Followed the steps here to set up your Codespace environment and start a GitLab server.
  2. Completed the configure lab.
  3. Completed the audit lab.

Perform a dry run

You will be performing a dry run against a pipeline in your preconfigured GitLab server. Answer the following questions before running this command:

  1. What project do you want to convert?

    • basic-pipeline-example

  2. What is the namespace for that project?

    • actions-importer

  3. Where do you want to store the result?

    • tmp/dry-run. This can be any path within the working directory from which GitHub Actions Importer commands are executed.

Steps

  1. Navigate to your codespace terminal

  2. Run the following command from the root directory:

    gh actions-importer dry-run gitlab --output-dir tmp/dry-run --namespace actions-importer --project basic-pipeline-example

  3. The command will list all the files written to disk when the command succeeds.

    $ gh actions-importer dry-run gitlab --output-dir tmp/dry-run --namespace actions-importer --project basic-pipeline-example
[2022-09-28 19:59:55] Logs: 'tmp/dry-run/log/actions-importer-20220928-195955.log'         
[2022-09-28 19:59:56] Output file(s):                                           
[2022-09-28 19:59:56]   tmp/dry-run/actions-importer/basic-pipeline-example/.github/workflows/basic-pipeline-example.yml

  4. View the converted workflow:

    • Find tmp/dry-run/actions-importer/basic-pipeline-example/.github/workflows in the file explorer pane in your codespace.
    • Click basic-pipeline-example.yml to open.

Inspect the output files

The files generated from the dry-run command represent the equivalent Actions workflow for the given GitLab pipeline. The GitLab pipeline and converted workflow can be seen below:

GitLab pipeline 👇 
stages:
  - build
  - test
  - deploy

image: alpine

build_a:
  stage: build
  script:
    - echo "This job builds something."
    - sleep 100

build_b:
  stage: build
  script:
    - echo "This job builds something else."
    - sleep 70

test_a:
  stage: test
  script:
    - echo "This job tests something. It will only run when all jobs in the"
    - echo "build stage are complete."

test_b:
  stage: test
  script:
    - echo "This job tests something else. It will only run when all jobs in the"
    - echo "build stage are complete too. It will start at about the same time as test_a."
    - sleep 300

deploy_a:
  stage: deploy
  script:
    - echo "This job deploys something. It will only run when all jobs in the"
    - echo "test stage complete."
    - sleep 600

deploy_b:
  stage: deploy
  script:
    - echo "This job deploys something else. It will only run when all jobs in the"
    - echo "test stage complete. It will start at about the same time as deploy_a."
    - sleep 400
Converted workflow 👇 
name: actions-importer/basic-pipeline-example
on:
  push:
  workflow_dispatch:
concurrency:
  group: "${{ github.ref }}"
  cancel-in-progress: true
jobs:
  build_a:
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job builds something."
    - run: sleep 100
  build_b:
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job builds something else."
    - run: sleep 70
  test_a:
    needs:
    - build_a
    - build_b
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job tests something. It will only run when all jobs in the"
    - run: echo "build stage are complete."
  test_b:
    needs:
    - build_a
    - build_b
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job tests something else. It will only run when all jobs in the"
    - run: echo "build stage are complete too. It will start at about the same time as test_a."
    - run: sleep 300
  deploy_a:
    needs:
    - test_a
    - test_b
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job deploys something. It will only run when all jobs in the"
    - run: echo "test stage complete."
    - run: sleep 600
  deploy_b:
    needs:
    - test_a
    - test_b
    runs-on: ubuntu-latest
    container:
      image: alpine
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: echo "This job deploys something else. It will only run when all jobs in the"
    - run: echo "test stage complete. It will start at about the same time as deploy_a."
    - run: sleep 400

Despite these two pipelines using different syntax they will function equivalently.

Perform a dry-run migration of a pipeline using included files

The previous example demonstrated a basic pipeline that mapped exactly to concepts in GitHub Actions. In this section, you will perform a dry run of the included-files-example pipeline that uses the include statement in GitLab:

include:
  - local: /config/build.gitlab-ci.yml
  - local: /config/test.gitlab-ci.yml

Run the following command from the root directory:

gh actions-importer dry-run gitlab --output-dir tmp/dry-run --namespace actions-importer --project included-files-example

The output of the command above can be seen below:

name: actions-importer/included-files-example
on:
  push:
  pull_request:
  workflow_dispatch:
concurrency:
  group: "${{ github.ref }}"
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 50
        lfs: true
    - run: echo "[BEFORE_SCRIPT] this is from test.gitlab-ci.yml"
    - run: echo "this is from a local file"
  test:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 50
        lfs: true
    - run: echo "[BEFORE_SCRIPT] this is from test.gitlab-ci.yml"
    - run: echo "this is from a local file"

It's important to note that GitHub Actions Importer converted this into a single workflow without templates. This is because of fundamental differences in how GitLab templates and GitHub Actions templates (that is, reusable workflows and composite actions) function in regards to job ordering. Unfortunately, elements of reusability will be sacrificed in order for the converted pipelines to function the same. It is likely that the output of GitHub Actions Importer could be refactored to use reusable workflows at a later date.

As an added challenge, try constructing and running the dry-run command yourself. Hint, you should only have to change the project name.

Next lab

Use custom transformers to customize GitHub Actions Importer's behavior