Migrating my projects from GitLab to GitHub

This post is about migrating/mirroring a project that test and deploy to GitLab pages + another project that uses GitLab CI to build a JavaFx artifact.

GitLab makes it very easy to migrate by offering an interface to mirror repositories:

GitLab can push every repository changes to GitHub or, in the other direction, pull any changes from GitHub every 30 minutes. As we have nothing yet on GitHub, we'll use push.

Mirroring a GitLab repo to GitHub

1. Make a new GitHub repository (under your profile, "repositories", "new"). I used the same names as in GitLab.
2. You'll get an URL to clone the projet. Copy it.
3. In your GitLab repository, go to " settings", " mirroring", past the URL and your GitHub username. We'll need to create a GitHub token to put in the "password" field.
4. In GitHub, generate a token by going to your profile, "settings", "developer settings", "tokens" (https://github.com/settings/tokens).
5. In GitLab, paste the generated token in the "password" field.
6. Validate the form.
7. Click the two circular arrows to "Update now".

Done!

Only problem I encountered was GitHub scanning my code, looking for my email address and preventing me for committing (error "push declined due to email privacy restrictions"). You have to disable the "Block command line pushes that expose my email" option on https://github.com/settings/emails.

From GitLab pages to GitHub pages

GitHub has 3 types of pages : pages for the developer, pages for organizations, and pages for repositories. The last one is what we want (that's the only type of pages in GitLab anyway), you can find it in the repository settings.

You have two ways to deploy repository pages: using GitHub Actions or deploy form a branch.

"Deploy from a branch" is dead simple. It's an automated copy-and-paste of your project files to some webserver.

1. Go to the repository settings, "Pages".
2. Simply choose a branch.
3. Wait a couple of minutes.
4. GitHub will give you the URL of your page.

It's quite cool but I also would like to

• run some automated tests before deploying.
• timestamp my script in the deployed page.

For that we have to use the second option, "GitHub Actions", that is the equivalent of using GitLab CI to deploy a page.

From GitLab CI to GitHub Actions

There is several differences:

• In Gitlab, the workflow is defined in the .gitlab-ci.yml at the root of the project, whereas in GitHub, they use the ".github/workflows" folder at the root of the project. This folder will be scanned by GitHub to find the yml files that represent the workflows.
• In GitLab, you run shell scripts. You can also do that in GitHub (using the keyword "run"), but you can also run a set of scripts maintained by other people, called "actions" (using the keyword "uses"). For instance:

name: my-pretty-javafx-pipeline
run-name: Building PAN and uploading artifact
on:
  push:
    branches: ["githubPipelineTests"]
jobs:
  building-my-pretty-PAN-artifact:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:

    #############################################
    # Here we use an "action" to checkout to the master branch
    #############################################
    - uses: actions/checkout@v4
      with:
        ref: master

    #############################################
    # Here we use an "action" to setup Java 17
    #############################################
    - uses: actions/setup-java@v4
      with:
        distribution: 'adopt'
        java-version: '17'

   #############################################
   # Here we use a script to clean/install the project
   #############################################
    - name: building my pretty PAN artifact
      run: |
          mvn clean install -Djavafx.platform=win -P windows-build,dl-windows-jdk
          ls target        

Why would we use "actions"? Why not use our own scripts? We could type "git checkout master" or "apt install openjdk-17-jdk openjdk-17-jre" ourselve instead of using actions. But, well, don't reinvent the wheel I guess. Also, actions can get pretty complex so it can help save a lot of time.

Deploying GitHub pages with GitHub Actions

Alright so how to deploy a page using Actions?

1. Create a .github/workflows in your project root.
2. Make a yml file, for instance actions.yml.

Now, you need to write the workflow inside. Fortunately, going to the "actions" page on your repository will offer you a "new workflow" button. Here you can search a pages workflow and use it as an inspiration.

This is what I ended up with. Deploying using GitHub actions:

run-name: Deploying the sample game to GitHub pages
# Will be launched in case of...
on:
  # ...a push on the tryingGhActions branch.
  push:
    branches: ["tryingGhActions"]
jobs:
  the-pretty-deployment:
    permissions:
      contents: read
      pages: write
      id-token: write

    environment:
      # This "github-pages" environment is created automatically by GitHub
      # check the deployment rules here, you may have to relax some rules:
      # https://github.com/marl1/cyoajsengine/settings/environments
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    runs-on: ubuntu-latest

    steps:
      # Git checkout on the tryingGhActions branch
      - name: Checkout
        uses: actions/checkout@v4        
        with:
          ref: tryingGhActions
      # Enable Pages and extract various metadata about a site
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload only the content of this folder, will be on https://marl1.github.io/cyoajsengine/games/
          path: './www'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4        

This is my final workflow, after adding the playwright automated testing and the timestamp :

name: my-pretty-test-and-deploy-pipeline
run-name: Testing the sample game with Playwright then deploy to GitHub pages
# Will be launched in case of...
on:
  # ...a push.
  push:
    branches: ["master"]
    # ...a manual action from the Actions tab
  workflow_dispatch:
jobs:
  # This is my testing job. You can ignore it if you don't use playwright
  testing-cyoa-engine-using-playwright:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    
     # I run the nodejs server to serve the website...
    - name: starting node server
      run: npm run start&
    # I test different things on the website
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30
  #End of the testing job. 
  #This is my deployment job.
  the-pretty-deployment:
    # I want it to depend of my testing job, remove the needs line 
    needs: testing-cyoa-engine-using-playwright
    permissions:
      contents: read
      pages: write
      id-token: write

    environment:
      # This "github-pages" environment is created automatically by GitHub
      # check the deployment rules here https://github.com/marl1/cyoajsengine/settings/environments
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    runs-on: ubuntu-latest

    steps:
      # Git checkout on the master branch
      - name: Checkout
        uses: actions/checkout@v4        
        with:
          ref: master
      - name: TimeStamping
        run: |
          echo "Using a timestamp to avoid browser cache..."
          timestamp=$(date +%s)
          sed -i "s,moteurldvelh.js,moteurldvelh.js?$timestamp," ./www/games/a_sample_game/index.htm
          sed -i "s,moteurldvelh.js,moteurldvelh.js?$timestamp," ./www/games/cyberpunk/index.htm
      # Enable Pages and extract various metadata about a site
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload only the content of this folder
          # will be on https://marl1.github.io/cyoajsengine/
          path: './www'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4        

The page is live on: https://marl1.github.io/cyoajsengine/games/a_sample_game/

Making a JavaFx artifact, from GitLab CI to GitHub actions

I want to migrate a script that:

1. Get the name of the project and the version (by looking at the POM)
2. build the artifact (basically mvn clean install + some options)
3. store the artifact with the name at step 1.

Let's take a look of my GitLab pipeline first, highlighting the differences to come:

stages:
  - .pre
  - build

pre_config:
  image: maven:3.8.4-openjdk-17 # won't work on GitHub, won't find the image
                                                      # Need to use ubuntu then install Java.
  stage: .pre
  script:
      - VERSION=$(mvn org.apache.maven.plugins:maven-help-plugin:3.1.1:evaluate -Dexpression=project.version -q -DforceStdout)
      - echo $VERSION
      - ARTIFACT_ID=$(mvn org.apache.maven.plugins:maven-help-plugin:3.1.1:evaluate -Dexpression=project.artifactId -q -DforceStdout)
      - echo $ARTIFACT_ID
      - export FULL_NAME=$(echo "$ARTIFACT_ID"-"$VERSION")
      - echo FULL_NAME=$FULL_NAME >> mesVariables.env      
  artifacts:
    paths:
      - public
    name: "artifacts"
    reports:
      dotenv: mesVariables.env # Gitlab use "env" to pass variables around, GitHub use
                                                # a GITHUB_OUTPUT  variable

build_artifacts:
  image: maven:3.8.4-openjdk-17
  stage: build
  script:
      - 'mvn clean install -Djavafx.platform=win -P windows-build,dl-windows-jdk'
      - 'ls target'
  artifacts:
    name: $FULL_NAME
    paths:
      - target/${FULL_NAME}-win/*        

Now the same script working on GitHub. You can see several actions used (to checkout, to install Java, to upload the artifact...).

name: my-pretty-javafx-pipeline
run-name: Building PAN and uploading artifact
on:
  push:
    branches: ["githubPipelineTests"]
jobs:
  building-my-pretty-PAN-artifact:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        ref: master
    - uses: actions/setup-java@v4
      with:
        distribution: 'adopt'
        java-version: '17'
    - name: building my pretty PAN artifact
      run: |
          mvn clean install -Djavafx.platform=win -P windows-build,dl-windows-jdk
          ls target
    - name: Generate artifact name
      id: generate-name
      run: |
        VERSION=$(mvn org.apache.maven.plugins:maven-help-plugin:3.1.1:evaluate -Dexpression=project.version -q -DforceStdout)
        echo $VERSION
        ARTIFACT_ID=$(mvn org.apache.maven.plugins:maven-help-plugin:3.1.1:evaluate -Dexpression=project.artifactId -q -DforceStdout)
        echo $ARTIFACT_ID
        export FULL_NAME=$(echo "$ARTIFACT_ID"-"$VERSION")
        echo FULL_NAME=$FULL_NAME >> $GITHUB_OUTPUT 
    - name: Upload artifact
      uses: actions/upload-artifact@v4
      with:
        name: ${{ steps.generate-name.outputs.FULL_NAME }}
        path: target/*.jar        

That concludes this long article, hope it'll be useful.

Bonus: include a video in the markdown file on GitLab AND GitHub

See the script and comments below.

Example : https://gitlab.com/marclv/picturesautonamer / https://github.com/marl1/picturesautonamer

For GitLab, as simple as that, assuming demo.mp4 is at the root of your project:

![](demo.mp4)

For GitHub, upload your vid somewhere and do:

<video src="https://github.com/marl1/picturesautonamer/assets/23550999/8638ef79-61fb-4b08-8ab8-44dd6036f4f5" width="320" height="240" controls></video>

GitHub won't display GitLab video and vice versa so you can use the same file and have the video displayed only once :-)