Skip to content

continuous-integration.md

Latest commit

 

History

History
249 lines (183 loc) · 11.3 KB

continuous-integration.md

File metadata and controls

249 lines (183 loc) · 11.3 KB
Raw

GitHub Reusable Workflow: Continuous Integration

Continuous Integration

Release License Stars PRs Welcome GitHub Verified Creator

Overview

A comprehensive CI workflow that performs linting, builds Docker images, and runs tests against the built images using testcontainers.

Jobs

  1. linter: Runs code linting using the shared linter workflow
  2. prepare-images-to-build: Selects images to build for the current event
  3. build-images: Builds Docker images (depends on linter)
  4. prepare-test-matrix: Prepares the matrix for test jobs
  5. test-images: Runs testcontainers tests for each built image

Permissions

  • actions: read
  • contents: read
  • id-token: write
  • issues: write
  • packages: write
  • pull-requests: write
  • security-events: write
  • statuses: write

Testing

Tests are defined per image as images/<image>/<image>.test.js and executed with Node.js built-in test runner (node --test) from inside the configured ghcr.io/hoverkraft-tech/docker-base-images/testcontainers-node runner image.

Test Configuration

Each image has an <image>.test.js file that typically:

  • Start containers and execute commands
  • Verify file existence and permissions
  • Validate container metadata (env vars, user, workdir, etc.)
  • Check command outputs and exit codes

The workflow injects a few environment variables:

  • TESTED_IMAGE_REF: the image reference under test

The runner also writes a JUnit report to images/<image>/junit.xml, which is picked up by the CI report parsing step.

The workflow pulls the published runner image with the configured test-image-tag.

Example Test

import { after, before, describe, it } from "node:test";
import assert from "node:assert";
import { GenericContainer } from "testcontainers";

describe("CI Helm Image", () => {
  const testedImageRef = process.env.TESTED_IMAGE_REF;
  let container;

  if (!testedImageRef) {
    throw new Error("TESTED_IMAGE_REF environment variable is required");
  }

  before(async () => {
    container = await new GenericContainer(testedImageRef)
      .withCommand(["sleep", "infinity"])
      .start();
  });

  after(async () => {
    await container?.stop();
  });

  it("helm is installed", async () => {
    const { exitCode, output } = await container.exec(["helm", "version"]);
    assert.strictEqual(exitCode, 0);
    assert.match(output, /version/i);
  });
});

Usage

name: Continuous Integration
on:
  push:
    branches:
      - main
permissions: {}
jobs:
  continuous-integration:
    uses: hoverkraft-tech/docker-base-images/.github/workflows/continuous-integration.yml@536aff60442c9d70714c247aeb392dc762d84b4e # 0.7.0
    permissions:
      actions: read
      contents: read
      id-token: write
      issues: write
      packages: write
      pull-requests: write
      security-events: write
      statuses: write
    secrets:
      # Password or GitHub token (packages:read and packages:write scopes) used to log against the OCI registry.
      # Defaults to GITHUB_TOKEN if not provided.
      oci-registry-password: ""
    with:
      # JSON array of runner(s) to use.
      # See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
      #
      # Default: `["ubuntu-latest"]`
      runs-on: '["ubuntu-latest"]'

      # OCI registry where to pull and push images.
      # Default: `ghcr.io`
      oci-registry: ghcr.io

      # Username used to log against the OCI registry.
      # See https://github.com/docker/login-action#usage.
      #
      # Default: `${{ github.repository_owner }}`
      oci-registry-username: ${{ github.repository_owner }}

      # JSON array of platforms to build images for by default.
      # Can be overridden per image with `images/<image>/build.json` or an image object in `images`.
      # See https://docs.docker.com/buildx/working-with-buildx/#build-multi-platform-images.
      #
      # Default: `["linux/amd64","linux/arm64"]`
      platforms: '["linux/amd64","linux/arm64"]'

      # Tag of the published `testcontainers-node` runner image to use for tests.
      #
      # Default: `latest`
      test-image-tag: latest

Inputs

Workflow Call Inputs

Input Description Required Type Default
runs-on JSON array of runner(s) to use. false string ["ubuntu-latest"]
See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
oci-registry OCI registry where to pull and push images. false string ghcr.io
oci-registry-username Username used to log against the OCI registry. false string ${{ github.repository_owner }}
See https://github.com/docker/login-action#usage.
platforms JSON array of platforms to build images for by default. false string ["linux/amd64","linux/arm64"]
Can be overridden per image with images/<image>/build.json or an image object in images.
See https://docs.docker.com/buildx/working-with-buildx/#build-multi-platform-images.
test-image-tag Tag of the published testcontainers-node runner image to use for tests. false string latest

Secrets

Secret Description Required
oci-registry-password Password or GitHub token (packages:read and packages:write scopes) used to log against the OCI registry. false
Defaults to GITHUB_TOKEN if not provided.

Outputs

Output Description
built-images Built images data.
See https://github.com/hoverkraft-tech/ci-github-container/blob/main/.github/workflows/docker-build-images.md#outputs.

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2026 hoverkraft-tech

For more details, see the license.

This documentation was automatically generated by CI Dokumentor.