diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a273700..8ef3c7c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,25 +1,36 @@ name: CI/CD Pipeline +# Triggers and action summary: +# pull-request -> build and verify. +# push develop -> build, verify, and push image tagged : and :develop. +# push main -> build, verify, and push image tagged :latest. +# push tag -> build, verify, and push image tagged :. + env: CACHE_FROM: type=gha,scope=simdb-dashboard CACHE_TO: type=gha,mode=max,scope=simdb-dashboard on: - # Triggers on pushes to develop, on pushed tags, and on pull requests targeting develop. push: - branches: [ "develop" ] + branches: [ "develop", "main" ] tags: [ "*" ] pull_request: branches: [ "develop" ] +# Serialize runs per ref, so that two merges in quick succession can't race to +# move the "develop" image tag backward. Superseded runs are not cancelled, so +# every merged commit still gets a versioned image. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + jobs: build: - name: Build, verify, and package + name: Build and verify runs-on: ubuntu-latest - outputs: - version: ${{ steps.version.outputs.value }} permissions: - contents: read + contents: write + packages: write steps: - name: Checkout code uses: actions/checkout@v7 @@ -98,76 +109,56 @@ jobs: path: ${{ runner.temp }}/dist/ retention-days: 7 - - name: Export service image tar - run: docker save -o "${{ runner.temp }}/simdb-dashboard-service.tar" simdb-dashboard:service - - - name: Upload service image artifact - uses: actions/upload-artifact@v7 - with: - name: simdb-dashboard-service - path: ${{ runner.temp }}/simdb-dashboard-service.tar - retention-days: 7 - - publish: - name: Publish service image - # Runs only for push events (branch/tag pushes), and is skipped for pull_request events. - if: ${{ github.event_name == 'push' }} - runs-on: ubuntu-latest - needs: build - permissions: - contents: write - packages: write - steps: + # Everything below publishes; it is skipped entirely for pull requests. - name: Lowercase repo-owner + if: ${{ github.event_name == 'push' }} id: repo_owner run: echo "value=${GITHUB_REPOSITORY_OWNER,,}" >> "$GITHUB_OUTPUT" - - name: Download service image artifact - uses: actions/download-artifact@v8 - with: - name: simdb-dashboard-service - path: ${{ runner.temp }} - - - name: Download dist artifact - uses: actions/download-artifact@v8 - with: - name: simdb-dashboard-dist - path: ${{ runner.temp }}/dist - - - name: Load service image - run: docker load -i "${{ runner.temp }}/simdb-dashboard-service.tar" - - name: Login to GitHub Container Registry + if: ${{ github.event_name == 'push' }} uses: docker/login-action@v4 with: registry: ghcr.io username: ${{ steps.repo_owner.outputs.value }} password: ${{ secrets.GITHUB_TOKEN }} + # Run on branch pushes (except main, it'll follow develop) and _any_ tag pushes. - name: Tag and push service image with version tag + if: ${{ github.event_name == 'push' && github.ref_name != 'main' }} + run: | + docker tag \ + simdb-dashboard:service \ + ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ steps.version.outputs.value }} + docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ steps.version.outputs.value }} + + # Run on develop pushes only + - name: Tag image :develop and publish + if: ${{ github.event_name == 'push' && github.ref_name == 'develop' }} run: | docker tag \ simdb-dashboard:service \ - ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} - docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:${{ needs.build.outputs.version }} + ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop + docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:develop - # These steps run on tagged commits only — `:latest` tag and GitHub Release. - - name: Tag and push latest - if: ${{ github.ref_type == 'tag' }} + # Run on main pushes only + - name: Tag image :latest and publish + if: ${{ github.event_name == 'push' && github.ref_name == 'main' }} run: | docker tag \ simdb-dashboard:service \ ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:latest docker push ghcr.io/${{ steps.repo_owner.outputs.value }}/simdb-dashboard:latest + # This step runs on tag pushes only - name: Package and upload release tarball - if: ${{ github.ref_type == 'tag' }} + if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }} env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} run: | tar -czf "${{ runner.temp }}/simdb-dashboard-dist.tar.gz" \ -C "${{ runner.temp }}/dist" . - gh release create "${{ needs.build.outputs.version }}" \ + gh release create "${{ steps.version.outputs.value }}" \ "${{ runner.temp }}/simdb-dashboard-dist.tar.gz" \ --generate-notes diff --git a/docker-compose.systemd.yml b/docker-compose.systemd.yml index 291adf9..c550ad0 100644 --- a/docker-compose.systemd.yml +++ b/docker-compose.systemd.yml @@ -3,7 +3,13 @@ # Uses the GHCR-published image instead of a local build. # # Set SIMDB_DASHBOARD_TAG in the environment file to pin a specific -# version. The default is the latest tag at the time of writing. +# version. The default is the latest tag. +# +# Published tags (ghcr.io/iterorganization/simdb-dashboard): +# immutable per-commit build, pin for reproducibility (e.g. 0.9.0) +# latest most recently pushed tag (default; moves after any tag push) +# develop tip of develop, for (pre-production) testing only +# See docs/installation.md#published-image-tags-ghcr. # # Enable this override by including it in COMPOSE_FILE, # after the original, e.g. diff --git a/docs/development.md b/docs/development.md index 205b928..0074270 100644 --- a/docs/development.md +++ b/docs/development.md @@ -48,3 +48,10 @@ make type-check ``` At the moment, the project does not include test files, so `make test` will exit with no tests found. + +## Releases and image tags + +Pushing a tag makes CI publish a versioned image and a GitHub Release, and moves +`latest`; pushes to `develop` move `develop`. The version comes from +`git describe --tags`, so tag releases as plain versions (`0.9.0`) and don't leave +stray tags around. See [Published image tags](installation.md#published-image-tags-ghcr). diff --git a/docs/installation.md b/docs/installation.md index f05898d..1060b73 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -77,7 +77,7 @@ sudo make systemd-start - `COMPOSE_FILE`: default systemd stack is `docker-compose.yml:docker-compose.systemd.yml`. - `SIMDB_DASHBOARD_IMAGE`: optional image repository override (default `ghcr.io/iterorganization/simdb-dashboard`). -- `SIMDB_DASHBOARD_TAG`: optional image tag (default `latest` in `docker-compose.systemd.yml`). +- `SIMDB_DASHBOARD_TAG`: optional image tag (default `latest` in `docker-compose.systemd.yml`; see [Published image tags](#published-image-tags-ghcr)). - `SYSTEMD_CONTAINER_NAME`: optional docker container name override (see `docker-compose.systemd.yml`). - `DASHBOARD_PORT`: host HTTP port (default `80`). - `DASHBOARD_HTTPS_PORT`: host HTTPS port (default `443`). @@ -88,6 +88,23 @@ sudo make systemd-start See `scripts/simdb-dashboard.env.example` and `scripts/simdb-dashboard.service` for the same defaults and where they are consumed. +## Published image tags + +CI publishes `ghcr.io/iterorganization/simdb-dashboard` docker images on every +push to `develop` or `main`, and on tagged commits (releases): + +| Tag | Pushed on | Mutable | +| --- | --- | --- | +| `` | `develop` and tag pushes | no | +| `develop` | `develop` pushes | yes | +| `latest` | `main` pushes | yes | + +`` is `git describe --tags --always` at the pushed commit (e.g. `0.9.0` on a +tag, `0.9.0-12-gabc1234` otherwise). The versioned image is therefore treated as +immutable and never reused across events. + +Deploy `latest` (the default, "stable") or pin a version for reproducibility. + ## Local container building and installation workflow (Docker image + Compose) For building and running docker containers directly (without need for systemd or root), also for development or tweaking. @@ -213,7 +230,8 @@ index path should be `/www/data/dashboard/index.html`. ## Exporting a runnable service image tar (non-Compose) -If you want a portable Docker image artifact (similar to CI artifacts), use: +If you want a portable Docker image tar — for example to move the image to a +host that cannot pull from the registry — use: ```sh make simdb-dashboard-service.tar