Deploying Your First Pipeline With Gitlab
Pre-Requisites
For this tutorial, here is what you will need.
- A Gitlab Repo
- An empty .gitlab-ci.yml file in the root directory of your repository
- Installed Gitlab Runner (I am using the docker install https://docs.gitlab.com/runner/install/docker.html)
- Linux (I am using “Ubuntu Focal 20.04 (LTS)”
- Knowledge of the “flutter web build” command
- Generated public/private key pair (preferably using “id_e25519”)
- Your host key(s). See below on creating/verifying your keys.
https://docs.gitlab.com/ee/ci/ssh_keys/#verifying-the-ssh-host-keys
THE GOAL
You have some code in your gitlab repository to want to push to your server every time you or one of your team members makes a commit to a specific repo. Here is what happens.
- You have a repo (ie. my-repo)
- You commit a file to that repo
- The gitlab.yml takes over and deploys your files to your server.
Sounds simple right? Assuming you have the prerequisites, we’re ready to go.
PART I (The Setup)
Adding Our First Variable
- Your Navigate to Settings > CI/CD and scroll down to the variables section:
- Click “Add variable”
- Add your “Key Name”. This can be anything (ie. airplanes), and will be used in your .gitlab-ci.yml file later.
4. Enter your private key (including the BEGIN and END private key sections)
5. Click the checkbox for “Export variable to pipelines running on protected branches and tags only”
Generally speaking protecting your branch is a good idea, especially when working on an open source or shared project.
https://docs.gitlab.com/ee/ci/variables/README.html#protect-a-cicd-variable
Adding Our Second Variable
- Go to your terminal. We’re going to print our host keys and add them to Gitlab
# Use the domain name
ssh-keyscan example.com## Or use an IP
ssh-keyscan 1.2.3.4
2. Go back to the Settings > CI/CD and scroll down again to the variables section.
3. Add another variable. This time you are going to add your host key or keys you printed out. If you have multiple host keys that print out in the terminal, you can add all of them, each with their own line.
PART II (The .yaml or .yml File)
Now we have to edit our empty .gitlab-ci.yml which you placed in the root of your project directory before you started the tutorial. Because we are only deploying flutter web, flutter mobile and flutter desktop deployments do not really matter.
There are many components you can add to our .gitlab-ci.yml in order to build a successful pipeline, including breaking the stages into multiple steps and running multiple test. Some components are critical when you want to run a well designed production ready CI/CD pipeline. However in our case we want to keep things simple.
# Declare the docker image
image: cirrusci/flutter:latest# List of commands that are executed before the job
before_script:
— git fetch
— flutter config — enable-webbuild:
stage: deploy
script:
— cd {your-project-folder}
— flutter build web # Run Flutter build web
— which ssh-agent
— eval $(ssh-agent -s)
— echo {Your_First_PrivateKey_Variable} | tr -d ‘\r’ | ssh-add -
— mkdir -p ~/.ssh
— chmod 700 ~/.ssh
— ssh-keyscan {Your-Server-Ip-Address} >> ~/.ssh/known_hosts
— chmod 644 ~/.ssh/known_hosts
— scp -P22 -r build/* your-username@your-ip-address:/path/to/drop/files #copy generated build files
artifacts:
paths:
— /path/to/store/copy # Copying the build files to this folder
only:
— development # Run only on development branch
PART III (The Breakdown)
Docker Image
Sometimes you’ll want to build your own Docker image, but in this case we have a head start. You can check the image layers if you really want to see what is going on here https://tinyurl.com/ytnbzztt
Before_Script
These are a set of commands that are run before we run the actual deployment script. Let’s say you want to test whether some packages are installed or simply list your files/directories with the “ls” command, you could do that as well. While the “before script” is not required, we’ll add two commands here simply to see what the output is. In our case we are using
- Git Fetch
- Flutter config — enable web
Build
The majority of building the files and deploying to the server takes place here. As mentioned previously you could break up the file into several stages and builds if you want based on your preference for singularity of modularity.
Stage
There are five default stages. You can run only one stage, all stages, or anything in between during a build. Here we are running just the deploy stage
Script
The bulk of the operations are here. Below is a description of each process in the .yaml file
cd
into your project root. This is usually where yourpubspec.yaml
file is .Flutter web build
will compile the flutter files you need to deploy your webapp.Which ssh-agent
andeval
are the two commands that allow you to run the ssh-agent inside your environment. The SSH is a standard helper agent to manage identities and keys.- Settings > CI/CD > Variables. Remember you created a “key name for your private key in the gitlab UI (ie. airplanes)? This is where you use it.
- Create the SSH directory and give it the right permissions.
Mkdir
Wait a minute, don’t we already have an SSH directory on the remote server? Yes, but remember pipelines are being created on the fly for this one time instance. - If you followed the keyscan instructions above, you would have created a second variable with a key and value in Settings >CI/CD > Variables. So just drop your IP address or domain name here and of course we give it the right permissions.
Transferring files.
- There are several ways to transfer files to a server. We’ll use a simple scp setup with port 22.
- We’re telling the job to copy all files from the build folder — generated by the
flutter build web
command. - Then the job is logging into your server just like you would on the command line with your username@ip address.
- Add the path where you are dropping the files.
Artifacts
- Think of this as storage in Gitlab, where you want to place the completed files. This can be any existing folder in your Gitlab repo, meaning it should already exist.
Only:
- This command allows you to only run a pipeline under certain conditions
In this sample case, we have a branch named “development”, and only want to run the job when a commit is made on the “development” branch.
So replace “development” with your actual branch name(ie. master, qa, development etc).
Deploy
Now is the fun part. You’ll need to make a commit to whatever branch name you replaced above. Then sit back and watch the runner do the work. Shouldn’t take more than a minute.
You can watch the job run by clicking on pipelines/jobs in the Gitlab UI. After it’s run it course, at the bottom you should see “Job Succeeded” as well as the web folder on your remote server.
You now have your first pipeline run on your own remote server.
Feel free to join our growing flutter, dart, and devops community https://discord.gg/xWz8V7Wn