Open
Conversation
polyipseity
force-pushed
the
add-docs
branch
4 times, most recently
from
dc4c0cf to
21fa8ee
Compare
Member
Author
|
Fixes #52. |
Member
|
Wow, is it done? I will take a look at it later. |
polyipseity
force-pushed
the
add-docs
branch
from
615ba34 to
9abe148
Compare
Member
|
You might also want to fix the runner selection for this repo. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Key notes | ||
|
|
||
| - Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-latest` but can fall back to `self-hosted` when needed. |
There was a problem hiding this comment.
The documentation states that CI jobs prefer ubuntu-latest, but the actual workflow files (check.yml, docs.yml, docs-publish.yml) use ubuntu-slim as the hosted runner label. Update this line to reference ubuntu-slim to match the actual implementation.
Suggested change
| - Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-latest` but can fall back to `self-hosted` when needed. | |
| - Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-slim` but can fall back to `self-hosted` when needed. |
Comment on lines
+1
to
+7
| name: docs | ||
|
|
||
| on: | ||
| push: | ||
| pull_request: | ||
| workflow_dispatch: | ||
|
|
There was a problem hiding this comment.
Consider adding concurrency control to this workflow (similar to check.yml and docker.yml) to avoid redundant doc builds when multiple commits are pushed to the same PR. This would save CI resources and reduce noise. Example:
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.sha }}
cancel-in-progress: true
Comment on lines
+3
to
+7
| Releases are produced by `googleapis/release-please-action`. The release workflow has been refactored so release steps are defined in `.github/workflows/release-shared-steps.yml` and invoked by a small top-level caller (`.github/workflows/release.yml`) which prefers hosted runners and falls back to `self-hosted` when the top-level try job fails. | ||
|
|
||
| - Trigger: push to `main`. | ||
| - Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`. | ||
| - CI integration: the shared-step workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic. |
There was a problem hiding this comment.
The documentation describes a "shared-step workflow" (release-shared-steps.yml) and a "top-level caller", but the release workflow is actually defined entirely in .github/workflows/release.yml with no separate shared-steps file. Update this section to accurately describe the single release.yml workflow that contains all release steps inline.
Suggested change
| Releases are produced by `googleapis/release-please-action`. The release workflow has been refactored so release steps are defined in `.github/workflows/release-shared-steps.yml` and invoked by a small top-level caller (`.github/workflows/release.yml`) which prefers hosted runners and falls back to `self-hosted` when the top-level try job fails. | |
| - Trigger: push to `main`. | |
| - Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`. | |
| - CI integration: the shared-step workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic. | |
| Releases are produced by `googleapis/release-please-action`, via a single workflow defined in `.github/workflows/release.yml`. This workflow prefers hosted runners and falls back to `self-hosted` when the top-level try job fails. | |
| - Trigger: push to `main`. | |
| - Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`. | |
| - CI integration: the `release.yml` workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic. |
Comment on lines
+7
to
+32
| A `Dockerfile` exists at the repository root. CI image build/publish logic has been extracted into an internal shared-step workflow (`.github/workflows/docker-shared-steps.yml`) and is invoked by a small top-level caller (`.github/workflows/docker.yml`) that prefers hosted runners and falls back to `self-hosted` when the hosted job fails. | ||
|
|
||
| ## Local build & run | ||
|
|
||
| Build the image locally (from repo root): | ||
|
|
||
| ```bash | ||
| # build | ||
| docker build -t template-api:local . | ||
|
|
||
| # run (expose port 3000) | ||
| docker run --rm -p 3000:3000 --env-file .env.example template-api:local | ||
| ``` | ||
|
|
||
| Replace `--env-file .env.example` with your `.env` file or explicit `-e` flags for required environment variables. | ||
|
|
||
| ## CI image publishing | ||
|
|
||
| The repository's `docker.yml` top-level caller invokes the internal shared-step workflow to build and push images to the registry. The shared-step workflow: | ||
|
|
||
| - sets up QEMU and Buildx | ||
| - logs into the registry using the workflow token | ||
| - generates metadata tags (sha, branch/ref, test) | ||
| - builds and pushes the image(s) | ||
|
|
||
| If you need to change the target registry or image name, update the `REGISTRY` and `IMAGE_NAME` environment variables in the shared-step workflow or the top-level caller as appropriate. |
There was a problem hiding this comment.
The documentation describes a "shared-step workflow" (docker-shared-steps.yml) and a "top-level caller", but the docker workflow is actually defined entirely in .github/workflows/docker.yml with no separate shared-steps file. Update this section to accurately describe the single docker.yml workflow that contains all build/push steps inline.
* feat: /metrics route and pinoy-loki logging * feat: testing for /metrics route * feat: add Prometheus config example * chore(gitignore): ignore Prometheus data folder * chore: format * chore: fix lint * fix: simplify metrics and logger init code * fix: test helper --------- Co-authored-by: William So <polyipseity@gmail.com>
Details will be moved under `docs/`.
…nd runner defaults
… docker metadata, release-please behavior
…te README and .gitignore
… cache for docs workflows Use numeric node-version (24) in `.github/workflows/docs.yml` and `.github/workflows/docs-publish.yml` Enable Corepack and run `corepack install` before installing dependencies Split node/cache setup to a dedicated `setup-node` step with `cache: yarn` Reorder and consolidate dependency install steps (Corepack prepare + yarn install --frozen-lockfile) Minor comment formatting fix in `docs-publish.yml`
Grant pages write permission; use yarn install --immutable --immutable-cache instead of corepack prep.
Update README docs-site badge to GitHub Pages URL and minor docs wording fixes. Remove UTF-8 BOM from `.env.example`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Apart from adding docs, this adds a workflow to publish "./docs/api" as GH pages. Might need to set it up.
Fixes #52.