In this article is a tutorial to get started with GitLab Runner, will show you how to install runner in AWS EC2 and registrations to GitLab.

Before you start, you need to make sure local with the following configuration:

  • login AWS CLI
  • Docker
  • nodejs

Gitlab runner config and deploy to AWS

Download the AWS EC2 GitLab runner to local

git clone https://github.com/aws-samples/amazon-ec2-gitlab-runner.git

cd amazon-ec2-gitlab-runner/

Open the sample-runner.properties and update the parameter align your AWS environment:

VpcID={your vpc id}
SubnetIds={your subnet id},{your subnet id2}
ImageId=ami-0de5311b2a443fb89
InstanceType=t2.micro
InstanceName=gitlab-runner-testing
VolumeSize=200
VolumeType=gp2
MaxSize=4
MinSize=1
DesiredCapacity=1
MaxBatchSize=1
MinInstancesInService=1
MaxInstanceLifetime=604800
GitlabServerURL="{your gitlab domain ex: https://gitlab.com}"
DockerImagePath="registry.gitlab.com/exampleuser/gitlab-runner:latest"
RunnerRegistrationTokens={your register token}
RunnerVersion=v1
RunnerEnvironment=dev
LambdaS3Bucket={your s3 bucket name}
Concurrent=2
CheckInterval=3
CostCenter=123456
AppId=1234

Start to deploy

./deploy-runner.sh <properties-file> <region> <aws-profile> <stack-name> 

For example:

./deploy-runner.sh sample-runner.properties ap-northeast-1 {local_aws_cli_profile_name} gitlab-runner-testing

Example of .gitlab-ci.yml and Env Var

Following is the example of the .gitlab-ci.yml that can be used for deploying lambda function to s3 and triggering the CodeDeploy process (the template.yaml and introduction will introduce later)

image: public.ecr.aws/sam/build-nodejs14.x

stages:
  - deploy

prod-build:
  stage: deploy 
  only:
    - master
  before_script:
    - pip3 install awscli --upgrade
    - pip3 install aws-sam-cli --upgrade
    - sam --version 
    - node -v
    - ls
  script:
    - sam build
    - make package
    - make deploy
  tags:
    - dev-v1-docker

Following is the CI/CD Variables for AWS Credentials

For execute AWS CLI, should add the following Variables into CI/CD settings:

Environment Variables Name Value
AWS_ACCESS_KEY_ID Your AWS Access Key ID
AWS_SECRET_ACCESS_KEY Your AWS Secret Access Key
AWS_DEFAULT_REGION Your default region
AWS_SESSION_TOKEN Your session token (if needed)
SAM_CLI_TELEMETRY set 0

Confirm Gitlab Runner register status

In Gitlab project > Settings > Ci/CD > Runners

Checking the Available specific runners, it should be registered with a runner name Gitlab Runner with Docker Executor.

Troubleshooting

(1) Deploy and get the runner error message

If you run the deploy-runner.sh and get the following error message:

Please confirm the command profile name and check your `~/.aws/config

Deploying Gitlab runner in the region: ap-northeast-1, using AWS profile: dev
CloudFormation stack name: gitlab-runner-testing
OSX
  adding: gitlab-runner-lifecycle-hook.py (deflated 73%)

The config profile (dev) could not be found

(2) Deploy and get the cloudformation rollback message

If you get the Cloudformation rollback status show RunnerAutoScalingGroup relative error:

Please confirm the VPC and SubnetIds.

(3) Running job not started

If in GitLab execute job and show the following error message:

This job is stuck because the project doesn't have any runners online assigned to it. Go to project CI settings

This job has not started yet
This job is in a pending state and is waiting to be picked by a runner

or

ValueError: Invalid endpoint: https://s3..amazonaws.com
make: *** [package] Error 1

Your can try fix this in project > Settings > Ci/CD > Runners

Click the Edit icon of your active runner, and on the edit detail page, select the checkbox: Run untagged jobs

or your can check the runner tag name, and add the tag name to your .gitlab-ci.yml

for example, the tag name is dev-v1-docker, and you should add the tag in your stage

prod-build:
  stage: package
  only:
    - master
  script:
    - make package
  tags:
    - dev-v1-docker

(4) Gitlab-ci access denied when call AWS CLI

When setting CI/CD variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and gitlab-ci execute the AWS CLI command, and get the error message:

An error occurred (AccessDenied)

You should confirm the CI/CD variable protected status, if yes, this means that only exposed to protected branches or protected tags.

Goto Settings > Repository > Protected branches to configure your branch protection settings

Reference

Gitlab runner

Deploy and Manage Gitlab Runners on Amazon EC2

Deploying AWS Lambda function using GitLab CI/CD