Merge pull request #2 from neovasili/improvement/codebuild-action

Proper logging capabilities

.Dockerignore

@@ -2,5 +2,6 @@
 .env
 __pycache__
 .git/
+.github/
 LICENSE
 action.yml

.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners.
+
+# These owners will be the default owners for everything in the repo.
+*       @7sevenlab/seven-lab
+
+# Order is important. The last matching pattern has the most precedence.
+# So if a pull request only touches javascript files, only these owners
+# will be requested to review.
+#*.js    @octocat @github/js
+
+# You can also use email addresses if you prefer.
+#docs/*  [email protected]

.github/labeler.yml

@@ -0,0 +1,27 @@
+---
+ci:
+    - .github/*
+    - .github/**/*
+
+documentation:
+    - ./*.md
+    - docs/*
+    - docs/**/*
+
+app:
+    - src/*
+    - src/**/*
+
+api:
+    - action.yml
+
+tests:
+    - tests/*
+    - tests/**/*
+
+docker:
+    - Dockerfile
+    - .Dockerignore
+
+dependencies:
+    - requirements.txt

.github/workflows/labeler.yml

@@ -0,0 +1,14 @@
+---
+name: "Pull Request Labeler"
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@main
+        with:
+          repo-token: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/pre-commit.yml

@@ -0,0 +1,21 @@
+---
+name: "Checks, linters and formatters"
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v2
+
+      - uses: pre-commit/[email protected]
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,4 +1,4 @@
 .DS_Store
 .env
 .dev
-__pycache__
+__pycache__

.pre-commit-config.yaml

@@ -0,0 +1,74 @@
+---
+fail_fast: true
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-vcs-permalinks
+      - id: detect-aws-credentials
+        args: [--allow-missing-credentials]
+      - id: no-commit-to-branch
+  - repo: https://github.com/sirosen/check-jsonschema
+    rev: 0.3.0
+    hooks:
+      - id: check-github-workflows
+        name: Check github workflows format
+  - repo: https://github.com/detailyang/pre-commit-shell
+    rev: v1.0.6
+    hooks:
+      - id: shell-lint
+        args: [--format=json]
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.19.0
+    hooks:
+      - id: yamllint
+        name: Yaml lintern
+        files: \.(yaml|yml|template)$
+        args:
+          [
+            --config-data,
+            "{extends: default, rules: {line-length: {max: 120, level: warning}}, yaml-files: ['*.yaml', '*.yml'], ignore: 'images/**/*.yml'}",
+          ]
+  - repo: https://github.com/Lucas-C/pre-commit-hooks-nodejs
+    rev: v1.1.1
+    hooks:
+      - id: dockerfile_lint
+        name: Dockerfile linter
+  - repo: https://github.com/markdownlint/markdownlint
+    rev: v0.11.0
+    hooks:
+      - id: markdownlint
+        args: [--rules, "~MD013"]
+  - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+    rev: v1.2.1
+    hooks:
+      - id: python-safety-dependencies-check
+        name: Python dependencies security check
+  - repo: https://github.com/PyCQA/flake8
+    rev: 3.9.1
+    hooks:
+      - id: flake8
+        name: Flake8 linter
+  - repo: https://github.com/PyCQA/pydocstyle
+    rev: 6.0.0
+    hooks:
+      - id: pydocstyle
+        name: Pycodestyle linter
+        args:
+          - --ignore=D100,D101,D102,D103,D104,D107,D203,D211
+  - repo: https://github.com/psf/black
+    rev: 20.8b1
+    hooks:
+      - id: black
+        name: Black python formatter
+        language_version: python
+        args:
+          - --line-length=120

Dockerfile

@@ -1,5 +1,6 @@
 FROM python:3.9.5-buster
 
+LABEL maintainer="Juan Manuel Ruiz Fernández"
 LABEL name="Docker image for AWS CodeBuild GitHub action"
 LABEL version="v1.0.0"
 

README.md

@@ -1,11 +1,121 @@
-# AWS CodeBuild github action
+# AWS CodeBuild GitHub action
+
+|Name|Badge|
+|:-:|:-:|
+|Checks, linters and formatters|[![Checks, linters and formatters](https://github.com/neovasili/aws-codebuild/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/neovasili/aws-codebuild/actions/workflows/pre-commit.yml)|
+|Quality|[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=neovasili_aws-codebuild&metric=alert_status)](https://sonarcloud.io/dashboard?id=neovasili_aws-codebuild)|
 
 This repository contains a GitHub action to invoke and integrate CodeBuild as part of a GitHub workflow with advanced features, like override environment image or passthrough source code using a S3 bucket, thus making your CodeBuild projects more reusable and agnostic to the git repository.
 
-[Project Roadmap](https://github.com/neovasili/aws-codebuild/projects/1)
+Here you can see the [project roadmap](https://github.com/neovasili/aws-codebuild/projects/1) for this GitHub action.
+
+- [AWS CodeBuild GitHub action](#aws-codebuild-github-action)
+  - [Motivation](#motivation)
+  - [Quick Start](#quick-start)
+    - [Minimal permissions](#minimal-permissions)
+    - [Setup your github workflow](#setup-your-github-workflow)
+  - [Features](#features)
+  - [References](#references)
+
+## Motivation
+
+Why this CodeBuild GitHub action if there is already an official one by AWS? There are two main motivations:
+
+- I already have it done and working since a while for private purposes, so I decided to "formalize" it and publish it.
+- Reusability of CodeBuild projects. There are several parameters that can be overridden in runtime that gives you a lot of flexibility and reusability of your CodeBuild projects with minimal effort. This GitHub Action is focused on it.
+
+## Quick Start
+
+This section will cover minimal usage of this action with no optional extra features; thus essentially, ability to call a CodeBuild project from GitHub actions and see log events from CodeBuild in GitHub actions logs.
+
+Unless you setup your CodeBuild project source from the repository, **this action will not pass your repository code automatically to CodeBuild** with this minimal setup.
+
+### Minimal permissions
+
+You will need to create an IAM user with the following minimum set of permissions:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": [
+                "codebuild:StartBuild",
+                "codebuild:BatchGetBuilds"
+            ],
+            "Resource": [
+                "YOUR_CODEBUILD_PROJECT_ARN"
+            ],
+            "Effect": "Allow"
+        },
+        {
+            "Action": "logs:GetLogEvents",
+            "Resource": [
+                "YOUR_CODEBUILD_PROJECT_LOG_GROUP_ARN"
+            ],
+            "Effect": "Allow"
+        }
+    ]
+}
+```
+
+Once you created it, it's recommended to store user AccessKey and AccessSecretKey as [GitHub secrets](https://docs.github.com/es/actions/reference/encrypted-secrets) to further use in the workflow.
+
+### Setup your github workflow
+
+You need to create a GitHub workflow yaml with this minimal content:
+
+```yaml
+---
+name: "Test CodeBuild action"
+
+jobs:
+  test-codebuild-action:
+    steps:
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-access-key-id: ${{ secrets.YOUR_IAM_USER_ACCESS_KEY_SECRET_NAME }}
+          aws-secret-access-key: ${{ secrets.YOUR_IAM_USER_ACCESS_SECRET_KEY_SECRET_NAME }}
+          aws-region: AWS_REGION_YOUR_GOING_TO_USE
+
+      - name: Run CodeBuild
+        uses: neovasili/[email protected]
+        with:
+          aws_region: AWS_REGION_YOUR_GOING_TO_USE
+          codebuild_job_name: YOUR_CODEBUILD_PROJECT_NAME
+          codebuild_log_group: YOUR_CODEBUILD_PROJECT_LOG_GROUP_NAME
+```
+
+As you can see, you need to first setup IAM credentials to be able to run the action against AWS resources.
+
+There are also three mandatory parameters to setup:
+
+- `aws_region`: The AWS region you are going to use, where your CodeBuild project is located
+- `codebuild_job_name`: The name of your CodeBuild project
+- `codebuild_log_group`: The name of your CodeBuild project log group
+
+## Features
+
+As mentioned before, the minimal setup of this action will let you:
+
+- Run a CodeBuild project from a GitHub workflow
+- See logs from CodeBuild in the GitHub workflow logs
+
+Nevertheless, as mentioned before, this action is intended mainly for reusability of CodeBuild projects with minimal effort, so it also implements some extra really useful features:
+
+- [Source code from S3](./docs/s3_source.md)
+- [Image override](./docs/image_override.md)
+- [Buildspec override](./docs/buildspec_override.md)
+- [Custom environment variables](./docs/custom_environment_variables.md)
 
 ## References
 
+- [S3 objects lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)
+- [ECR images lifecycle](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html)
+- [ECR cross account permissions](https://docs.amazonaws.cn/en_us/AmazonECR/latest/userguide/repository-policy-examples.html#IAM_allow_other_accounts)
+- [CodeBuild buildspec](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html)
 - [CodeBuild environment variables](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_EnvironmentVariable.html)
 - [CodeBuild environment variables secrets](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.secrets-manager)
 - [CodeBuild environment SSM parameter](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.parameter-store)

action.yml

@@ -27,7 +27,7 @@ inputs:
     description: "Optional image tag override to use for override image. Requires `override_image_ssm_base` input"
     required: false
   override_image_tag_prefix:
-    description: "Optional image tag prefix to use for override image. Requires `override_image_ssm_base` input"
+    description: "Optional image tag prefix to use for override image. Requires `override_image_ssm_base` input. Overridden by `override_image_tag` if specified"
     required: false
 
 runs:

docs/buildspec_override.md

@@ -0,0 +1,50 @@
+# Buildspec override
+
+⬑ [Return to index](../README.md)
+
+- [Buildspec override](#buildspec-override)
+  - [How it works](#how-it-works)
+  - [Configuration](#configuration)
+
+The buildspec references the definition of a CodeBuild project steps to execute once it's invoked. These steps can be defined on CodeBuild project provisioning time as well as on runtime, so for some specific cases you can easily alter the CodeBuild invoked job behaviour.
+
+This action, will use inline "injection" to override buildspec, that means that the buildspec file should exists in the repository.
+
+## How it works
+
+When this feature is enabled and properly configured will work following these steps:
+
+- Reads the buildspec file content from the provided file path in the `buildspec` input
+- Invokes CodeBuild passing the new buildspec definition
+
+## Configuration
+
+Last step is to let the GitHub workflow know where it needs to upload the code configuring the optional input `buildspec`:
+
+```yaml
+---
+name: "Test CodeBuild action"
+
+jobs:
+  test-codebuild-action:
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-access-key-id: ${{ secrets.YOUR_IAM_USER_ACCESS_KEY_SECRET_NAME }}
+          aws-secret-access-key: ${{ secrets.YOUR_IAM_USER_ACCESS_SECRET_KEY_SECRET_NAME }}
+          aws-region: AWS_REGION_YOUR_GOING_TO_USE
+
+      - name: Run CodeBuild
+        uses: neovasili/[email protected]
+        with:
+          aws_region: AWS_REGION_YOUR_GOING_TO_USE
+          codebuild_job_name: YOUR_CODEBUILD_PROJECT_NAME
+          codebuild_log_group: YOUR_CODEBUILD_PROJECT_LOG_GROUP_NAME
+          buildspec: RELATIVE_PATH_TO_BUILDSPEC_FILE_IN_REPO
+```
+
+As mentioned in the beginning, your need this to exists in the repository, so don't forget to add to your workflow a step that first checkouts the repository code into the GitHub actions agent.