Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
aaf20ab
refactor(docs): write the manual as MkDocs Markdown
q-soriarty Nov 16, 2026
5cf76fc
feat(docs): generate the navigation of the command reference
q-soriarty Nov 16, 2026
dd25acb
build: add the Qubernetic brand as a submodule
q-soriarty Nov 16, 2026
25e4ad2
feat(docs): build the manual with MkDocs Material and the Qubernetic …
q-soriarty Nov 16, 2026
b929462
chore(docs): remove the Jekyll site
q-soriarty Nov 16, 2026
be09805
test(docs): guard the generated manual and the pages that name commands
q-soriarty Nov 16, 2026
5a242c7
docs: move the installation guides into the site
q-soriarty Nov 16, 2026
91bbdae
docs: write the authentication guide for users
q-soriarty Nov 16, 2026
11e0ff6
docs: add the home page and the quick start
q-soriarty Nov 16, 2026
36b2a13
test(docs): reject a removed subcommand under an existing group
q-soriarty Nov 16, 2026
cd44231
docs: correct the config path and the auth switch description
q-soriarty Nov 16, 2026
39592f2
ci(docs): build with MkDocs and fetch the brand theme with a deploy key
q-soriarty Nov 16, 2026
052c582
test(ci): pin the rules of the docs workflow
q-soriarty Nov 16, 2026
25dcbc9
docs: describe the new documentation site
q-soriarty Nov 16, 2026
6820919
ci(docs): give each ref its own concurrency group
q-soriarty Nov 16, 2026
72a10b5
docs: make the descriptions of the docs build exact
q-soriarty Nov 16, 2026
23a61b8
docs: require the Go version go.mod names
q-soriarty Nov 16, 2026
ac26b23
docs(cmd): break long example lines where they read well
q-soriarty Nov 16, 2026
b537820
docs: keep the site's command lines within the column
q-soriarty Nov 16, 2026
baa0b7b
build: move the brand theme to the footer decisions
q-soriarty Nov 16, 2026
8fef446
fix(docs): escape a flag's default with its usage
q-soriarty Nov 16, 2026
1703ff4
test(docs): check reference links and escaped code in the guard
q-soriarty Nov 16, 2026
adc18ac
ci(docs): trigger on every input of the manual
q-soriarty Nov 16, 2026
4e26a3d
test(ci): tighten the rules of the docs workflow
q-soriarty Nov 16, 2026
2ceb991
docs: show a pr create command that works as written
q-soriarty Nov 16, 2026
3af2ab3
docs: point the Linux package downloads at the releases page
q-soriarty Nov 16, 2026
8625926
build(docs): build locally from the pinned requirements
q-soriarty Nov 16, 2026
b3ba857
build: pin the brand theme to its develop merge
q-soriarty Nov 16, 2026
166a435
Merge remote-tracking branch 'origin/develop' into HEAD
q-soriarty Nov 16, 2026
b6bcd5d
build(docs): skip the brand submodule on recursive clones
q-soriarty Nov 16, 2026
14f327c
ci(docs): install MkDocs Material without apt
q-soriarty Nov 16, 2026
4d11eb2
docs: say which old manual addresses still resolve
q-soriarty Nov 16, 2026
bb6f2d5
build(docs): pin the brand theme to its v0.1.0 release
q-soriarty Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 39 additions & 5 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,31 @@ on:
- "docs/site/**"
- "pkg/cmd/**"
- "internal/docs/**"
- "internal/copiacmd/**"
- "pkg/cmdutil/**"
- "go.mod"
- "go.sum"
- "script/gen-docs.go"
- ".gitmodules"
- ".github/workflows/docs.yml"
workflow_dispatch:

permissions:
contents: read

concurrency:
group: "pages"
group: pages-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-24.04
steps:
# No ssh-key and no submodules here: actions/checkout would fetch this
# repository with the brand deploy key too, which is not valid for it.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
Expand All @@ -31,17 +41,41 @@ jobs:
- name: Generate command docs
run: go run script/gen-docs.go

- name: Build Jekyll site
uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
- name: Read the brand pin
id: brand
run: echo "sha=$(git rev-parse HEAD:docs/site/brand)" >> "$GITHUB_OUTPUT"

- name: Fetch the brand theme
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
source: docs/site
destination: ./_site
repository: qubernetic/brand
ref: ${{ steps.brand.outputs.sha }}
path: docs/site/brand
ssh-key: ${{ secrets.BRAND_DEPLOY_KEY }}
persist-credentials: false

- name: Install MkDocs Material
run: pip3 install --require-hashes -r docs/site/requirements.txt

- name: Build
run: python3 -m mkdocs build --strict -f docs/site/mkdocs.yml -d "$GITHUB_WORKSPACE/_site"

- name: Upload Pages artifact
if: github.ref == 'refs/heads/main'
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: _site

- name: Upload the rehearsal build
if: github.ref != 'refs/heads/main'
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: docs-site
path: _site

deploy:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-24.04
permissions:
pages: write
Expand Down
10 changes: 5 additions & 5 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,10 @@ bin/
dist/
/site/

# Jekyll build artifacts
docs/site/_site/
docs/site/.jekyll-cache/
docs/site/Gemfile.lock
docs/site/manual/copia-cli_*.md
# Docs site: generated pages, navigation and build output
docs/site/docs/manual/copia-cli*.md
docs/site/commands-nav.json
docs/site/site/

# IDE
.idea/
Expand All @@ -31,3 +30,4 @@ coverage.out
unit.junit.xml
AUDIT.md
docs/superpowers/
__pycache__/
4 changes: 4 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[submodule "docs/site/brand"]
path = docs/site/brand
url = https://github.com/qubernetic/brand.git
update = none
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- The manual moved from Jekyll to MkDocs Material with the Qubernetic docs theme, held as the private submodule `docs/site/brand`. The old page addresses (`https://qubernetic.github.io/copia-cli/manual/copia-cli_<command>`) still resolve: GitHub Pages redirects each to the page that now lives at that path with a trailing slash. Old links that end in `.html` (`.../copia-cli_<command>.html`) no longer work. The installation guides moved to the site too (`/install/linux/`, `/install/macos/`, `/install/windows/`, `/install/source/`), and the README links there; `docs/install_*.md` point to them. `docs.yml` builds the site with `mkdocs build --strict` on pushes to `main` and on manual dispatch, fetches the theme with a read-only deploy key in a checkout of its own, and deploys from `main` only; a dispatch from another branch uploads the build as an artifact (#501)
- Every `github/codeql-action` step runs 4.39.3 instead of 4.39.1: `init`, `autobuild` and `analyze` in `codeql.yml` and `upload-sarif` in `govulncheck.yml`, all four on one ref. Dependabot still opened one PR per step (#492 to #495), each failing `TestCodeQLStepsShareOneVersion` and CodeQL, since it reads the `codeql-action` group from `main`, where it arrives with the next release (#497)
- The integration tests `TestNotificationList_Run` and `TestNotificationList_All` ask for one notification instead of 30: app.copia.io takes about two seconds per notification it returns, so the two took 49 s and 24 s (run 42364994440). `TestStatus` stays the slowest test, since `status` itself asks for 50 notifications per page (#449) (#447)
- The integration tests run in a fresh repository instead of the fixed `COPIA_TEST_REPO`, which had collected so many pull requests, issues and notifications that Copia answered slowly (the `Integration tests` step took 22 minutes). The first test of a run creates a private repository `it-run-<base36 unix time>` with an initial commit in the `COPIA_TEST_OWNER` organization, every test works in it and creates the issues and pull requests it needs, and `TestMain` deletes it after the run and fails the run unless the API then answers 404 for it. Before creating it, a run deletes every `it-run-*` repository of the organization older than two hours, left by a run that hit the timeout. Every delete goes through one helper that refuses, without a request, any name that is not `it-run-` and a lowercase base36 time; its unit tests run with `go test ./...`. The repository name is not printed. The `Integration tests` and `Copia version` steps of `ci.yml` and `integration-scheduled.yml` no longer pass `COPIA_TEST_REPO` (#445)
Expand Down
Loading