PBS GitHub Actions Templates

Description

This is a collection of GitHub Actions templates managed by the PLOPS team (and friends) and cover various workflow scenarios like building/testing/publishing docker images, deploying/updating services into AWS ECS or running commands

Features

feature	description	template(s)
Slack updates	Send a Slack jobs status message to a channel and update it in real-time	all
AWS login via OIDC roles	Login into AWS using OIDC roles (created separately)	all
AWS ECR login	Login into AWS ECR	all
Secrets scanning	Scan for secrets inside the code	docker-build-push
Before action commands	Commands for preparing the environment	all
After action commands	Commands for tearing down the environment	all
Docker build, test and push	Build, test and push Docker images to AWS ECR; caching is enabled by default	docker-build-push
AWS ECS deploy	Deploy or update AWS ECS service	ecs-deploy
Run shell commands	Run shell commands	run-commands
SonarQube code quality	Scan and publish code quality to SonarQube	docker-build-push
Test results parser	Parse and publish test results to the GitHub Actions workflow	docker-build-push, run-commands
Package dependency tracker	Create SBOM (software bill of materials) from the docker image and publish to Dependency Tracker (WIP)	docker-build-push

Prerequisites

Create the team OIDC roles

• one role for each account
• permissions should be granular and minimum per required actions
• should be created via a ticket to the PLOPS team (CAT board)
• more details - WIP

Add secrets and environment variables

• secrets should be only passwords, tokens, keys, etc
• environment variables need to be set per environment (qa, staging, prod, etc)

variable	description	scope
APP_NAME	The application (service) name, including the environment (ex: app-test)	per env
AWS_ACCOUNT	AWS account ID	env
AWS_OIDC_ROLE	OIDC role name	account
AWS_REGION	AWS region name (ex: us-east-1)	env, global
SLACK_CHANNEL_ID	Slack channel ID	env, global
SONAR_HOST_URL	SonarQube host url	global

secret	description	scope
SLACK_BOT_TOKEN	Slack bot token with access to the SLACK_CHANNEL_ID	global
SONAR_TOKEN	SonarQube token	global

Templates

• you can use multiple jobs in the same workflow
• if dependency is required between the jobs, use needs

Base workflow (no jobs)

name: Workflow example

on:
  workflow_dispatch:
  pull_request:
    types:
      - opened
      - reopened

permissions:
  id-token: write
  contents: read

Docker Build / Test / Push

Build, test and push Docker images

Usage

jobs:
    build: 
      uses: pbs/gha-public-workflows/.github/workflows/docker-build-push.yml@main
      secrets: inherit
      with:
        env: test
        image_name: image-test
        image_build_tag: latest
        image_test_tag: test
        test_command: |
          echo "add commands that tests the image"
          docker run -t image-test:test echo "add another command ran inside the container"

Inputs

name	description	type	required	default
env	Environment	string	true	""
before_command	(Optional) Command to prepare the environment	string	false	""
test_command	Command to test the application	string	false	""
after_command	(Optional) Command to teardown the environment	string	false	""
assume_aws_role	Assume AWS role	boolean	false	true
ecr_login	Login to ECR	boolean	false	true
immutable	Repository is immutable	boolean	false	false
secrets_scan	Scan code for secrets before build	boolean	false	true
sbom	Retrieve and push the Docker image SBOM	boolean	false	false
image_name	Docker image name	string	true	""
image_build_tag	Docker image build tag	string	false	latest
image_test_tag	Docker image test tag	string	false	test
dockerfile	Path to the Dockerfile	string	false	./Dockerfile
context	Build context for Docker	string	false	.
parser	Publish test results using JUnit Parser	boolean	false	false
report_paths	JUnit Parser report paths	string	false	outdist/*.xml
sonarqube	Submit code coverage to Sonarqube	boolean	false	false
brief_slack_msg	Custom slack message for job end	string	false	""

ECS Deploy

Deploy or update an AWS ECS service

Usage

jobs:
    deploy:
      uses: pbs/gha-public-workflows/.github/workflows/ecs-deploy.yml@main
      secrets: inherit
      with:
        env: test
        ecs_cluster: test-cluster
        ecs_service: test-service
        image_name: test-templates
        image_tag: latest

Inputs

name	description	type	required	default
env	Environment	string	true	""
name	Deployment name	string	false	""
before_command	(Optional) Command to prepare the environment	string	false	""
after_command	(Optional) Command to teardown the environment	string	false	""
assume_aws_role	Assume AWS role	boolean	false	true
ecr_login	Login to ECR	boolean	false	true
ecs_cluster	ECS cluster name	string	true	""
ecs_service	ECS service name	string	true	""
image_name	Docker image name	string	true	""
image_tag	Docker image tag	string	false	latest
timeout	ECS deploy timeout(seconds)	string	false	600
brief_slack_msg	Custom slack message for job end	string	false	""

Run Commands

Run shell commands

Usage

jobs:
    run:
      uses: pbs/gha-public-workflows/.github/workflows/run-commands.yml@main
      secrets: inherit
      with:
        env: test
        name: testing123
        before_command: |
          echo "add optional commands that set up the environment prior to the build"
        command: |
          echo "main commands to be ran"
        after_command: |
          echo "add optional commands that cleans up the environment"

Inputs

name	description	type	required	default
env	Environment	string	true	""
name	Command name	string	true	""
before_command	(Optional) Command to prepare the environment	string	false	""
command	Command to run	string	false	""
after_command	(Optional) Command to teardown the environment	string	false	""
assume_aws_role	Assume AWS role	boolean	false	true
ecr_login	Login to ECR	boolean	false	true
parser	Publish test results using JUnit Parser	boolean	false	false
report_paths	JUnit Parser report paths	string	false	outdist/*.xml
brief_slack_msg	Custom slack message for job end	string	false	""

Secrets scanning

• the secrets scanning should be performed before other jobs
• this change is done to the GitHub Action workflows which run on push to feature branch or pull request to default branch
• add the following job to be triggered first

Usage

jobs:
    secrets-scanning:
      uses: pbs/gha-public-workflows/.github/workflows/secrets-scanning.yml@main
      permissions:
        contents: read
        id-token: write
        issues: write
        pull-requests: write

• add this to the rest of the jobs to make them dependent on the secrets-scanning job

    job1:
      needs: secrets-scanning
      ...
    job2:
      needs: secrets-scanning
      ...