Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
GitHub action to publish docs to GH Pages #1129
base: master
Are you sure you want to change the base?
GitHub action to publish docs to GH Pages #1129
Changes from 15 commits
2f000a45a85d8d664d580dbac6d3fae56762d18a98cb63d3a03f72210dd9541354e2b754cfd49de8024e16150cdd2bb3690006eb2dff9e1f9b8039d45cd54a2f85300897b95eb802387bee22614bb846aFile filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good start,
Per existing CircleCI config, there's also a need for additional routing logic depending on the branch:
st2docs/.circleci/config.yml
Lines 41 to 61 in 6c65852
From what I understand the logic looks this way:
masterbranch build ->/latest/st2docs dirv.X.Y.Zlatest stable branch ->/st2docs dirvX.Y.Zbranch build ->vX.Yst2docs dirThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this might be possible with the
destination_dir: subdiroption:https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-deploy-to-subdirectory-destination_dir
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
so, the
destination_dir: subdiroption works well for/latestand/X.Ysite directories. so 🎉One difference, however, is that if we deploy to the root for the latest GA version like we do for S3, we'll lose all other subdirectories. For example, if we have
/1.0and/latest, and then we determine that the current version is also the latest GA release, deploying the site to/will wipe away/1.0and/latest. I've confirmed this with testing.To get around this, we could implement the action to deploy the latest GA release to a
/gasubdirectory, and we can use URL routing to pointdocs.stackstorm.comtodocs.stackstorm.com/ga. Thoughts?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
actually, we have a bigger issue:
When we push to github pages, a bot will run a
pages-build-deploymentpipeline. If we push togh-pagesagain while an existingpages-build-deploymentpipeline is running, github will cancel the previous deployment in favor of the subsequent one:This means that we cannot push to
gh-pageswhile there is an ongoing gh pages deployment, and it is non-trivial to "wait" until the gh pages deployment is finished. I suspect it's possible, though I've not looked into how it might be done (it'd probably involve the github api and some sort of polling logic).This will also impact us when we want to run a deployment to existing version branches as we'd have to wait until each is finished before triggering the next one..
One thing that might help is that we could utilize the concurrency feature for our workflow. This will help ensure that our workflows don't run while another of our workflows are running, but we don't seem to have control over the
pages-build-deploymentpipeline.https://stackoverflow.com/questions/70631168/github-actions-going-through-with-pages-build-deployment
Using
concurrencymight help because it's likely the gh pages will finish before any subsequent builds do, but it's a risk. It's possible that the gh pages deployment will take some time in which case our st2docs build might finish before and cancel the existingpages-build-deploymentpipeline.Concurrency was not working with my testing of multiple jobs in the same workflow, however.. (test here: https://github.com/StackStorm/st2docs/pull/1129/files#diff-7b112bd01a3c7000d73727a7e66cbfb9cf00a47702c94fda157e23f46e20db17R1)
However, it also means that we have to run two builds for the same thing...
One possible workaround is to use routing logic in Route53 or cloudfront to point the latest GA release instead of using a
/gasubdirectory. I can think of 2 ways to do this:alternatively, it might be possible in the future to publish to GH Pages without the bot, but for now, that's our only option, I think:
https://github.community/t/github-pages-bot-added-to-our-repos-unannounced/218214/13
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
example pipeline here: https://github.com/mickmcgrath13/st2docs/actions/runs/2531438591
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think I understand the issue. The
pages-build-deploymentpipeline that github runs will be deploying whatever is on the gh-pages branch.So, if we have two merges into the gh-pages branch at about the same time, and two builds start, then the build for the older commit should be canceled. But, because the newer commit should include everything from the previous commit, I don't think that's a problem. What else am I missing here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think the issue was that if we are deploying say to version 3.7 of the docs, and then do a deploy to latest whilst its still running the deploy for v3.7. The v3.7 one will be cancelled, and we won't get the update to v3.7.
Though it isn't a frequent occurrance, that we push doc changes to the older branches, so as long as we can re-trigger the branched build I would have thought that would be ok.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By the time
pages-build-deploymentruns for latest (cancelling the previous deployment), the updated 3.7 sources will already be committed to the gh-pages branch.pages-build-deploymentredeploys everything ingh-pagesafaik, so the nextpages-build-deploymentrun will include both 3.7 and latest in the deployed changes.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
from my previous notes:
One thing that can possibly work around these issues is to always only build gh pages in a pipeline based on the base branch. the base branch gh-pages pipeline will also
cloneother versions/subdirectories and build those.then we have pipelines for version-specific branches that just trigger the base gh-pages pipeline to rebuild everything
an all-in-one pipeline at the base branch that builds root and subdirectories would also mitigate special routing requirements (i.e. we just build all the subdirectories we need)
just some thoughts..