Consumer quickstart

1.Prerequisites¶

1. Consumer repo has a secret TOOLKIT_READ_TOKEN: a fine-grained GitHub token with Contents: read on OASIS-Docs/publisher-toolkit (or a classic personal access token with the repo scope). The toolkit is private, so the default GITHUB_TOKEN of a sibling repo cannot read it.
2. Consumer repo has .githooks/ (copied from any TC bootstrap) and a .file-metadata file at the repo root.

2.Workflow file layout in the consumer¶

<consumer-tc>/
├── .github/
│   └── workflows/
│       ├── step_1_format_md_and_convert_to_html.yml   <-- from templates/workflow_step_1.yml
│       └── step_2_convert_md_to_html_pdf_final.yml    <-- from templates/workflow_step_2.yml
├── .githooks/
├── .file-metadata
└── <spec>/<ver>/<stage>/<shortname>-<stage>.md

A pinned consumer has no .github/src/ directory. All pipeline code lives in this toolkit and is checked out at workflow time.

3.Pinning the toolkit¶

Both consumer workflows contain:

- name: Checkout publisher-toolkit (pinned)
  uses: actions/checkout@v4
  with:
    repository: OASIS-Docs/publisher-toolkit
    token: ${{ secrets.TOOLKIT_READ_TOKEN }}
    ref: <40-char SHA>
    path: toolkit

The ref: is a full 40-character commit SHA, never a branch name and never a tag name. Tags and branches can move; a commit SHA cannot. Toolkit tags are annotated, so the SHA git ls-remote or the GitHub refs API prints for a tag is the tag object, not the commit: resolve it with git rev-parse vX.Y.Z^{commit}. See upgrading the toolkit pin for the upgrade procedure.

4.Running a chain¶

The commands are the same for every pinned consumer:

gh workflow run step_1_format_md_and_convert_to_html.yml --repo OASIS-Docs/<tc> \
  -f sync_path=<spec>/<ver>/<stage> -f modify_date=YYYY-MM-DD
gh workflow run step_2_convert_md_to_html_pdf_final.yml --repo OASIS-Docs/<tc> \
  -f sync_path=<spec>/<ver>/<stage> -f modify_date=YYYY-MM-DD
gh workflow run step_3_create_zipfile.yml --repo OASIS-Docs/<tc> \
  -f latest_version_path=<spec>/<ver>/<stage> -f modify_date=YYYY-MM-DD
gh workflow run step_4_update_sym_version_links.yml --repo OASIS-Docs/<tc> \
  -f latest_version_path=<spec>/<ver>/<stage>

Steps 3 and 4 do not touch the toolkit; they continue to live entirely in the consumer repo. A pinned consumer may also carry its own go-live workflows: OASIS-Docs/dps has step_5_golive_to_staging.yml and step_6_golive_to_prod.yml, which do not use the toolkit.

5.Bootstrapping a brand-new TC¶

scripts/bootstrap_new_tc.sh <new-tc-shortname> "<description>" <40-char-toolkit-SHA>

That script creates OASIS-Docs/<new-tc> PRIVATE, copies templates/tc_repo_skeleton/, drops in the two workflow templates with the SHA you supplied, and pushes. The skeleton is still a stub (one README), so the script warns and the new repo has an empty .file-metadata but no .githooks/; until the skeleton is filled in, migrating a clone of an existing TC repo is the better starting point.

6.Migrating an existing embedded TC¶

scripts/migrate_tc_to_toolkit.sh <path-to-existing-tc-clone> <40-char-toolkit-SHA>

Deletes .github/src/{step_1,step_2,lint_html,requirements.txt,style.css}, replaces the two workflow files, writes the SHA you supplied into both, and prints git status and git diff --stat for review. It does not commit or push.