- Key Similarities and Differences
- Comparison of features and concepts
- Planning and Performing a Migration
Migrating from GitHub Actions
If you’re migrating from GitHub Actions to GitLab CI/CD, you are able to create CI/CD pipelines that replicate and enhance your GitHub Action workflows.
Key Similarities and Differences
GitHub Actions and GitLab CI/CD are both used to generate pipelines to automate building, testing, and deploying your code. Both share similarities including:
- CI/CD functionality has direct access to the code stored in the project repository.
- Pipeline configurations written in YAML and stored in the project repository.
- Pipelines are configurable and can run in different stages.
- Jobs can each use a different container image.
Additionally, there are some important differences between the two:
- GitHub has a marketplace for downloading 3rd-party actions, which might require additional support or licenses.
- Self-managed GitLab instances support both horizontal and vertical scaling, while GitHub Enterprise Server only supports vertical scaling.
- GitLab maintains and supports all features in house, and some 3rd-party integrations are accessible through templates.
- GitLab provides a built-in container registry.
- GitLab has native Kubernetes deployment support.
- GitLab provides granular security policies.
Comparison of features and concepts
Many GitHub features and concepts have equivalents in GitLab that offer the same functionality.
Configuration file
GitHub Actions can be configured with a workflow YAML file.
GitLab CI/CD uses a .gitlab-ci.yml
YAML file by default.
For example, in a GitHub Actions workflow
file:
on: [push]
jobs:
hello:
runs-on: ubuntu-latest
steps:
- run: echo "Hello World"
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
stages:
- hello
hello:
stage: hello
script:
- echo "Hello World"
GitHub Actions workflow syntax
A GitHub Actions configuration is defined in a workflow
YAML file using specific keywords.
GitLab CI/CD has similar functionality, also usually configured with YAML keywords.
GitHub | GitLab | Explanation |
---|---|---|
env | variables |
env defines the variables set in a workflow, job, or step. GitLab uses variables to define CI/CD variables at the global or job level. Variables can also be added in the UI. |
jobs | stages |
jobs groups together all the jobs that run in the workflow. GitLab uses stages to group jobs together. |
on | Not applicable |
on defines when a workflow is triggered. GitLab is integrated tightly with Git, so SCM polling options for triggers are not needed, but can be configured per job if required. |
run | Not applicable | The command to execute in the job. GitLab uses a YAML array under the script keyword, one entry for each command to execute. |
runs-on | tags |
runs-on defines the GitHub runner that a job must run on. GitLab uses tags to select a runner. |
steps | script |
steps groups together all the steps that run in a job. GitLab uses script to group together all the commands run in a job. |
uses | include |
uses defines what GitHub Action to be added to a step . GitLab uses include to add configuration from other files to a job. |
Common configurations
This section goes over commonly used CI/CD configurations, showing how they can be converted from GitHub Actions to GitLab CI/CD.
GitHub Action workflows
generate automated CI/CD jobs that are triggered when certain event take place, for example
pushing a new commit. A GitHub Action workflow is a YAML file defined in the .github/workflows
directory located in the root of the repository. The GitLab equivalent is the
.gitlab-ci.yml
configuration file which also resides
in the repository’s root directory.
Jobs
Jobs are a set of commands that run in a set sequence to achieve a particular result, for example building a container or deploying to production.
For example, this GitHub Actions workflow
builds a container then deploys it to production.
The jobs runs sequentially, because the deploy
job depends on the build
job:
on: [push]
jobs:
build:
runs-on: ubuntu-latest
container: golang:alpine
steps:
- run: apk update
- run: go build -o bin/hello
- uses: actions/upload-artifact@v3
with:
name: hello
path: bin/hello
retention-days: 7
deploy:
if: contains( github.ref, 'staging')
runs-on: ubuntu-latest
container: golang:alpine
steps:
- uses: actions/download-artifact@v3
with:
name: hello
- run: echo "Deploying to Staging"
- run: scp bin/hello remoteuser@remotehost:/remote/directory
This example:
- Uses the
golang:alpine
container image. - Runs a job for building code.
- Stores build executable as artifact.
- Runs a second job to deploy to
staging
, which also:- Requires the build job to succeed before running.
- Requires the commit target branch
staging
. - Uses the build executable artifact.
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
default:
image: golang:alpine
stages:
- build
- deploy
build-job:
stage: build
script:
- apk update
- go build -o bin/hello
artifacts:
paths:
- bin/hello
expire_in: 1 week
deploy-job:
stage: deploy
script:
- echo "Deploying to Staging"
- scp bin/hello remoteuser@remotehost:/remote/directory
rules:
- if: $CI_COMMIT_BRANCH == 'staging'
Parallel
In both GitHub and GitLab, Jobs run in parallel by default.
For example, in a GitHub Actions workflow
file:
on: [push]
jobs:
python-version:
runs-on: ubuntu-latest
container: python:latest
steps:
- run: python --version
java-version:
if: contains( github.ref, 'staging')
runs-on: ubuntu-latest
container: openjdk:latest
steps:
- run: java -version
This example runs a Python job and a Java job in parallel, using different container images.
The Java job only runs when the staging
branch is changed.
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
python-version:
image: python:latest
script:
- python --version
java-version:
image: openjdk:latest
rules:
- if: $CI_COMMIT_BRANCH == 'staging'
script:
- java -version
In this case, no extra configuration is needed to make the jobs run in parallel.
Jobs run in parallel by default, each on a different runner assuming there are enough runners
for all the jobs. The Java job is set to only run when the staging
branch is changed.
Matrix
In both GitLab and GitHub you can use a matrix to run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job.
For example, in a GitHub Actions workflow
file:
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo "Building $PLATFORM for $ARCH"
strategy:
matrix:
platform: [linux, mac, windows]
arch: [x64, x86]
test:
runs-on: ubuntu-latest
steps:
- run: echo "Testing $PLATFORM for $ARCH"
strategy:
matrix:
platform: [linux, mac, windows]
arch: [x64, x86]
deploy:
runs-on: ubuntu-latest
steps:
- run: echo "Deploying $PLATFORM for $ARCH"
strategy:
matrix:
platform: [linux, mac, windows]
arch: [x64, x86]
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
stages:
- build
- test
- deploy
.parallel-hidden-job:
parallel:
matrix:
- PLATFORM: [linux, mac, windows]
ARCH: [x64, x86]
build-job:
extends: .parallel-hidden-job
stage: build
script:
- echo "Building $PLATFORM for $ARCH"
test-job:
extends: .parallel-hidden-job
stage: test
script:
- echo "Testing $PLATFORM for $ARCH"
deploy-job:
extends: .parallel-hidden-job
stage: deploy
script:
- echo "Deploying $PLATFORM for $ARCH"
Trigger
GitHub Actions requires you to add a trigger for your workflow. GitLab is integrated tightly with Git, so SCM polling options for triggers are not needed, but can be configured per job if required.
Sample GitHub Actions configuration:
on:
push:
branches:
- main
The equivalent GitLab CI/CD configuration would be:
rules:
- if: '$CI_COMMIT_BRANCH == main'
Pipelines can also be scheduled by using Cron syntax.
Container Images
With GitLab you can run your CI/CD jobs in separate, isolated Docker containers
by using the image
keyword.
For example, in a GitHub Actions workflow
file:
jobs:
update:
runs-on: ubuntu-latest
container: alpine:latest
steps:
- run: apk update
In this example the apk update
command runs in an alpine:latest
container.
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
update-job:
image: alpine:latest
script:
- apk update
GitLab provides every project a container registry for hosting container images. Container images can be built and stored directly from GitLab CI/CD pipelines.
For example:
stages:
- build
build-image:
stage: build
variables:
IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $IMAGE .
- docker push $IMAGE
Variables
In GitLab, we use the variables
keyword to define different CI/CD variables at runtime.
Use variables when you need to reuse configuration data in a pipeline. You can define
variables globally or per job.
For example, in a GitHub Actions workflow
file:
env:
NAME: "fern"
jobs:
english:
runs-on: ubuntu-latest
env:
Greeting: "hello"
steps:
- run: echo "$GREETING $NAME"
spanish:
runs-on: ubuntu-latest
env:
Greeting: "hola"
steps:
- run: echo "$GREETING $NAME"
In this example, variables provide different outputs for the jobs.
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
default:
image: ubuntu-latest
variables:
NAME: "fern"
english:
variables:
GREETING: "hello"
script:
- echo "$GREETING $NAME"
spanish:
variables:
GREETING: "hola"
script:
- echo "$GREETING $NAME"
Variables can also be set up through the GitLab UI, under CI/CD settings, where you can protect or mask the variables. Masked variables are hidden in job logs, while protected variables can only be accessed in pipelines for protected branches or tags.
For example, in a GitHub Actions workflow
file:
jobs:
login:
runs-on: ubuntu-latest
env:
AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
steps:
- run: my-login-script.sh "$AWS_ACCESS_KEY"
If the AWS_ACCESS_KEY
variable is defined in the GitLab project settings, the equivalent
GitLab CI/CD .gitlab-ci.yml
file would be:
login:
script:
- my-login-script.sh $AWS_ACCESS_KEY
Additionally, GitHub Actions and GitLab CI/CD provide built-in variables which contain data relevant to the pipeline and repository.
Conditionals
When a new pipeline starts, GitLab checks the pipeline configuration to determine
which jobs should run in that pipeline. You can use the rules
keyword
to configure jobs to run depending on conditions like the status of variables, or the pipeline type.
For example, in a GitHub Actions workflow
file:
jobs:
deploy_staging:
if: contains( github.ref, 'staging')
runs-on: ubuntu-latest
steps:
- run: echo "Deploy to staging server"
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
rules:
- if: '$CI_COMMIT_BRANCH == staging'
Runners
Runners are the services that execute jobs. If you are using GitLab.com, you can use the shared runner fleet to run jobs without provisioning your own self-managed runners.
Some key details about runners:
- Runners can be configured to be shared across an instance, a group, or dedicated to a single project.
- You can use the
tags
keyword for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has autoscaling for runners. Use autoscaling to provision runners only when needed and scale down when not needed.
For example, in a GitHub Actions workflow
file:
linux_job:
runs-on: ubuntu-latest
steps:
- run: echo "Hello, $USER"
windows_job:
runs-on: windows-latest
steps:
- run: echo "Hello, %USERNAME%"
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
linux_job:
stage: build
tags:
- linux-runners
script:
- echo "Hello, $USER"
windows_job:
stage: build
tags:
- windows-runners
script:
- echo "Hello, %USERNAME%"
Artifacts
In GitLab, any job can use the artifacts keyword to define a set of artifacts to be stored when a job completes. Artifacts are files that can be used in later jobs.
For example, in a GitHub Actions workflow
file:
on: [push]
jobs:
generate_cat:
steps:
- run: touch cat.txt
- run: echo "meow" > cat.txt
- uses: actions/upload-artifact@v3
with:
name: cat
path: cat.txt
retention-days: 7
use_cat:
needs: [generate_cat]
steps:
- uses: actions/download-artifact@v3
with:
name: cat
- run: cat cat.txt
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
stage:
- generate
- use
generate_cat:
stage: generate
script:
- touch cat.txt
- echo "meow" > cat.txt
artifacts:
paths:
- cat.txt
expire_in: 1 week
use_cat:
stage: use
script:
- cat cat.txt
Caching
A cache is created when a job downloads one or more files and saves them for faster access in the future. Subsequent jobs that use the same cache don’t have to download the files again, so they execute more quickly. The cache is stored on the runner and uploaded to S3 if distributed cache is enabled.
For example, in a GitHub Actions workflow
file:
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo "This job uses a cache."
- uses: actions/cache@v3
with:
path: binaries/
key: binaries-cache-$CI_COMMIT_REF_SLUG
The equivalent GitLab CI/CD .gitlab-ci.yml
file would be:
cache-job:
script:
- echo "This job uses a cache."
cache:
key: binaries-cache-$CI_COMMIT_REF_SLUG
paths:
- binaries/
Templates
In GitHub an Action is a set of complex tasks that need to be frequently repeated and is saved
to enable reuse without redefining a CI/CD pipeline. In GitLab the equivalent to an action would
be a the include
keyword, which allows you to add CI/CD pipelines from other files,
including template files built into GitLab.
Sample GitHub Actions configuration:
- uses: hashicorp/setup-terraform@v2.0.3
The equivalent GitLab CI/CD configuration would be:
include:
- template: Terraform.gitlab-ci.yml
In these examples, the setup-terraform
GitHub action and the Terraform.gitlab-ci.yml
GitLab template
are not exact matches. These two examples are just to show how complex configuration can be reused.
Security Scanning features
GitLab provides a variety of security scanners out-of-the-box to detect vulnerabilities in all parts of the SLDC. You can add these features to your GitLab CI/CD pipeline by using templates.
for example to add SAST scanning to your pipeline, add the following to your .gitlab-ci.yml
:
include:
- template: Security/SAST.gitlab-ci.yml
You can customize the behavior of security scanners by using CI/CD variables, for example with the SAST scanners.
Secrets Management
Privileged information, often referred to as “secrets”, is sensitive information or credentials you need in your CI/CD workflow. You might use secrets to unlock protected resources or sensitive information in tools, applications, containers, and cloud-native environments.
For secrets management in GitLab, you can use one of the supported integrations for an external service. These services securely store secrets outside of your GitLab project, though you must have a subscription for the service:
GitLab also supports OIDC authentication for other third party services that support OIDC.
Additionally, you can make credentials available to jobs by storing them in CI/CD variables, though secrets stored in plain text are susceptible to accidental exposure. You should always store sensitive information in masked and protected variables, which mitigates some of the risk.
Also, never store secrets as variables in your .gitlab-ci.yml
file, which is public to all
users with access to the project. Storing sensitive information in variables should
only be done in the project, group, or instance settings.
Review the security guidelines to improve the safety of your CI/CD variables.
Planning and Performing a Migration
The following list of recommended steps was created after observing organizations that were able to quickly complete this migration.
Create a Migration Plan
Before starting a migration you should create a migration plan to make preparations for the migration.
Prerequisites
Before doing any migration work, you should first:
- Get familiar with GitLab.
- Read about the key GitLab CI/CD features.
- Follow tutorials to create your first GitLab pipeline and more complex pipelines that build, test, and deploys a static site.
- Review the
.gitlab-ci.yml
keyword reference.
- Set up and configure GitLab.
- Test your GitLab instance.
- Ensure runners are available, either by using shared GitLab.com runners or installing new runners.
Migration Steps
- Migrate Projects from GitHub to GitLab:
- (Recommended) You can use the GitHub Importer to automate mass imports from external SCM providers.
- You can import repositories by URL.
- Create a
.gitlab-ci.yml
in each project. - Migrate GitHub Actions jobs to GitLab CI/CD jobs and configure them to show results directly in merge requests.
- Migrate deployment jobs by using cloud deployment templates, environments, and the GitLab agent for Kubernetes.
- Check if any CI/CD configuration can be reused across different projects, then create and share CI/CD templates
- Check the pipeline efficiency documentation to learn how to make your GitLab CI/CD pipelines faster and more efficient.
Additional Resources
- Video: How to migrate from GitHub to GitLab including Actions
- Blog: GitHub to GitLab migration the easy way
If you have questions that are not answered here, the GitLab community forum can be a great resource.