Skip to content

Commit 9dbdb01

Browse files
grahamalamagrahamalama
authored
chore: Add build-and-push reusable workflow docs (#67)
* Add links to Actions docs in top level readme * Add docs for build-and-publish workflow
1 parent f25c3db commit 9dbdb01

File tree

3 files changed

+112
-12
lines changed

3 files changed

+112
-12
lines changed

‎.github/workflows/build-and-push.yml

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,4 @@
1-
# This reusable workflow encapsulates an end to end workflow for building and
2-
# pushing a container image for a MozCloud Service. It:
3-
# - runs a `prebuild_script` to prepare the build environment, e.g. create a `version.json` file in the build context
4-
# - builds the image
5-
# - provides an entrypoint to run a `postbuild_script`, e.g. run a suite of tests
6-
# - pushes the image
7-
#
8-
# For details on the workflow inputs passed to docker-build and docker-push, see the
9-
# documentation for those actions:
10-
#
11-
# https://github.com/mozilla-it/deploy-actions/tree/main/docker-build
12-
# https://github.com/mozilla-it/deploy-actions/tree/main/docker-push
1+
# See `reusable-workflow-docs/build-and-push.md` for usage details
132

143
name: Docker Build and Push
154

‎.github/workflows/docs/build-and-push.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Docker Build and Push Reusable Workflow
2+
3+
This reusable GitHub Actions workflow encapsulates an end-to-end process for building and pushing a
4+
container image for a MozCloud service.
5+
6+
The inputs of this workflow are mostly used to configure [`docker-build`](../docker-build/README.md)
7+
and [`docker-push`](../docker-push/README.md). See their documentation for more details on some of
8+
these inputs.
9+
10+
## Overview
11+
12+
- Runs a `prebuild_script` to prepare the build environment (e.g. generate `version.json`)
13+
- Builds and tags the Docker image using [`docker-build`](../docker-build/README.md)
14+
- Provides an optional hook to run a `postbuild_script` after building (e.g. for running tests)
15+
- Pushes the image to GCP Artifact Registry (and optionally GitHub Container Registry) using [docker-push](../docker-push/README.md)
16+
17+
18+
## Inputs
19+
20+
| Name | Required | Type | Description |
21+
| --------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
22+
| `image_name` | true | string | The name of the Docker image to build. |
23+
| `gar_name` | true | string | Name of the GAR repository. (typically `<tenant>-prod`) |
24+
| `project_id` | true | string | GCP project ID where the Artifact Registry is located. (typically `moz-fx-<tenant>-prod`) |
25+
| `workload_identity_pool_project_number` | false | string | GCP workload identity pool project number. (default: `${{ vars.GCPV2_WORKLOAD_IDENTITY_POOL_PROJECT_NUMBER }}`) |
26+
| `prebuild_script` | false | string | Shell script (either inline or path to script) to run before building the image. (default: *see below)* |
27+
| `postbuild_script` | false | string | Shell script (either inline or path to script) to run after building the image. |
28+
| `image_build_context` | false | string | Build context path. (default: `"./"`) |
29+
| `image_tag_metadata` | false | string | Additional metadata for image tagging. |
30+
| `should_tag_ghcr` | false | boolean | Whether to also tag and push the image to GHCR. (default: `false`) |
31+
| `should_tag_latest` | false | boolean | Whether to tag the image as `latest`. (default: `false`) |
32+
| `gar_location` | false | string | Artifact Registry location. (default: `"us"`) |
33+
| `service_account_name` | false | string | GCP service account for pushing to registry. (default: `"artifact-writer"`) |
34+
35+
### Default `prebuild_script`
36+
37+
```bash
38+
IMAGE_BUILD_CONTEXT_ABSPATH=$(realpath "$IMAGE_BUILD_CONTEXT")
39+
40+
printf '{"commit":"%s","version":"%s","source":"%s","build":"%s"}\n' \
41+
"$GITHUB_SHA" \
42+
"$GITHUB_REF_NAME" \
43+
"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \
44+
"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" > "$IMAGE_BUILD_CONTEXT_ABSPATH/version.json"
45+
```
46+
47+
This script generates a `version.json` file with commit, version, and build metadata.
48+
49+
## Permissions
50+
51+
- `contents: read` (required)
52+
- `id-token: write` (required: for GCP authentication)
53+
- `packages: write` (optional: for GHCR publishing)
54+
55+
## Usage
56+
57+
### Minimal configuration
58+
```yaml
59+
on:
60+
push:
61+
branches:
62+
- main
63+
tags:
64+
- v20[0-9][0-9].[01][0-9].[0-3][0-9] # e.g. v2023.12.04
65+
- v20[0-9][0-9].[01][0-9].[0-3][0-9]-[0-9] # e.g. v2023.12.04-2
66+
67+
jobs:
68+
build-and-push:
69+
secrets: inherit
70+
permissions:
71+
contents: read
72+
id-token: write
73+
uses: mozilla-it/deploy-actions/.github/workflows/docker-build-and-push.yml@main
74+
with:
75+
image_name: your-service
76+
gar_name: your-tenant-prod
77+
project_id: moz-fx-you-tenant-prod
78+
```
79+
80+
### Push to GHCR
81+
```yaml
82+
on:
83+
push:
84+
branches:
85+
- main
86+
tags:
87+
- v20[0-9][0-9].[01][0-9].[0-3][0-9] # e.g. v2023.12.04
88+
- v20[0-9][0-9].[01][0-9].[0-3][0-9]-[0-9] # e.g. v2023.12.04-2
89+
90+
jobs:
91+
build:
92+
secrets: inherit
93+
permissions:
94+
contents: read
95+
id-token: write
96+
packages: write
97+
uses: mozilla-it/deploy-actions/.github/workflows/docker-build-and-push.yml@main
98+
with:
99+
image_name: your-service
100+
gar_name: your-tenant-prod
101+
project_id: moz-fx-you-tenant-prod
102+
should_tag_ghcr: true
103+
```

‎README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
This repository contains GitHub Actions Composite Actions used for Deployment Automation.
44

5+
## Actions
6+
* [`docker-build`](./docker-build/README.md)
7+
* [`docker-push`](./docker-push//README.md)
8+
9+
## Workflows
10+
* [build-and-push](./.github/workflows/docs/build-and-push.md)
11+
12+
513
## Releases & Tags
614

715
Releases follow semantic versioning. Tags additionally provide "generic" versions (e.g. `v2`, `v3`) to allow specifying "moving" pointers in github actions (e.g. `mozilla-it/deploy-actions/slack@v3`.

0 commit comments

Comments
 (0)