Skip to content

Commit fb0af17

Browse files
epam-avramenkoepam-avramenko
committed
RANCHER-3066. Update feature-build documentation: change workflow reference to application-update.yml and clarify commit hash usage
1 parent d8fa04c commit fb0af17

2 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎.github/docs/feature-build.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Feature Build
2+
3+
**Workflow**: `feature-build.yml` (per app repo, from `folio-app-template`)
4+
**Purpose**: Build an application descriptor from a feature branch that includes custom modules built outside the standard registries, without publishing to FAR
5+
**Type**: `workflow_dispatch` wrapper around `application-update.yml`
6+
7+
## Overview
8+
9+
A feature build resolves an application descriptor for a feature branch whose template references
10+
**custom modules** — modules built from their own feature branches, whose descriptors are published
11+
to a private S3 bucket rather than to the FOLIO registry, and whose Docker images live outside
12+
Docker Hub. It:
13+
14+
- resolves those custom module descriptors from an **S3 fallback registry**,
15+
- skips artifact validation for **only** the fallback-resolved modules (primary modules are still
16+
validated against Docker Hub / npm as usual),
17+
- does **not** publish the descriptor to FAR,
18+
- commits `application.lock.json` back to the feature branch,
19+
- versions the app with the feature branch's **commit hash** (`X.Y.Z-SNAPSHOT.<shortSha>`) instead
20+
of a build number, so a feature app is distinguishable from a snapshot app in FAR.
21+
22+
All build configuration lives in the feature branch's `pom.xml`. The workflow itself takes no
23+
registry parameters — it only names the branch and the validation switches.
24+
25+
## Configure the feature branch `pom.xml`
26+
27+
Two coupled edits in the `folio-application-generator` plugin section of the app repo's feature
28+
branch:
29+
30+
```xml
31+
<properties>
32+
<!-- Must be a generator version that supports fallbackModuleRegistries / validateFallbackArtifacts -->
33+
<folio-application-generator.version>1.5.0-SNAPSHOT</folio-application-generator.version>
34+
</properties>
35+
...
36+
<configuration>
37+
<templatePath>${templatePath}</templatePath>
38+
39+
<moduleRegistries>
40+
<registry>
41+
<type>okapi</type>
42+
<url>https://folio-registry.dev.folio.org</url>
43+
</registry>
44+
</moduleRegistries>
45+
46+
<!-- Searched only when a module is not found in moduleRegistries above -->
47+
<fallbackModuleRegistries>
48+
<registry>
49+
<type>s3</type>
50+
<bucket>eureka-custom-registry</bucket>
51+
<path>descriptors</path>
52+
</registry>
53+
</fallbackModuleRegistries>
54+
55+
<!-- Custom modules' images are not in Docker Hub, so skip artifact validation for them -->
56+
<validateFallbackArtifacts>false</validateFallbackArtifacts>
57+
58+
<awsRegion>us-east-1</awsRegion>
59+
</configuration>
60+
```
61+
62+
Notes:
63+
64+
- **The version bump is required.** Older generator versions (the app poms pin `1.3.0` / `1.4.0`)
65+
have no fallback-registry support at all. Maven does not fail on `<configuration>` elements a
66+
plugin does not recognize — it warns and ignores them — so on an old version the
67+
`<fallbackModuleRegistries>` / `<validateFallbackArtifacts>` elements are silently dropped and no
68+
custom module is ever resolved from S3. Bump `folio-application-generator.version` to a version
69+
that supports these elements (`1.5.1-SNAPSHOT` or later).
70+
- **Do not set `<validateArtifacts>false</validateArtifacts>`.** Primary-resolved modules must keep
71+
their Docker Hub / npm validation. `validateFallbackArtifacts=false` narrows validation to exclude
72+
only the fallback-resolved custom modules; it does not disable validation.
73+
- `fallbackModuleRegistries` accepts the same registry types as `moduleRegistries`: `s3`, `okapi`,
74+
`simple`. The S3 registry needs `bucket` and `path`; the region comes from `awsRegion`, not from
75+
the registry entry.
76+
- Keep this configuration on the feature branch only. A `-SNAPSHOT` generator pin and a custom
77+
fallback registry must never be merged into `master` or a release branch.
78+
79+
## Run the build
80+
81+
Dispatch **Feature Build** on the app repo, from the Actions tab or the CLI:
82+
83+
```shell
84+
gh workflow run feature-build.yml --repo folio-org/app-<name> \
85+
-f branch=<feature-branch> \
86+
-f dry_run=true
87+
```
88+
89+
### Inputs
90+
91+
| Input | Description | Required | Type | Default |
92+
|------------------------------|----------------------------------------------------------------|----------|---------|-----------|
93+
| `branch` | Feature branch to build the descriptor from | Yes | string | - |
94+
| `commit_hash` | Commit hash used as the descriptor build suffix (empty = auto-detect from the branch HEAD) | No | string | `''` |
95+
| `skip_interface_validation` | Skip module interface integrity validation | No | boolean | `false` |
96+
| `skip_dependency_validation` | Dependency validation: `false` / `true` / `bypass` | No | choice | `false` |
97+
| `dry_run` | Build without committing the lock file to the branch | No | boolean | `false` |
98+
99+
A `resolve-build-number` job runs first: it uses `commit_hash` when supplied, otherwise reads the
100+
branch HEAD short SHA (`gh api repos/<repo>/commits/<branch> --jq '.sha[0:7]'`). The resolved value
101+
is passed as `build_number` and becomes the version suffix (`X.Y.Z-SNAPSHOT.<shortSha>`).
102+
103+
The wrapper calls `application-update.yml` with fixed values that make a feature build correct:
104+
`need_pr: false` (commit straight to the feature branch), `publish: false` (never reaches FAR), and
105+
`rely_on_FAR: true` (a feature branch has no matching branch in `platform-lsp`, so dependency
106+
validation resolves against FAR instead of a platform descriptor). Routing through the orchestrator
107+
(`application-update.yml`) rather than the flow directly also produces the run summary and the Slack
108+
notification.
109+
110+
## Related documentation
111+
112+
- [All repository workflows](workflows.md) — overview of the four workflows this repo ships
113+
- [Application Update](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/application-update.md) — the orchestrator this wraps (adds the summary + notification)
114+
- [Application Update Flow](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/application-update-flow.md) — the underlying flow the orchestrator runs

‎.github/docs/workflows.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Application Repository Workflows
2+
3+
Every `app-*` repository ships four workflows, generated from `folio-app-template`. Each is a thin
4+
wrapper that calls a reusable workflow in
5+
[`kitfox-github`](https://github.com/folio-org/kitfox-github) with `secrets: inherit`; the wrapper
6+
holds only the trigger and the app-specific inputs, while the reusable workflow holds the logic.
7+
8+
| Workflow | Trigger | Calls (kitfox-github) | Purpose |
9+
|---|---|---|---|
10+
| [Application Update Scheduler](#application-update-scheduler) | schedule + manual | `application-update.yml` | Keep module versions current on configured branches |
11+
| [Feature Build](#feature-build) | manual | `application-update.yml` | Build a descriptor from a feature branch with custom modules |
12+
| [Release Application Version](#release-application-version) | manual | `release-application-version-flow.yml` | Create a GitHub Release (tag + descriptor asset) |
13+
| [Release Preparation](#release-preparation) | manual | `release-preparation.yml` | Cut a new release branch from a previous one |
14+
15+
All four resolve the reusable workflow at `@master`, so behavior tracks the latest `kitfox-github`
16+
without changing the app repo.
17+
18+
---
19+
20+
## Application Update Scheduler
21+
22+
**File**: `.github/workflows/update-scheduler.yml`
23+
**Trigger**: `schedule` (every 20 minutes) and `workflow_dispatch`
24+
25+
The automation that keeps applications up to date. It reads `.github/update-config.yml` via the
26+
`get-update-config` action, builds a matrix of enabled branches, and runs `application-update.yml`
27+
for each. Which branches are scanned, whether each uses a PR or a direct commit, and all other
28+
per-branch policy come entirely from `update-config.yml` — not from this workflow.
29+
30+
| Dispatch input | Description | Default |
31+
|---|---|---|
32+
| `dry_run` | Run without creating PRs or committing changes | `false` |
33+
34+
This is the only workflow of the four that runs on its own. The rest are manual.
35+
36+
- Configure it: [update-config.yml schema](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/update-config.md)
37+
- What it runs: [Application Update](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/application-update.md)
38+
39+
## Feature Build
40+
41+
**File**: `.github/workflows/feature-build.yml`
42+
**Trigger**: `workflow_dispatch`
43+
44+
Builds an application descriptor from a **feature branch** whose template references custom modules
45+
built outside the standard registries. It resolves those modules from an S3 fallback registry, skips
46+
artifact validation for only those modules, does not publish to FAR, and commits
47+
`application.lock.json` back to the feature branch. Registry configuration lives in the feature
48+
branch's `pom.xml`; this workflow only names the branch and the validation switches.
49+
50+
| Dispatch input | Description | Default |
51+
|---|---|---|
52+
| `branch` | Feature branch to build from (**required**) | - |
53+
| `commit_hash` | Commit hash used as the version suffix (empty = auto-detect from branch HEAD) | `''` |
54+
| `skip_interface_validation` | Skip module interface integrity validation | `false` |
55+
| `skip_dependency_validation` | `false` / `true` / `bypass` | `false` |
56+
| `dry_run` | Build without committing the lock file | `false` |
57+
58+
The wrapper fixes `need_pr: false`, `publish: false`, and `rely_on_FAR: true` — the combination that
59+
makes a feature build correct (see the flow doc for why) — and versions the app with the feature
60+
branch's commit hash (`X.Y.Z-SNAPSHOT.<shortSha>`). It routes through the orchestrator
61+
`application-update.yml`, so the run also gets a summary and a Slack notification.
62+
63+
- Full pom pattern + details: [Feature Build](feature-build.md)
64+
- What it runs: [Application Update](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/application-update.md)
65+
66+
## Release Application Version
67+
68+
**File**: `.github/workflows/release-application-version.yml`
69+
**Trigger**: `workflow_dispatch`
70+
71+
Tags a commit with the application version, creates a GitHub Release, and attaches
72+
`application-descriptor.json` as a release asset. Normally invoked automatically after a successful
73+
FAR publish (`post-merge-flow.yml`); this manual wrapper exists for re-running or ad-hoc releases.
74+
75+
| Dispatch input | Description | Default |
76+
|---|---|---|
77+
| `commit_sha` | Commit to release (empty = branch HEAD) | `''` |
78+
| `base_branch` | Release branch the commit belongs to (empty = dispatch branch) | `''` |
79+
| `release_notes` | Release notes body text | `''` |
80+
| `dry_run` | Simulate without creating a tag/release | `false` |
81+
82+
- What it runs: [Release Application Version Flow](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/release-application-version-flow.md)
83+
84+
## Release Preparation
85+
86+
**File**: `.github/workflows/release-preparation.yml`
87+
**Trigger**: `workflow_dispatch`
88+
89+
Creates a new release branch (e.g. `R2-2024`) seeded from a previous release branch, pinning module
90+
versions for the new release line. Typically run by the Kitfox team during release cutover.
91+
92+
| Dispatch input | Description | Default |
93+
|---|---|---|
94+
| `previous_release_branch` | Previous release branch, e.g. `R1-2024` (**required**) | - |
95+
| `new_release_branch` | New release branch, e.g. `R2-2024` (**required**) | - |
96+
| `use_snapshot_fallback` | Fall back to `snapshot` if the previous branch is missing | `false` |
97+
| `use_snapshot_version` | Use the snapshot version as the base | `false` |
98+
| `need_pr` | Require a PR for version updates on the new branch | `true` |
99+
| `prerelease_mode` | Module constraints: `false` / `true` / `only` | `'false'` |
100+
| `dry_run` | Run without making changes | `false` |
101+
| `dispatch_id` | Optional identifier for run tracking | `''` |
102+
103+
- What it runs: [Release Preparation Flow](https://github.com/folio-org/kitfox-github/blob/master/.github/docs/release-preparation-flow.md)
104+
105+
---
106+
107+
## Conventions shared by all wrappers
108+
109+
- **`app_name` / `repo`** are derived from the repository (`github.event.repository.name`,
110+
`github.repository`) — never hardcoded.
111+
- **`secrets: inherit`** passes org/repo secrets through to the reusable workflow; the wrappers
112+
declare no secrets of their own.
113+
- **`@master` pin** on the `kitfox-github` reusable workflow.
114+
- **`dry_run`** is available on every manual workflow and performs no destructive action (no commit,
115+
push, PR, tag, or FAR publish).
116+
117+
For setup of a new repository generated from this template, see [SETUP.md](../../SETUP.md).

0 commit comments

Comments
 (0)