Building Cross-Platform CI/CD Actions with Docker

Last week I got hit by a headache - our perfectly tuned Lingo.dev GitHub Actions workflow couldn't run on a contributor's GitLab instance. Then I realized I’d actually like to run the same automation everywhere, regardless of the platform.

So I went on a quest to build a cross-platform CI automation that runs on GitHub, GitLab, and Bitbucket (and possibly others too!). The solution started as a simple GitHub Action but evolved into something more powerful when we needed to support multiple code hosting platforms.

I will walk you through the exact process:

1. starting simple, I will showcase how Github Actions work
2. leveling up to build reusable Docker image
3. finally I will show you how to run this on each platform

Follow the steps to build and ship your first cross-platform action. Or bookmark the article for later.

tl;dr see the template repository 👇👇👇

1. Starting Simple: Run JavaScript in GitHub Actions

Running a GitHub Action

Let's start with the simplest possible GitHub Action - one that runs a JavaScript file. First, create index.js in the root of your repository:

console.log("Hello World");

Now create a workflow file .github/workflows/hello.yml:

name: Hello World
on:
  push:
    branches:
      - main

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Say Hello
        run: node index.js

This action will:

1. Trigger on push to main branch
2. Check out your repository
3. Set up Node.js environment
4. Run your script

Making it Reusable

Now, let's make this action reusable by moving it to a separate repository. Create a new GitHub repository (e.g., hello-world-action like my example here) with these files:

1. index.js (same as before):

console.log("Hello World");

1. action.yml:

name: "Hello World Action"
description: "A simple action that says hello"
runs:
  using: "node20"
  main: "index.js"

Now you can use this action in any repository by referencing it in your workflow:

name: Use Hello Action
on:
  push:
    branches:
      - main

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        uses: your-username/hello-world-action@main

The key differences are:

1. The action lives in its own repository
2. action.yml defines how to run the action
3. Other repositories can reference it using uses: your-username/hello-world-action@ref

2. Leveling Up: Dockerized TypeScript Action

Now, let's create a more sophisticated action that runs TypeScript code. We'll need several files:

1. Initialize the project and set up TypeScript:
   

   pnpm init                # Creates package.json
   pnpm add -D typescript   # Install TypeScript as dev dependency
   
   

2. Update your package.json to add the build script:
   

   {
     "scripts": {
       "build": "tsc"
     }
   }
   
   

3. Then rename our index.js to index.ts to use TypeScript instead of JavaScript and move it to the src directory.

4. Create tsconfig.json to configure TypeScript compilation:
   

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "commonjs",
       "outDir": "./build",
       "rootDir": "./src",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true
     },
     "exclude": ["node_modules", "build", "**/*.test.ts"]
   }
   
   

5. Create a Dockerfile:
   

FROM node:20-slim

WORKDIR /app

# Install pnpm
RUN npm install -g pnpm

# Copy package files
COPY package.json pnpm-lock.yaml tsconfig.json /app

# Copy source code
COPY src /app/src

# Install dependencies
RUN pnpm install

# Build TypeScript code
RUN pnpm build

# Run the action
ENTRYPOINT ["node", "./build/index.js"]

1. Redefine the action in action.yml:

name: "Hello World TypeScript Action"
description: "A cross-platform TypeScript action example"
runs:
  using: "docker"
  image: "Dockerfile"

Running Docker Image Locally

To build and run the image defined in Dockerfile locally, you need Docker Desktop app. Then, assuming Docker is running locally, you can:

1. Build the image:

docker build -t hello-world-action .

1. Run it:

docker run hello-world-action

3. Cross-Platform Support

Now comes the most interesting part - running your action on other platforms. We'll need to:

1. Build and push our Docker image to a registry
2. Reference it in platform-specific configurations

Building and Publishing Docker Image

First, create a workflow to build and push the Docker image on every release. We will be using GitHub Container Registry (GHCR) that comes with your GitHub (free for public repositories, 500MB for private repositories on free plan).

name: Publish Docker image
on:
  push:
    branches:
      - main

jobs:
  push_to_registry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

Github Actions

To use this action in GitHub Actions of another repository, create a workflow file in .github/workflows/hello.yml (see GitHub Actions workflow syntax documentation):

name: Run Hello World
on:
  push:
    branches:
      - master

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - uses: your-username/hello-world-action@main

If you need to run this action on GitHub Actions only, there is no need to build and push the Docker image. GitHub Actions will build the Docker container directly from the Dockerfile specified in your action.yml file on each workflow run. This is more efficient since it avoids the extra steps of pushing to and pulling from a container registry. However, if you plan to use this action on other CI platforms like GitLab or Bitbucket, you'll need to publish the Docker image as shown above.

GitHub's free plan offers the most generous CI/CD minutes allocation among the three platforms. It includes:

• unlimited minutes for public repositories
• 2,000 minutes/month for private repositories

GitLab CI Configuration

Create .gitlab-ci.yml (see GitLab CI/CD documentation):

hello:
  image: ghcr.io/your-username/hello-world-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "main"

Your Gitlab free plan includes 400 CI/CD compute minutes per month regardless if the repository is public or private.

Bitbucket Pipelines

Create bitbucket-pipelines.yml (see Bitbucket Pipelines documentation):

image: docker:latest

pipelines:
  branches:
    main:
      - step:
          image: ghcr.io/your-username/hello-world-action:latest
          script:
            - echo "Done"

Bitbucket's free plan includes only 50 build minutes per month, regardless if the repository is public or private, making it the lowest free tier of all three platforms.

Other CI/CD Platforms

Since we published our Docker image in a public Github Container Registry, we can run this on any platform that supports Docker images. This is supported by:

• Circle CI (docs)
• Travis CI (docs)

Let me know if you run this somewhere else, I am curious about your use case!

---

💡 What can you do with this?

We built an action to run automated Lingo.dev localization for your web and mobile apps on any CI platform. On every commit it updates translations in your entire repository using Lingo.dev localization engine - either as a new commit or by opening a pull request (docs).

Example for GitHub:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    values:
        pull-request: 'true' # or false, we don't judge

---

You can build reusable actions and easily integrate them into your workflows regardless of the code hosting platform you are using. Here are some ideas for you:

• cross-platform test reporter (orchestrating end-to-end testing session)
• custom code quality checker (think formatting, linting, testing)
• release notes generator (how about publishing a changelog on your website?)

What would you use it for?

💥 Bonus: Template repository

If you don't feel like reading the rest of the article, you can find a template starter repository with all the code here. It contains the action - you can run it on GitHub, GitLab and Bitbucket.

https://github.com/mathio/awesome-action-starter

💡 Tip: Clone the repo and make it a starting point for your own action:

git clone https://github.com/mathio/awesome-action-starter.git my-action
cd my-action

…or just create a new repository from my template.

Then just implement your own action logic in src/index.ts file.

Conclusion

We've seen how to evolve from a simple shell-based GitHub Action to a sophisticated TypeScript action that can run anywhere. The key takeaways are:

1. Start simple with shell commands to validate your automation logic
2. Dockerize your action to make it portable
3. Use container registries to distribute your action across platforms
4. Adapt the configuration for each platform while keeping the core logic in Docker

This approach gives you the flexibility to run your automation anywhere while maintaining a single codebase. Happy automating!

---

I occasionally post about tech stuff and new Lingo.dev features on Twitter as @mathio28. Let's keep in touch.

Comments

[Max Prilutskiy]

This is really cool!

Curious – what platform had the best developer experience / APIs?

[Matej Lednický]

I have the best experience with Github. But maybe I just explored this platform the most since its my platform of choice. Free CI/CD usage for open source projects is definitely a nice perk ❤️

[Veronica Prilutskaya 🌱]

Great article!
And thanks for sharing the template repo!