cicd

name	cicd
description	Use when touching .github/workflows/, release config (.releaserc*), mkdocs.yml, docs deploy, or the whats-new generator. Covers branch-to-release-channel mapping, semantic-release, docs deploy gating, and the agentic whats-new flow.

CI/CD in pytrendy

Workflows

File	Purpose
test.yaml	Core tests → non-core (--cov-append) → Codecov. Runs on push to main/develop + PRs.
release.yaml	Core tests → semantic-release → build & publish to PyPI. Runs on push to main/develop.
docs.yaml	Build + deploy docs to GitHub Pages (gh-pages branch, per-subdirectory). main/develop.
docs-preview.yaml	Per-PR docs preview at russellsb.github.io/pytrendy/pr-<N>/.
whats-new.yaml	Agentic: generates docs/whats-new.md entry via OpenCode CLI, opens PR back.
check-base-branch.yml	Fails PRs not targeting develop (with documented exceptions).
lint-pr-title.yml	Enforces Conventional Commits on PR titles.
codeql.yml	GitHub code scanning.

Branch → release channel

• main → stable. .releaserc config; branches: ["main"]; publishes to PyPI as 1.x.x.
• develop → prerelease dev channel. Release workflow does cp .releaserc.dev.json .releaserc before running; branches includes { "name": "develop", "prerelease": "dev", "channel": "dev" }; publishes as 1.x.x.devN (the prepareCmd rewrites -dev. → .dev for PEP 440 compliance).

Version source of truth = semantic-release output, applied via poetry version ${nextRelease.version}. Never hand-edit pyproject.toml's version — it desyncs the next release.

Release flow (release.yaml)

1. test-core job: pytest tests/ -m core.
2. semantic-release: conventional-commits analyzer → bumps version → poetry version → commits CHANGELOG.md + pyproject.toml (main) or just pyproject.toml (develop) with chore(release): <ver> [skip ci]. Uses SSH deploy key (RELEASE_SSH_KEY).
3. build-and-publish: only if released == 'true' (or force_publish dispatch). poetry build → PyPI via OIDC trusted publishing (id-token: write, environment: release).

Docs deploy gating (docs.yaml)

The check-should-deploy job decides whether to build:

• Skip if any commit message contains [skip docs].
• Deploy if any commit matches ^(feat|fix|docs|refactor|perf)(\([^)]*\))?!?: (semantic types).
• Deploy if any commit subject has ! (breaking) or body has BREAKING CHANGE.
• Else diff files: deploy if changes touch docs/, mkdocs.yml, or pytrendy/.

Deploy writes to gh-pages under a per-branch subdirectory (main/, develop/) with keep_files: true so branches don't clobber each other. On main, also writes a root index.html redirecting to main/. The offline mkdocs plugin is stripped via sed for online deploys; site_url is injected per-branch.

GitHub Pages setup is a one-time manual step (Settings → Pages → gh-pages / root) — noted in docs.yaml header comment.

Docs preview (docs-preview.yaml)

Triggers on PR open/sync/reopen/close touching docs/**, mkdocs.yml, or pytrendy/**. Skips fork PRs (no gh-pages write access). Bot comments URL with stable marker <!-- docs-preview-bot --> (updates existing comment rather than duplicating). On PR close, removes pr-<N>/ from gh-pages and updates the comment.

What's New generator (whats-new.yaml) — agentic

Triggers: on release publish, on Release workflow completion (main/develop), or manual dispatch.

1. Resolves release metadata (tag, name, body, prerelease flag, branch) from the event payload, falling back to the GitHub Releases API by tag, then CHANGELOG.md.
2. Checks out the release branch, installs the OpenCode CLI (see whats-new.yaml for the exact install step).
3. Runs python scripts/generate_whats_new.py with OPENCODE_MODEL (default opencode-go/deepseek-v4-flash) and a deny-all permission block (bash/edit/webfetch/websearch/external_directory/task all deny) — the agent can only read and write the whats-new file via the script.
4. The script prepends a user-friendly entry into docs/whats-new.md between sentinel comments <!-- WHATS_NEW_CONTENT_START --> / <!-- WHATS_NEW_CONTENT_END -->. Don't edit content inside those markers by hand — it gets regenerated.
5. Opens a PR (docs/whats-new-<tag>) back to the release branch via peter-evans/create-pull-request@v7 using DOCS_PREVIEW_PAT. The PR's base is the release branch (develop or main) — these are the only PRs allowed to target main from a non-develop head (check-base-branch.yml whitelists docs/whats-new-*).
6. On stable releases (main, not prerelease), a sync-to-develop job re-generates the entry framed as stable and opens a follow-up PR to develop so both branches stay consistent.

Script-level agent instructions are in scripts/generate_whats_new.py docstring: verify CSV URLs resolve (use develop-branch raw URLs for pre-releases, main for stable), derive before/after plot scenarios from tests/tests_crashes_edgecases/ not synthetic data, and keep figsize/grid/legend/colors identical between before/after images by routing through the same detect_trends() + plot_pytrendy() pipeline.

For manual before/after plot generation in PR bodies (fix/feature PRs), see the pr-plots skill.

Secrets the workflows expect

CODECOV_TOKEN, RELEASE_SSH_KEY, OPENCODE_API_KEY, DOCS_PREVIEW_PAT, plus GITHUB_TOKEN. OPENCODE_MODEL is a repo variable (vars context), not a secret. PyPI publish uses OIDC trusted publishing (no token).

OpenCode App installation scopes

The OpenCode GitHub App (opencode-agent) requires specific repository permissions for commits, issues, and PRs. Verify in GitHub Settings → Integrations → OpenCode App → Installations:

• Contents: read/write (for commits)
• Issues: read/write (for creating and commenting on issues)
• Pull requests: read/write (for creating and commenting on PRs)

Fallback (user awareness only — do not attempt to apply): If App scopes cannot be fixed, the user can set use_github_token: true in .github/workflows/opencode.yml (backed by the widened workflow permissions: block). This requires changes to the workflow on main, so the agent should not attempt to work around it.