fix: proofread post

Author: elasticspoon

_posts/2025/01/30/2025-01-30-ci_overview.md

@@ -1,10 +1,10 @@
 ---
 layout: post
-title: "Github Actions CI"
+title: "Building a CI Platform on Github Actions"
 summary: An introduction to how we run CI at my company for 25 Rails apps on Github Actions using Docker Compose.
-cover-img: /assets/img/thumbnails/delayed_job.jpg
-thumbnail-img: /assets/img/thumbnails/delayed_job.jpg
-share-img: /assets/img/thumbnails/delayed_job.jpg
+cover-img: /assets/img/thumbnails/ci-overview.jpg
+thumbnail-img: /assets/img/thumbnails/ci-overview.jpg
+share-img: /assets/img/thumbnails/ci-overview.jpg
 readtime: true
 toc: true
 tags:
@@ -14,7 +14,7 @@ tags:
   - github-actions
 ---
 
-# Deploying and providing CI for 25 Rails Apps
+# Providing CI for 25 Rails Apps
 
 {: .box-warning .ignore-blockquote }
 
@@ -24,28 +24,31 @@ tags:
 
 ## Brief Background
 
-I work on something similar to a "platform" team for 130 Ruby on Rails developers. We run and provide CI (via self-hosted Github Actions) for the applications that other developers build.
+I work on something similar to a "platform" team for 130 Ruby on Rails developers. We run and provide continuous integration (CI) via self-hosted Github Actions for the applications that other developers build.
 
 {: .box-note .ignore-blockquote }
 
 <!-- prettier-ignore -->
 >**A bit more background**\\
-> To go a bit more in depth all the compute is handled by several Kubernetes clusters and the actual code lives in multiple repositories all under the same organization. Thus, a lot of the challenges we face are around providing flexibility for our developers without implementation details leaking out to them.
+> All the compute is handled by several Kubernetes clusters while the actual code lives in multiple repositories all under the same organization. Thus, a lot of the challenges we face are around providing flexibility for our developers without implementation details leaking out to them.
 
 Our apps all follow a fairly similar pattern:
 
+- they have their own github repository under our organization
 - they have a `Dockerfile`
-- get built as an image
-- get served via Kubernetes.
+- get built as an docker container image (my terminology might be wrong here)
+- get served via Kubernetes
 
 However, despite serving everything as containers our developers don't actually develop in containers. So to avoid the issue where production is the first place that our apps see containerized use we run all our tests in containers.
 
 ## How Do We Run CI?
 
-Basically all our apps have a structure like so:
+All our apps have this general structure:
 
 ```plaintext
 .
+├── app_code
+├── ...
 ├── .github
 │   └── workflows
 │      └── main.yaml
@@ -56,9 +59,9 @@ Basically all our apps have a structure like so:
 └── docker-compose.test.yaml
 ```
 
-The `Dockerfile` is nothing worth mentioning, it just sets up our application with whatever dependencies it needs (gems, node modules, etc).
+Our `Dockerfile` largely follows [the default generated by Rails](https://github.com/dylhack/rails/blob/main/railties/lib/rails/generators/rails/app/templates/Dockerfile.tt). The difference are mainly in the certs that we add to the image.
 
-The scripts in `bin` as just basic bash scripts that represent the testing process, linting process or whatever. For example:
+The scripts in `/bin` as just basic bash scripts that represent the testing process, linting process or whatever. For example:
 
 ```bash
 # bin/ci-lint
@@ -67,7 +70,7 @@ bundle exec brakeman
 bundle exec rubocop
 ```
 
-The idea is that these are the same scripts that a developer could run locally on their machine as in CI.
+The idea is that these are the same scripts that a developer could run locally on their machine. Reusing the scripts ensure they are the source of truth for both local and CI processes.
 
 The `docker-compose` looks something like this:
 
@@ -93,13 +96,14 @@ services:
       retries: 5
 ```
 
-Running `docker compose up` locally builds the image, starts Postgres, then runs the `command` in a container.
+Running `docker compose up` locally builds the image, starts Postgres, then runs `bin/ci-some-command` in against the container with the app. We specify a default command but docker compose allows us to override the command when called via command line.
 
-This translates nicely to CI because the developers are able create arbitrary scripts and those scripts will run in CI the same way as locally. For example if a particular app wants to use Cypress they can add that to the existing script or create a new script for it.
+CI runs tests via the same docker compose and an commands that a developer would run locally. Lets take a look at that.
 
 ## Getting It All Set Up in Github Actions
 
 So how does this all look as an actions workflow?
+
 {% raw  %}
 
 ```yaml
@@ -139,10 +143,10 @@ jobs:
         uses: our_org/actions/ruby-rspec-report@v4
 ```
 
-Largely it looks something like:
+To sum it up:
 
-1. we pull down the repo
-2. set up docker
+1. we pull down the repo (checkout)
+2. set up docker (login, setup buildx, bake)
 3. run the test in docker compose
 4. print a report.
 
@@ -159,33 +163,29 @@ Largely it looks something like:
 
 {% endraw %}
 
-The `DOCKER_RUN_CMD` here is simply to all passing in commands to run other `bin` scripts (ex: `bin/ci-lint` and `bin/ci-rspec`). I omitted showing the potential inputs that this action might receive.
+As mentioned before, the command in the `docker-compose` file can be override. The `DOCKER_RUN_CMD` here is passing in commands to run other `bin` scripts (ex: `bin/ci-lint` and `bin/ci-rspec`). I omitted showing the potential inputs that this action might receive.
 
 ## Benefits and Drawbacks
 
 ### Benefits
 
-The biggest benefit of this approach (and the one that makes it pretty much mandatory) is that our applications see containerized usage before landing in some higher environment (staging, qa, etc). The majority of our developers simply don't develop in docker, this, given that the final product is served in a container, testing in docker is the next best thing.
+**Shifting Docker Left**: The majority of our developers don't develop in docker. Thus, for our apps to see any containerized usage before the apps hit staging or production we need to run tests in docker. This makes docker in CI a necessity.
 
-Since our testing happens by starting docker compose and running a bash script with test commands the entire process is very platform agnostic. We don't have to worry about how do you set up ruby on GitHub Actions vs Jenkins vs CircleCI, then repeat for node, etc. We set up docker and that's it.
+**Platform Agnosticism**: Since our testing happens by starting `docker compose` and running a script with test commands the entire process is platform agnostic. We don't have to worry about differences in ruby / node / etc on GitHub Actions vs Jenkins vs CircleCI. We set up docker and that's it. And if we are protected if we ever need to switch to another provider.
 
 ### Drawbacks
 
-The main drawback (and I mean pure drawback not tradeoff) is performance overhead. This comes in two forms: container overhead and time to build the container.
-
-In terms of the container overhead, running software directly in the runner will always be faster than running it with docker compose on the runner. Does it really matter? Not really.
-
-The real problem we have encountered is the slow speed in building the images. The P90 of the setup step is 15 minutes on our biggest app (when all the layers miss the cache). Fixing this is still a work in progress.
+**Performance Overhead**: In terms of the container overhead, running software directly in the runner will always be faster than running it with `docker compose` on the runner. Does it really matter? Not really.
 
-### Shifted Complexity
-
-We have moved the complexity around within the actions jobs. Without docker there might be complexity in ensuring all required packages are present to test the app. With docker you get that for free but instead you have to worry about setting up and building the image. This made sense for us.
+**Container Build Overhead**: Building images is slow. The P90 of the setup step is 15 minutes on our biggest app (when all the layers miss the cache). Fixing this is still a work in progress.
 
 ## Conclusion
 
+We have moved the complexity around within the actions jobs. Without docker there might be complexity in ensuring all required packages are present to test the app. With docker you get that for free but instead you have to worry about setting up and building the image. This made sense for us, it might not for you.
+
 I left a lot of the detail out of my summary but we have about 25 web apps under us of varying sizes that we support this way. Beyond the initial setup the files in each app repository stay fairly static and developers largely get to ignore them. CI usually just works.
 
-That was a super brief overview of our CI and in a future post I will go a bit more in depth on how we provide a few cool features namely:
+That was a super brief overview of our CI and in future posts I will go a bit more in depth on how we provide a few cool features namely:
 
 - variably size parallelization of runs via input: `runner-count: 8`
 - providing arbitrary commands to get run via CI: `[{"cmd": "some-command"}]`