Hi James, Sorry for the late reply, I read this more as an fyi. We use a similar but more convoluted setup for arrow.
The docs are generated from the main repo sources and templates via sphinx etc. in a workflow and then uploaded to the actual arrow-site repo through a normal fork PR by the release manager after the vote. The dev docs are generated and updated nightly through a workflow in the arrow-site repo (we used to do this for the releases too but had instances where building the docs surfaced errors missed in our verification, so now successfully building docs is part of our release CI for the monorepo). In regards to your process using a PAT: I think this is fine if a fine grained token (from a service account) is used that only has access to the grails-docs repo with the relevant scope. With the goal of minimal required permissions I think you could make it work with only `actions:write` using `workflow_dispatch` triggering a workflow in the docs repo that gets the ref to build the docs for as an input and generates + pushes the docs to the gh_pages branch. Best, Jacob James Daugherty <jdaughe...@jdresources.net.invalid> schrieb am Mi., 30. Apr. 2025, 23:44: > Hi Everyone, > > I still have not seen a response to this request. Can anyone please > provide guidance on this issue - publishing documentation to a different > repository? grails-core generates the documentation and saves to > grails-doc:gh-pages branch to keep the grails-core repo size small. > > Regards, > James > > On Fri, Apr 18, 2025 at 12:12 PM Drew Foulks <dfou...@apache.org> wrote: > > > Pulling in our GitHub actions folks too > > > > On Fri, Apr 18, 2025 at 12:08 PM James Daugherty < > > jdaughe...@jdresources.net> wrote: > > > >> Hi Everyone, > >> > >> I spoke to Drew about the grails project's need to publish its > >> documentation and the challenge we have with the documentation being > >> published to a separate repository. Drew suggested I send a summary of > how > >> our process works. From my discussion with Drew, it sounds like this > is a > >> grey area in the policy and approval may need to be granted to proceed. > >> Please see below. > >> > >> ---------------------------------------- > >> > >> Today, the grails-core repository contains both the "documentation" > >> templates & the grails-core code base. The `grails-doc` repository acts > >> only as a hosting mechanism for the generated documentation. This is > >> because the generated documentation can consume over 30 megabytes for > each > >> build. > >> > >> In GitHub, the gh-pages branch is how a GitHub page is hosted. When > >> changes are pushed to a branch with this name, GitHub automatically > deploys > >> the GitHub pages based on that branch. For the grails-doc repository, > its > >> github page has an external dns name (https://docs.grails.org) that end > >> users access. > >> > >> The size of the gh-pages branch in the grails-doc repository is over 3 > >> gigabytes due to the history of documentation. Normally, this branch > would > >> live in the same repository, but the size of the documentation has made > it > >> difficult to obtain contributions. For this reason, it was decided that > >> the documentation templates be moved to grails-core where the > repository is > >> much smaller in size. The hope being people would change the > documentation > >> when code is changed and it would be easy to checkout this project. > >> > >> Since the repository is separate, we need to be able to deploy the build > >> results to the gh-pages branch in grails-doc. If this was a combined > repo, > >> we could do it with the existing GITHUB_TOKEN that is provided on each > >> GitHub action build. The GITHUB_TOKEN does not allow access to > different > >> repositories though. So we need a separate token to commit the > generated > >> code to the grails-doc repository's gh-pages branch. Can this token > please > >> be provided in form a github action secret on the grails-core > repository? > >> > >> Regards, > >> James > >> > >> > >> > >> > > > > -- > > Cheers, > > > > Drew Foulks > > ASF Infra > > > > > > >
