ci-cd

README

ci-cd

Welcome

Demo

Getting Started

Contributing

Global Guidelines

• You can find contributing guidelines in CONTRIBUTING.md
• Feeling like something could be improved? Let's do it together! From code to documentation, services to use, or linter rules, everything is discussable and improvable, make a PR! Let's move forward together.

Concepts

• A repository such as this one is representing a project
• A project is basically an application
• An application is a microservice that works with other microservices to to achieve project's goals
• Microservices are small, loosely coupled, and independently deployable and scalable
• Each microservice should be agnostic of it downstreams. However, it should expose a clear and well-defined API to its downstreams for them to consume (that is, the microservice itself uses its upstreams' API)

Documentation

• Go code documentation is accessible thanks to pkgsite! Just run pkgsite in the root of the project to serve its documentation
• Global project documentation is available in the doc directory

Development Guidelines and Conventions

• All major directories contain a PURPOSE.md file with a brief description of directory's content and instructions on how to use it
• You are encouraged to create your own README.md files in subdirectories to provide project-specific instructions, and to document more-widely scoped topics in doc directory
• Code sharing is encouraged, such code should be placed in pkg and internal/pkg directories, as-per Go's conventions
• Importing other applications libraries and packages is encouraged, following code sharing encouragement
• First class code documentation (following Go doc comment guidelines) as well as project documentation is encouraged
• Following Learn Go with tests is encouraged
• Following Effective Go and Google's styleguide is encouraged
• Following locality of behaviour and principle of least astonishment is encouraged
• Variables, functions, methods, ... should be named in a short and descriptive way

Project development

• Deploy dev stacks of the layers, in ascending order of layer number (XX- prefix)
• Make changes and enjoy hot reloading!
• Once you are happy with your changes, create a PR!

Prerequisites

• Docker to run applications in containers. You should configure your credentials store and credential helpers for Docker to work with your container registry
• Go to install applications dependencies as needed
• Pulumi to manage Cloud resources
• kind to run Kubernetes clusters locally
• Kubectl to manage Kubernetes resources (not strictly required but quite handy)
• Very few other CLI tools such as git, bash, ... that are most likely already installed on your system

Running the project

• Common tasks such as running, testing, creating new IaC components, updating Cloud resources, ... are done by using kemutil. You are encouraged to install and use it!

CI / CD

Locally

• CI pipelines can be mimicked locally using ci-cd image, mounting project's directory as a volume in /src, and running the same commands as in the CI pipeline

• That is, you can run the following command to run the whole CI pipeline locally:

  kemutil ci [--fix] [--hot] ci
  

• When using --hot, your need to export GIT_TOKEN environment variable to propagate your git credentials to the container, so that it can fetch private dependencies. This is typically done by running:

  export GIT_TOKEN=$(gh auth token)
  

• Other commands are available, feel free to run kemutil help to see the list of available commands and their usage

False positives

• CI Pipelines can sometime report false positives. Here is what you can do to remediate (be as specific as possible on silences to avoid shadowing real issues):
  • golangci-lint: Add a nolint:<linter>[,<linter>] // <explanation> comment. See this doc
  • semgrep: Add a nosemgrep: <rule-id> comment. See this doc
  • gitleaks: Add finding fingerprint to .gitleaksignore. See this doc. Please note that any leaked secret should be revoked and replaced as soon as possible
  • markdownlint: Add a markdownlint-disable <rule> comment. See this doc
  • shellcheck: Add a shellcheck disable=<rule> comment. See this doc
  • hadolint: Add a hadolint ignore=<rule> comment. See this doc
  • actionlint: In case of a shellcheck error, refer to the shellcheck section. Otherwise, you can pass arguments to the linting action to ignore specific rules. See this doc
  • grype: Add an ignore in upstream repo-template .grype.yaml. See this doc. Please note that any vulnerability should be remediated as soon as possible, only add true false positives to the ignore list. Prefer deploying with a non-exploitable vulnerability reported rather than ignoring it.