| Message ID | 20260506155442.1566744-3-stefan.klug@ideasonboard.com |
|---|---|
| State | New |
| Headers | show |
| Series |
|
| Related | show |
Hi 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > Add a build step that deploys the docs to docs.libcamera.org. This step > only runs on pushes to master and on tag builds. It requires two > external variables: > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > --- > .gitlab-ci/setup-container.sh | 2 ++ > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > 2 files changed, 36 insertions(+), 1 deletion(-) > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > index c7ca6426c3ab..6c4b439b887b 100755 > --- a/.gitlab-ci/setup-container.sh > +++ b/.gitlab-ci/setup-container.sh > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > python3-sphinxcontrib.doxylink > texlive-latex-extra > ) > + # Packages required to deploy the documentation > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > # Tools requires by the lint jobs. > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > # libclang-rt-dev for the clang ASan runtime. > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > index 468f5769eb87..9bbceae38a27 100644 > --- a/gitlab-ci.yml > +++ b/gitlab-ci.yml > @@ -5,6 +5,7 @@ stages: > - build > - lint > - test > + - deploy > > variables: > FDO_UPSTREAM_REPO: 'camera/libcamera' > @@ -74,7 +75,7 @@ include: > .libcamera-ci.debian:13: > variables: > FDO_DISTRIBUTION_VERSION: 'trixie' > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > .container-debian: > extends: > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > artifacts: > reports: > junit: build/lc-compliance-report.xml > + > +# ------------------------------------------------------------------------------ > +# Deploy stage - deploy docs if we are building master or a tag > +# ------------------------------------------------------------------------------ > + > +deploy-docs: > + extends: > + - .fdo.distribution-image@debian > + - .libcamera-ci.debian:13 > + - .libcamera-ci.scripts > + rules: > + - if: $CI_COMMIT_BRANCH == "master" - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ? > + - if: $CI_COMMIT_TAG - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ or something similar (possibly accepting some kind of suffix)? > + environment: deploy > + stage: deploy I think `deploy` could (should?) be added to the top-level `stages` list for the sake of completeness. > + needs: > + - job: build-docs > + script: > + - | > + mkdir -p ~/.ssh > + chmod 700 ~/.ssh > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > + chmod 600 ~/.ssh/id_ed25519 > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts > + > + - | > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > + --exclude .doctrees \ > + --exclude .buildinfo \ > + --exclude objects.inv \ > + build/docs/ \ > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME I like to hide the user and the host name in separate protected ci variables, but I guess it does not matter that much in the end. Have you considered using `$CI_COMMIT_REF_SLUG` ? Regards, Barnabás Pőcze
On Wed, May 06, 2026 at 06:28:20PM +0200, Barnabás Pőcze wrote: > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > Add a build step that deploys the docs to docs.libcamera.org. This step > > only runs on pushes to master and on tag builds. It requires two > > external variables: > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > --- > > .gitlab-ci/setup-container.sh | 2 ++ > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > index c7ca6426c3ab..6c4b439b887b 100755 > > --- a/.gitlab-ci/setup-container.sh > > +++ b/.gitlab-ci/setup-container.sh > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > python3-sphinxcontrib.doxylink > > texlive-latex-extra > > ) > > + # Packages required to deploy the documentation > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > # Tools requires by the lint jobs. > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > # libclang-rt-dev for the clang ASan runtime. > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > index 468f5769eb87..9bbceae38a27 100644 > > --- a/gitlab-ci.yml > > +++ b/gitlab-ci.yml > > @@ -5,6 +5,7 @@ stages: > > - build > > - lint > > - test > > + - deploy > > > > variables: > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > @@ -74,7 +75,7 @@ include: > > .libcamera-ci.debian:13: > > variables: > > FDO_DISTRIBUTION_VERSION: 'trixie' > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > .container-debian: > > extends: > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > artifacts: > > reports: > > junit: build/lc-compliance-report.xml > > + > > +# ------------------------------------------------------------------------------ > > +# Deploy stage - deploy docs if we are building master or a tag > > +# ------------------------------------------------------------------------------ > > + > > +deploy-docs: > > + extends: > > + - .fdo.distribution-image@debian > > + - .libcamera-ci.debian:13 > > + - .libcamera-ci.scripts > > + rules: > > + - if: $CI_COMMIT_BRANCH == "master" > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > ? > > > + - if: $CI_COMMIT_TAG Should we keep this one disabled until we reach v1.0 ? > - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ > > or something similar (possibly accepting some kind of suffix)? > > > + environment: deploy > > + stage: deploy > > I think `deploy` could (should?) be added to the top-level `stages` list > for the sake of completeness. All good comments. > > + needs: > > + - job: build-docs > > + script: > > + - | > > + mkdir -p ~/.ssh > > + chmod 700 ~/.ssh > > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > > + chmod 600 ~/.ssh/id_ed25519 > > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts I wonder if there's a particular reason to depart from https://docs.gitlab.com/ci/jobs/ssh_keys/#ssh-keys-when-using-the-docker-executor, which uses a file variable, and ssh-agent to avoid having to copy the private key to ~/.ssh/. > > + > > + - | > > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > > + --exclude .doctrees \ > > + --exclude .buildinfo \ > > + --exclude objects.inv \ > > + build/docs/ \ > > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME Could all of this be moved to a script ? > I like to hide the user and the host name in separate protected ci variables, > but I guess it does not matter that much in the end. Possibly still a good practice though. > Have you considered using `$CI_COMMIT_REF_SLUG` ?
Quoting Laurent Pinchart (2026-05-06 19:15:12) > On Wed, May 06, 2026 at 06:28:20PM +0200, Barnabás Pőcze wrote: > > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > > Add a build step that deploys the docs to docs.libcamera.org. This step > > > only runs on pushes to master and on tag builds. It requires two > > > external variables: > > > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > > --- > > > .gitlab-ci/setup-container.sh | 2 ++ > > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > > index c7ca6426c3ab..6c4b439b887b 100755 > > > --- a/.gitlab-ci/setup-container.sh > > > +++ b/.gitlab-ci/setup-container.sh > > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > > python3-sphinxcontrib.doxylink > > > texlive-latex-extra > > > ) > > > + # Packages required to deploy the documentation > > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > > # Tools requires by the lint jobs. > > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > > # libclang-rt-dev for the clang ASan runtime. > > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > > index 468f5769eb87..9bbceae38a27 100644 > > > --- a/gitlab-ci.yml > > > +++ b/gitlab-ci.yml > > > @@ -5,6 +5,7 @@ stages: > > > - build > > > - lint > > > - test > > > + - deploy > > > > > > variables: > > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > > @@ -74,7 +75,7 @@ include: > > > .libcamera-ci.debian:13: > > > variables: > > > FDO_DISTRIBUTION_VERSION: 'trixie' > > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > > > .container-debian: > > > extends: > > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > > artifacts: > > > reports: > > > junit: build/lc-compliance-report.xml > > > + > > > +# ------------------------------------------------------------------------------ > > > +# Deploy stage - deploy docs if we are building master or a tag > > > +# ------------------------------------------------------------------------------ > > > + > > > +deploy-docs: > > > + extends: > > > + - .fdo.distribution-image@debian > > > + - .libcamera-ci.debian:13 > > > + - .libcamera-ci.scripts > > > + rules: > > > + - if: $CI_COMMIT_BRANCH == "master" > > > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > > > ? > > > > > + - if: $CI_COMMIT_TAG > > Should we keep this one disabled until we reach v1.0 ? Not unless you have a date in mind for 1.0 :-) I think we already have different versions in use in different distributions, and working towards keeping versioned documentation on the website will seamlessly support those existing releases. -- Kieran
Hi Barnabás, Thank you for the review. Quoting Barnabás Pőcze (2026-05-06 18:28:20) > Hi > > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > Add a build step that deploys the docs to docs.libcamera.org. This step > > only runs on pushes to master and on tag builds. It requires two > > external variables: > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > --- > > .gitlab-ci/setup-container.sh | 2 ++ > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > index c7ca6426c3ab..6c4b439b887b 100755 > > --- a/.gitlab-ci/setup-container.sh > > +++ b/.gitlab-ci/setup-container.sh > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > python3-sphinxcontrib.doxylink > > texlive-latex-extra > > ) > > + # Packages required to deploy the documentation > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > # Tools requires by the lint jobs. > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > # libclang-rt-dev for the clang ASan runtime. > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > index 468f5769eb87..9bbceae38a27 100644 > > --- a/gitlab-ci.yml > > +++ b/gitlab-ci.yml > > @@ -5,6 +5,7 @@ stages: > > - build > > - lint > > - test > > + - deploy > > > > variables: > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > @@ -74,7 +75,7 @@ include: > > .libcamera-ci.debian:13: > > variables: > > FDO_DISTRIBUTION_VERSION: 'trixie' > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > .container-debian: > > extends: > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > artifacts: > > reports: > > junit: build/lc-compliance-report.xml > > + > > +# ------------------------------------------------------------------------------ > > +# Deploy stage - deploy docs if we are building master or a tag > > +# ------------------------------------------------------------------------------ > > + > > +deploy-docs: > > + extends: > > + - .fdo.distribution-image@debian > > + - .libcamera-ci.debian:13 > > + - .libcamera-ci.scripts > > + rules: > > + - if: $CI_COMMIT_BRANCH == "master" > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH Yes, I don't mind doing that. > > ? > > > > + - if: $CI_COMMIT_TAG > > - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ > > or something similar (possibly accepting some kind of suffix)? I'm wondering what we gain by that? Do you want to guard against upcoming tags where we don't want documentation for? The next person reading this would need to spend additional brain cycles decoding the regexp, then wondering what it was meant for, then checking the tags to see what the reason might have been, then realizing that it matches all tags in the repo... On the other hand it might make the intent clearer. I don't have a strong preference. > > > > + environment: deploy > > + stage: deploy > > I think `deploy` could (should?) be added to the top-level `stages` list > for the sake of completeness. deploy is added to the stages list at the beginning of this patch. Do you mean somewhere else? > > > > + needs: > > + - job: build-docs > > + script: > > + - | > > + mkdir -p ~/.ssh > > + chmod 700 ~/.ssh > > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > > + chmod 600 ~/.ssh/id_ed25519 > > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts > > + > > + - | > > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > > + --exclude .doctrees \ > > + --exclude .buildinfo \ > > + --exclude objects.inv \ > > + build/docs/ \ > > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME > > I like to hide the user and the host name in separate protected ci variables, > but I guess it does not matter that much in the end. I think the less variables we require, the better. Is user & host really that sensitive? > > Have you considered using `$CI_COMMIT_REF_SLUG` ? That is a great hint. I wasn't aware of that one. Thanks, Stefan > > > Regards, > Barnabás Pőcze
2026. 05. 07. 9:23 keltezéssel, Stefan Klug írta: > Hi Barnabás, > > Thank you for the review. > > Quoting Barnabás Pőcze (2026-05-06 18:28:20) >> Hi >> >> 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: >>> Add a build step that deploys the docs to docs.libcamera.org. This step >>> only runs on pushes to master and on tag builds. It requires two >>> external variables: >>> >>> DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key >>> DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org >>> >>> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> >>> --- >>> .gitlab-ci/setup-container.sh | 2 ++ >>> gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- >>> 2 files changed, 36 insertions(+), 1 deletion(-) >>> >>> diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh >>> index c7ca6426c3ab..6c4b439b887b 100755 >>> --- a/.gitlab-ci/setup-container.sh >>> +++ b/.gitlab-ci/setup-container.sh >>> @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in >>> python3-sphinxcontrib.doxylink >>> texlive-latex-extra >>> ) >>> + # Packages required to deploy the documentation >>> + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) >>> # Tools requires by the lint jobs. >>> PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) >>> # libclang-rt-dev for the clang ASan runtime. >>> diff --git a/gitlab-ci.yml b/gitlab-ci.yml >>> index 468f5769eb87..9bbceae38a27 100644 >>> --- a/gitlab-ci.yml >>> +++ b/gitlab-ci.yml >>> @@ -5,6 +5,7 @@ stages: >>> - build >>> - lint >>> - test >>> + - deploy >>> >>> variables: >>> FDO_UPSTREAM_REPO: 'camera/libcamera' >>> @@ -74,7 +75,7 @@ include: >>> .libcamera-ci.debian:13: >>> variables: >>> FDO_DISTRIBUTION_VERSION: 'trixie' >>> - FDO_DISTRIBUTION_TAG: '2026-04-24.0' >>> + FDO_DISTRIBUTION_TAG: '2026-05-06.0' >>> >>> .container-debian: >>> extends: >>> @@ -437,3 +438,35 @@ test-lc-compliance:virtual: >>> artifacts: >>> reports: >>> junit: build/lc-compliance-report.xml >>> + >>> +# ------------------------------------------------------------------------------ >>> +# Deploy stage - deploy docs if we are building master or a tag >>> +# ------------------------------------------------------------------------------ >>> + >>> +deploy-docs: >>> + extends: >>> + - .fdo.distribution-image@debian >>> + - .libcamera-ci.debian:13 >>> + - .libcamera-ci.scripts >>> + rules: >>> + - if: $CI_COMMIT_BRANCH == "master" >> >> - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > Yes, I don't mind doing that. > >> >> ? >> >> >>> + - if: $CI_COMMIT_TAG >> >> - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ >> >> or something similar (possibly accepting some kind of suffix)? > > I'm wondering what we gain by that? Do you want to guard against upcoming > tags where we don't want documentation for? The next person reading this > would need to spend additional brain cycles decoding the regexp, then > wondering what it was meant for, then checking the tags to see what the > reason might have been, then realizing that it matches all tags in the > repo... On the other hand it might make the intent clearer. I don't have > a strong preference. Constraining the documentation to "version tags" seems like a reasonable thing to me. But yes, you're right that there are no tags not matching that pattern, so it is technically unnecessary. > >> >> >>> + environment: deploy >>> + stage: deploy >> >> I think `deploy` could (should?) be added to the top-level `stages` list >> for the sake of completeness. > > deploy is added to the stages list at the beginning of this patch. Do > you mean somewhere else? It seems I am just blind. > >> >> >>> + needs: >>> + - job: build-docs >>> + script: >>> + - | >>> + mkdir -p ~/.ssh >>> + chmod 700 ~/.ssh >>> + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 >>> + chmod 600 ~/.ssh/id_ed25519 >>> + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts >>> + >>> + - | >>> + rsync -rlz --delete --chmod=Do=rx,Fo=r \ >>> + --exclude .doctrees \ >>> + --exclude .buildinfo \ >>> + --exclude objects.inv \ >>> + build/docs/ \ >>> + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME >> >> I like to hide the user and the host name in separate protected ci variables, >> but I guess it does not matter that much in the end. > > I think the less variables we require, the better. Is user & host > really that sensitive? I guess it's probably fine to have them public, but not sure if I'm missing something. But in any case, it's already on the mailing list. > >> >> Have you considered using `$CI_COMMIT_REF_SLUG` ? > > That is a great hint. I wasn't aware of that one. Ahh, it's not as great as I thought because it replaces `.` as well. :( Let's just ignore I have ever suggested this. > > Thanks, > Stefan > >> >> >> Regards, >> Barnabás Pőcze
Hi Laurent, Thank you for the review. Quoting Laurent Pinchart (2026-05-06 20:15:12) > On Wed, May 06, 2026 at 06:28:20PM +0200, Barnabás Pőcze wrote: > > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > > Add a build step that deploys the docs to docs.libcamera.org. This step > > > only runs on pushes to master and on tag builds. It requires two > > > external variables: > > > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > > --- > > > .gitlab-ci/setup-container.sh | 2 ++ > > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > > index c7ca6426c3ab..6c4b439b887b 100755 > > > --- a/.gitlab-ci/setup-container.sh > > > +++ b/.gitlab-ci/setup-container.sh > > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > > python3-sphinxcontrib.doxylink > > > texlive-latex-extra > > > ) > > > + # Packages required to deploy the documentation > > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > > # Tools requires by the lint jobs. > > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > > # libclang-rt-dev for the clang ASan runtime. > > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > > index 468f5769eb87..9bbceae38a27 100644 > > > --- a/gitlab-ci.yml > > > +++ b/gitlab-ci.yml > > > @@ -5,6 +5,7 @@ stages: > > > - build > > > - lint > > > - test > > > + - deploy > > > > > > variables: > > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > > @@ -74,7 +75,7 @@ include: > > > .libcamera-ci.debian:13: > > > variables: > > > FDO_DISTRIBUTION_VERSION: 'trixie' > > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > > > .container-debian: > > > extends: > > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > > artifacts: > > > reports: > > > junit: build/lc-compliance-report.xml > > > + > > > +# ------------------------------------------------------------------------------ > > > +# Deploy stage - deploy docs if we are building master or a tag > > > +# ------------------------------------------------------------------------------ > > > + > > > +deploy-docs: > > > + extends: > > > + - .fdo.distribution-image@debian > > > + - .libcamera-ci.debian:13 > > > + - .libcamera-ci.scripts > > > + rules: > > > + - if: $CI_COMMIT_BRANCH == "master" > > > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > > > ? > > > > > + - if: $CI_COMMIT_TAG > > Should we keep this one disabled until we reach v1.0 ? > > > - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ > > > > or something similar (possibly accepting some kind of suffix)? > > > > > + environment: deploy > > > + stage: deploy > > > > I think `deploy` could (should?) be added to the top-level `stages` list > > for the sake of completeness. > > All good comments. > > > > + needs: > > > + - job: build-docs > > > + script: > > > + - | > > > + mkdir -p ~/.ssh > > > + chmod 700 ~/.ssh > > > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > > > + chmod 600 ~/.ssh/id_ed25519 > > > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts > > I wonder if there's a particular reason to depart from > https://docs.gitlab.com/ci/jobs/ssh_keys/#ssh-keys-when-using-the-docker-executor, > which uses a file variable, and ssh-agent to avoid having to copy the > private key to ~/.ssh/. I don't really like that solution. It spills secrets somewhere on the system, requires running ssh-agent thereby adding additional complexity and you still need to create ~/.ssh/ for the known_hosts file. Having the secret in a env variable is also directly portable to forgejo where file secrets are not supported. To me this solution is easier/quicker to grasp. > > > > + > > > + - | > > > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > > > + --exclude .doctrees \ > > > + --exclude .buildinfo \ > > > + --exclude objects.inv \ > > > + build/docs/ \ > > > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME > > Could all of this be moved to a script ? I can do that, I don't see much gain though. Best regards, Stefan > > > I like to hide the user and the host name in separate protected ci variables, > > but I guess it does not matter that much in the end. > > Possibly still a good practice though. > > > Have you considered using `$CI_COMMIT_REF_SLUG` ? > > -- > Regards, > > Laurent Pinchart
On Thu, May 07, 2026 at 09:23:23AM +0200, Stefan Klug wrote: > Quoting Barnabás Pőcze (2026-05-06 18:28:20) > > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > > Add a build step that deploys the docs to docs.libcamera.org. This step > > > only runs on pushes to master and on tag builds. It requires two > > > external variables: > > > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > > --- > > > .gitlab-ci/setup-container.sh | 2 ++ > > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > > index c7ca6426c3ab..6c4b439b887b 100755 > > > --- a/.gitlab-ci/setup-container.sh > > > +++ b/.gitlab-ci/setup-container.sh > > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > > python3-sphinxcontrib.doxylink > > > texlive-latex-extra > > > ) > > > + # Packages required to deploy the documentation > > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > > # Tools requires by the lint jobs. > > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > > # libclang-rt-dev for the clang ASan runtime. > > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > > index 468f5769eb87..9bbceae38a27 100644 > > > --- a/gitlab-ci.yml > > > +++ b/gitlab-ci.yml > > > @@ -5,6 +5,7 @@ stages: > > > - build > > > - lint > > > - test > > > + - deploy > > > > > > variables: > > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > > @@ -74,7 +75,7 @@ include: > > > .libcamera-ci.debian:13: > > > variables: > > > FDO_DISTRIBUTION_VERSION: 'trixie' > > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > > > .container-debian: > > > extends: > > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > > artifacts: > > > reports: > > > junit: build/lc-compliance-report.xml > > > + > > > +# ------------------------------------------------------------------------------ > > > +# Deploy stage - deploy docs if we are building master or a tag > > > +# ------------------------------------------------------------------------------ > > > + > > > +deploy-docs: > > > + extends: > > > + - .fdo.distribution-image@debian > > > + - .libcamera-ci.debian:13 > > > + - .libcamera-ci.scripts > > > + rules: > > > + - if: $CI_COMMIT_BRANCH == "master" > > > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > Yes, I don't mind doing that. > > > > > ? > > > > > > > + - if: $CI_COMMIT_TAG > > > > - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ > > > > or something similar (possibly accepting some kind of suffix)? > > I'm wondering what we gain by that? Do you want to guard against upcoming > tags where we don't want documentation for? The next person reading this > would need to spend additional brain cycles decoding the regexp, then > wondering what it was meant for, then checking the tags to see what the > reason might have been, then realizing that it matches all tags in the > repo... On the other hand it might make the intent clearer. I don't have > a strong preference. If your concern is that it's not immediately clear, a comment above the line will help. > > > + environment: deploy > > > + stage: deploy > > > > I think `deploy` could (should?) be added to the top-level `stages` list > > for the sake of completeness. > > deploy is added to the stages list at the beginning of this patch. Do > you mean somewhere else? > > > > + needs: > > > + - job: build-docs > > > + script: > > > + - | > > > + mkdir -p ~/.ssh > > > + chmod 700 ~/.ssh > > > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > > > + chmod 600 ~/.ssh/id_ed25519 > > > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts > > > + > > > + - | > > > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > > > + --exclude .doctrees \ > > > + --exclude .buildinfo \ > > > + --exclude objects.inv \ > > > + build/docs/ \ > > > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME > > > > I like to hide the user and the host name in separate protected ci variables, > > but I guess it does not matter that much in the end. > > I think the less variables we require, the better. Is user & host > really that sensitive? > > > Have you considered using `$CI_COMMIT_REF_SLUG` ? > > That is a great hint. I wasn't aware of that one.
On Thu, May 07, 2026 at 09:36:20AM +0200, Stefan Klug wrote: > Quoting Laurent Pinchart (2026-05-06 20:15:12) > > On Wed, May 06, 2026 at 06:28:20PM +0200, Barnabás Pőcze wrote: > > > 2026. 05. 06. 17:54 keltezéssel, Stefan Klug írta: > > > > Add a build step that deploys the docs to docs.libcamera.org. This step > > > > only runs on pushes to master and on tag builds. It requires two > > > > external variables: > > > > > > > > DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key > > > > DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org > > > > > > > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> > > > > --- > > > > .gitlab-ci/setup-container.sh | 2 ++ > > > > gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- > > > > 2 files changed, 36 insertions(+), 1 deletion(-) > > > > > > > > diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh > > > > index c7ca6426c3ab..6c4b439b887b 100755 > > > > --- a/.gitlab-ci/setup-container.sh > > > > +++ b/.gitlab-ci/setup-container.sh > > > > @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in > > > > python3-sphinxcontrib.doxylink > > > > texlive-latex-extra > > > > ) > > > > + # Packages required to deploy the documentation > > > > + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) > > > > # Tools requires by the lint jobs. > > > > PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) > > > > # libclang-rt-dev for the clang ASan runtime. > > > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml > > > > index 468f5769eb87..9bbceae38a27 100644 > > > > --- a/gitlab-ci.yml > > > > +++ b/gitlab-ci.yml > > > > @@ -5,6 +5,7 @@ stages: > > > > - build > > > > - lint > > > > - test > > > > + - deploy > > > > > > > > variables: > > > > FDO_UPSTREAM_REPO: 'camera/libcamera' > > > > @@ -74,7 +75,7 @@ include: > > > > .libcamera-ci.debian:13: > > > > variables: > > > > FDO_DISTRIBUTION_VERSION: 'trixie' > > > > - FDO_DISTRIBUTION_TAG: '2026-04-24.0' > > > > + FDO_DISTRIBUTION_TAG: '2026-05-06.0' > > > > > > > > .container-debian: > > > > extends: > > > > @@ -437,3 +438,35 @@ test-lc-compliance:virtual: > > > > artifacts: > > > > reports: > > > > junit: build/lc-compliance-report.xml > > > > + > > > > +# ------------------------------------------------------------------------------ > > > > +# Deploy stage - deploy docs if we are building master or a tag > > > > +# ------------------------------------------------------------------------------ > > > > + > > > > +deploy-docs: > > > > + extends: > > > > + - .fdo.distribution-image@debian > > > > + - .libcamera-ci.debian:13 > > > > + - .libcamera-ci.scripts > > > > + rules: > > > > + - if: $CI_COMMIT_BRANCH == "master" > > > > > > - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH > > > > > > ? > > > > > > > + - if: $CI_COMMIT_TAG > > > > Should we keep this one disabled until we reach v1.0 ? > > > > > - if: $CI_COMMIT_TAG =~ /^v([0-9]+\.)*[0-9]+$/ > > > > > > or something similar (possibly accepting some kind of suffix)? > > > > > > > + environment: deploy > > > > + stage: deploy > > > > > > I think `deploy` could (should?) be added to the top-level `stages` list > > > for the sake of completeness. > > > > All good comments. > > > > > > + needs: > > > > + - job: build-docs > > > > + script: > > > > + - | > > > > + mkdir -p ~/.ssh > > > > + chmod 700 ~/.ssh > > > > + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 > > > > + chmod 600 ~/.ssh/id_ed25519 > > > > + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts > > > > I wonder if there's a particular reason to depart from > > https://docs.gitlab.com/ci/jobs/ssh_keys/#ssh-keys-when-using-the-docker-executor, > > which uses a file variable, and ssh-agent to avoid having to copy the > > private key to ~/.ssh/. > > I don't really like that solution. It spills secrets somewhere on the > system, As far as I understand, because the mechanism was designed for that purpose, the runner will ensure that the location remains secure. I don't know what guarantees we have for ~/.ssh/ on shared runners. > requires running ssh-agent thereby adding additional complexity > and you still need to create ~/.ssh/ for the known_hosts file. True, but known_hosts isn't security-sensitive (from the point of view of being leaked). > Having > the secret in a env variable is also directly portable to forgejo where > file secrets are not supported. True, but I'm not sure that's relevant. gitlab-ci.yml isn't portable to forgejo :-) > To me this solution is easier/quicker to grasp. The fact that a file variable is recommended by gitlab makes me concerned that a home-grown solution may be less secure. Note how using regular variables, documented by gitlab as an alternative ([1]), also uses ssh-agent: - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | DISPLAY=None SSH_ASKPASS=~/.ssh/tmp ssh-add - I however don't know if that's on purpose for specific reasons, or was just done that way. [1] https://gitlab.com/gitlab-examples/ssh-private-key/-/blob/main/.gitlab-ci.yml?ref_type=heads > > > > + > > > > + - | > > > > + rsync -rlz --delete --chmod=Do=rx,Fo=r \ > > > > + --exclude .doctrees \ > > > > + --exclude .buildinfo \ > > > > + --exclude objects.inv \ > > > > + build/docs/ \ > > > > + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME > > > > Could all of this be moved to a script ? > > I can do that, I don't see much gain though. > > > > I like to hide the user and the host name in separate protected ci variables, > > > but I guess it does not matter that much in the end. > > > > Possibly still a good practice though. > > > > > Have you considered using `$CI_COMMIT_REF_SLUG` ?
diff --git a/.gitlab-ci/setup-container.sh b/.gitlab-ci/setup-container.sh index c7ca6426c3ab..6c4b439b887b 100755 --- a/.gitlab-ci/setup-container.sh +++ b/.gitlab-ci/setup-container.sh @@ -132,6 +132,8 @@ case $FDO_DISTRIBUTION_VERSION in python3-sphinxcontrib.doxylink texlive-latex-extra ) + # Packages required to deploy the documentation + PKGS_LIBCAMERA_RUNTIME+=( openssh-client rsync ) # Tools requires by the lint jobs. PKGS_LIBCAMERA_RUNTIME+=( clang-format jq python3-autopep8 reuse shellcheck ) # libclang-rt-dev for the clang ASan runtime. diff --git a/gitlab-ci.yml b/gitlab-ci.yml index 468f5769eb87..9bbceae38a27 100644 --- a/gitlab-ci.yml +++ b/gitlab-ci.yml @@ -5,6 +5,7 @@ stages: - build - lint - test + - deploy variables: FDO_UPSTREAM_REPO: 'camera/libcamera' @@ -74,7 +75,7 @@ include: .libcamera-ci.debian:13: variables: FDO_DISTRIBUTION_VERSION: 'trixie' - FDO_DISTRIBUTION_TAG: '2026-04-24.0' + FDO_DISTRIBUTION_TAG: '2026-05-06.0' .container-debian: extends: @@ -437,3 +438,35 @@ test-lc-compliance:virtual: artifacts: reports: junit: build/lc-compliance-report.xml + +# ------------------------------------------------------------------------------ +# Deploy stage - deploy docs if we are building master or a tag +# ------------------------------------------------------------------------------ + +deploy-docs: + extends: + - .fdo.distribution-image@debian + - .libcamera-ci.debian:13 + - .libcamera-ci.scripts + rules: + - if: $CI_COMMIT_BRANCH == "master" + - if: $CI_COMMIT_TAG + environment: deploy + stage: deploy + needs: + - job: build-docs + script: + - | + mkdir -p ~/.ssh + chmod 700 ~/.ssh + echo "${DEPLOY_SSH_KEY_BASE64}" | base64 --decode > ~/.ssh/id_ed25519 + chmod 600 ~/.ssh/id_ed25519 + echo "${DEPLOY_KNOWN_HOSTS}" > ~/.ssh/known_hosts + + - | + rsync -rlz --delete --chmod=Do=rx,Fo=r \ + --exclude .doctrees \ + --exclude .buildinfo \ + --exclude objects.inv \ + build/docs/ \ + deploy@docs.libcamera.org:/$CI_COMMIT_REF_NAME
Add a build step that deploys the docs to docs.libcamera.org. This step only runs on pushes to master and on tag builds. It requires two external variables: DEPLOY_SSH_KEY_BASE64: base64 encoded private deploy key DEPLOY_KNOWN_HOSTS: Known hosts containing docs.libcamera.org Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com> --- .gitlab-ci/setup-container.sh | 2 ++ gitlab-ci.yml | 35 ++++++++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-)