chore(ci): setup auto docs publish workflow for release vX.X.X tag #7331

ShenQingchuan · 2022-03-15T17:11:19Z

Automatic workflow for release docs publish

I wrote these guides in order to give our reviewers more context and information here.

Why for this PR ?

After publishing a new release of Vite, we must open Netlify UI to trigger docs build & publish manually now.

It's because the contents of docs folder are actively updating, and we'll always see the latest content on docs site if we use Netlify's git-based deployment, but actually there's something ahead of current release.

So I'm wondering if there's some ways for setting up an automatically deploy workflow which only targets on vX.X.X tag, it's a significant sign.

Is these changes enough ?

Actually, NO. we should add more configs around.

First: turn off Netlify builds

Since now this repo would not trigger a new deploy by commit pushing, we can skip this step if it's already done.

Go to Netlify UI, site administration page.
Open Site Setting panel
Open Build & Deploy tab on the left side
Scroll down to Build Settings, and click Edit Settings
Select Builds --> Stop Builds

Second: setting up secrets

This step may requires @yyx990803, @patak-dev or someone has right to access this repo's setting panel, to create a list of following fields:

VITE_GITHUB_TOKEN: this is a Github Access Token, may need to be generated by manually creating @yyx990803

https://github.com/settings/tokens
NETLIFY_AUTH_TOKEN: this is a personal access token which is supposed to be generate on Netlify.

https://app.netlify.com/user/applications#personal-access-tokens
NETLIFY_SITE_ID: this one could be found at General | Site settings

But I could use an open API of Netlify to query for result:

curl https://api.netlify.com/api/v1/sites/vitejs.dev

// id: 8c66140b-3a31-475e-b0c6-ff6689563820

That's all for configuration.

patak-dev · 2022-03-19T19:47:14Z

@ShenQingchuan in Vitest we have a setup that shows a preview for each commit that affects the docs: vitest-dev/vitest#970. Would the action you used here do the same? @antfu do you have a link to guide us to do the same you did for Vitest here?

antfu · 2022-03-20T06:02:52Z

a link to guide

Actually, it's the default behavior of Netlify - unless you disable it explicitly. I guess it's done by Evan for a reason 👀

patak-dev · 2022-03-20T07:32:25Z

Added for discussion in the next meeting, let's check with him then.

ShenQingchuan · 2022-03-20T16:20:43Z

@ShenQingchuan in Vitest we have a setup that shows a preview for each commit that affects the docs: vitest-dev/vitest#970. Would the action you used here do the same? @antfu do you have a link to guide us to do the same you did for Vitest here?

No, the setup I made here is for release docs publish.
I know that maybe you @patak-dev also want to keep the preview feature of Netlify and not trigger a production release in daily commits pushing. I'll find it out how to do it !

Could you please let me sit in on the next internal meeting when talking about this issue ( for only once 😊 )

ShenQingchuan · 2022-03-20T17:15:44Z

2nd Update

What's new? I've removed the config field production-branch: main because it would send production build request on Netlify by default ( even with production-deploy is actually false by default ). So we can only use production-deploy with an expression value instead.

vite/.github/workflows/deploy-docs-on-netlify.yml

Line 39 in 419b18e

production-deploy: ${{ github.event_name == 'release' }}

It would generate "Preview" deploy as expected when we modified and pushed anything under docs/.

References for your need:

ShenQingchuan · 2022-03-21T12:54:42Z

And I'm supposed to provide some more information...

the "Preview Build" is indeed a feature of Netlify but it's not by default, it depends on which branch you assign as a "Production branch"

if you push something to the "Production branch", it triggers a "Production build"
if you push something to another branch, it triggers a "Preview build"

patak-dev · 2022-04-01T11:47:17Z

Sorry for taking so much time @ShenQingchuan, v2.9 is out now, so getting back to this.

Some questions:

So IIUC, we aren't trying to get netlify to send as the docs previews. I checked in Vitest, and we are getting them even if we don't touch the docs and that is quite noisy: fix: vitest cannot read the latest config when it changes vitest-dev/vitest#1001.
If we delete the netlify.toml file, aren't we going to stop being able to use the Netlify UI? For example the Retry Deploy. It may still be ok, we haven't used that button until now.
About VITE_GITHUB_TOKEN, could we directly use secrets.GITHUB_TOKEN that is automatically generated for the action?
The current workflow will also deploy the docs for production when we release a plugin. Until now, we are only publishing when releasing Vite core. There have been some times when we released a plugin in the middle of a beta for example. So we should check that the tag of the release corresponds to Vite. We should also avoid releasing for production for a beta release. (unrelated, but I think it would be great to have a public https://beta.vitejs.dev deployment for the betas)

ShenQingchuan · 2022-04-06T07:07:08Z

Sorry for taking so much time @ShenQingchuan, v2.9 is out now, so getting back to this.

Some questions:

So IIUC, we aren't trying to get netlify to send as the docs previews. I checked in Vitest, and we are getting them even if we don't touch the docs and that is quite noisy: fix: vitest cannot read the latest config when it changes vitest-dev/vitest#1001.

If we delete the netlify.toml file, aren't we going to stop being able to use the Netlify UI? For example the Retry Deploy. It may still be ok, we haven't used that button until now.

About VITE_GITHUB_TOKEN, could we directly use secrets.GITHUB_TOKEN that is automatically generated for the action?

The current workflow will also deploy the docs for production when we release a plugin. Until now, we are only publishing when releasing Vite core. There have been some times when we released a plugin in the middle of a beta for example. So we should check that the tag of the release corresponds to Vite. We should also avoid releasing for production for a beta release. (unrelated, but I think it would be great to have a public https://beta.vitejs.dev deployment for the betas)

Hi, @patak-dev

Sorry for take so long to notify that this issue got an update! I would like to answer your questions one by one:

Sorry for that I don't really get your point at this one, do you mean that we're not going to set a Netlify preview every commit because that's annoying? IIUC, then my answer is "That's ok", now this PR set up "Preview build" only for every changes under docs/ dir.
Yes for "Not able to use the 'Re-trigger build' button in Netlify Admin UI", but it's not because of netlify.toml deletion, it's because we need to stop(de-activate) "Netlify Build", this setting will effect whether turn to an auto build for each commit in this repo. We actually need to get full control of build to implement our specific "logic" about publishing docs.

Difference between "Stop build" & "Stop auto publishing":
According to my Q&A with Evan and my own experiment:
- Stop auto publishing(Now this repo is using this one): build on every commit, but no publish, need manually click "Publish Deploy" button in Netlify UI.
- Stop build: Netlify will not trigger build by any commit / PR or something else, can only send deploy via API
So I think we may not need Netlify UI anymore as we just use this platform to deploy, and the Github Action plugin nwtgck/actions-netlify could meet our needs.
I don't know about this feature. Does every action task generate its own Github token?
OK, I got your point. I will think about how to change the setting to match our needs. The main difficulty is how to write a correct "conditional expression" in Github Workflow Configuration for publish-deploy field.

ShenQingchuan · 2022-04-06T07:22:25Z

For the question 4: I may need to get it more clear ...

Do we just need to publish docs on vX.X.X tags release ? @patak-dev

only trigger production build for core release

patak-dev · 2022-04-06T07:50:51Z

. 4. Yes, only for vX.X.X

. 3. Yes, and it is available as secrets.GITHUB_TOKEN https://docs.github.com/en/actions/security-guides/automatic-token-authentication

. 1. and 2. I was only checking that I understood the implications and I agree that what you are proposing is good 👍

ShenQingchuan · 2022-04-06T08:06:05Z

@yyx990803

According to my experiment now, we must enable "auto publishing", otherwise the new deploy generated by Github Action can't be the latest "Production build".

patak-dev · 2022-04-11T21:34:03Z

.github/workflows/deploy-docs-on-netlify.yml

+        with:
+          publish-dir: "docs/.vitepress/dist"
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          production-deploy: ${{ startsWith(github.ref, 'refs/tags/v') }}


This will also match for beta releases, no? That we wanted to avoid
https://github.com/vitejs/vite/releases/tag/v2.9.0-beta.11

yes，maybe a more specific regular expression ..

@patak-dev Maybe a clearer definition of our requirements about branch/tag name ?

Starts with "v"

Not contains "beta" (or something else ?)

Yes, starts with v and not includes beta covers it 👍🏼

I use contains which is defined as built-in function @patak-dev

( docs: https://docs.github.com/en/actions/learn-github-actions/expressions#contains )

patak-dev · 2022-04-14T18:57:17Z

@ShenQingchuan I just saw that netlify auto-deploys now has a fixed URL for main:

https://main--vitejs.netlify.app/

This is great, as we can use it to check the current HEAD state and as temporal docs during the beta. Maybe we should check that this PR isn't going to disable this feature, or improve on it by directly deploying on every commit to main.vitejs.dev?

ShenQingchuan · 2022-04-14T19:04:13Z

@patak-dev

Yes, that's another awesome feature of Netlify that I didn't know !

Does it means that: Right now we already have a url to preview our latest docs ?

patak-dev · 2022-04-14T19:09:56Z

Yes, check https://main--vitejs.netlify.app/! 🙌🏼
The UI for netlify changed a bit and now I saw this URL instead of the usual preview one. Or maybe someone touched some general configuration in the Vue netlify account 🤔

ShenQingchuan · 2022-04-14T19:24:39Z

@patak-dev

I found specification about it in Netlify docs, but it seems need to require auto build from a branch. but for main branch, it's quite spacial because it's actually our production branch. And it leads to update our release site by every commit.

But I've got your idea about main.vitejs.dev, I'd think about how to make it work.

ShenQingchuan · 2022-04-25T10:20:21Z

@patak-dev Maybe we can merge this PR first ?

I haven't found any good idea to "Enable auto publishing main branch to main--vitejs.netlify.app" and "Do not auto publishing main branch's deploy as production site content" at the same time, it seems that Netlify do not support this requirement.

This is also important:

According to my experiment now, we must enable "auto publishing", otherwise the new deploy generated by Github Action can't be (published as) the latest "Production build".

patak-dev · 2022-04-25T15:01:24Z

I think we are close to moving forward to test it. I found another issue though. We release patches from prev minors so if we tag 2.9.3 -> 2.8.7, we'll end up with stale docs because it will trigger a new deployment. So we need to check that the tag is from the main branch? Or maybe I'm missing something 🤔

@ShenQingchuan another thing that we should think about is how we could deploy to deploy a
v2.vitejs.dev to keep the v2 branch once we start using vitejs.dev for the next major. Maybe it doesn't need to be automatic and we can run the publish command manually from the v2.9.x branch

patak-dev · 2022-04-25T18:30:37Z

@antfu is using https://docs.netlify.com/domains-https/custom-domains/multiple-domains/#branch-subdomains for VueUse, so there is deploy with the last version for each major: https://v6-7-6.vueuse.org/. In Vite it is usual to apply patches to older versions, so it would be better to have a https://v2.vitejs.dev. Maybe we could still use it and for the last minor in each major we tag it as v2

bluwy · 2024-05-18T06:30:56Z

Do we still want to go ahead with this? I believe we have disabled auto publishing, but we still manually trigger publishing when we cut a release, and this PR automates it?

ShenQingchuan · 2024-05-20T11:40:15Z

I think the problem this PR tried to resolve is staled, so it's closable now.

ShenQingchuan force-pushed the shenqingchuan/netlify-deploy-by-api branch 2 times, most recently from 374bcca to faf559b Compare March 15, 2022 17:15

patak-dev self-assigned this Mar 18, 2022

ShenQingchuan added 2 commits March 21, 2022 01:03

chore(ci): setup auto docs publish workflow for release vX.X.X tag

aec6b92

chore(docs): split docs deloy into push and release types

419b18e

ShenQingchuan force-pushed the shenqingchuan/netlify-deploy-by-api branch from faf559b to 419b18e Compare March 20, 2022 17:03

patak-dev added the p1-chore Doesn't change code behavior (priority) label Apr 1, 2022

fix: adjust workflow config

66e0d52

only trigger production build for core release

ShenQingchuan added 2 commits April 6, 2022 15:58

fix: deploy message

14d5c31

fix: use auto generated GITHUB_TOKEN

7c513f8

fix: wrong reference

c611b42

patak-dev reviewed Apr 11, 2022

View reviewed changes

fix: add a more specific check for tag name

48782f7

patak-dev approved these changes Apr 14, 2022

View reviewed changes

ShenQingchuan closed this May 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(ci): setup auto docs publish workflow for release vX.X.X tag #7331

chore(ci): setup auto docs publish workflow for release vX.X.X tag #7331

ShenQingchuan commented Mar 15, 2022

patak-dev commented Mar 19, 2022

antfu commented Mar 20, 2022

patak-dev commented Mar 20, 2022

ShenQingchuan commented Mar 20, 2022 •

edited

ShenQingchuan commented Mar 20, 2022 •

edited

ShenQingchuan commented Mar 21, 2022

patak-dev commented Apr 1, 2022

ShenQingchuan commented Apr 6, 2022 •

edited

ShenQingchuan commented Apr 6, 2022

patak-dev commented Apr 6, 2022 •

edited

ShenQingchuan commented Apr 6, 2022

patak-dev Apr 11, 2022

ShenQingchuan Apr 13, 2022

ShenQingchuan Apr 13, 2022 •

edited

patak-dev Apr 13, 2022

ShenQingchuan Apr 14, 2022 •

edited

patak-dev commented Apr 14, 2022 •

edited

ShenQingchuan commented Apr 14, 2022

patak-dev commented Apr 14, 2022

ShenQingchuan commented Apr 14, 2022 •

edited

ShenQingchuan commented Apr 25, 2022 •

edited

patak-dev commented Apr 25, 2022

patak-dev commented Apr 25, 2022

bluwy commented May 18, 2024

ShenQingchuan commented May 20, 2024

chore(ci): setup auto docs publish workflow for release vX.X.X tag #7331

chore(ci): setup auto docs publish workflow for release vX.X.X tag #7331

Conversation

ShenQingchuan commented Mar 15, 2022

Automatic workflow for release docs publish

Why for this PR ?

Is these changes enough ?

First: turn off Netlify builds

Second: setting up secrets

That's all for configuration.

patak-dev commented Mar 19, 2022

antfu commented Mar 20, 2022

patak-dev commented Mar 20, 2022

ShenQingchuan commented Mar 20, 2022 • edited

ShenQingchuan commented Mar 20, 2022 • edited

2nd Update

ShenQingchuan commented Mar 21, 2022

patak-dev commented Apr 1, 2022

ShenQingchuan commented Apr 6, 2022 • edited

ShenQingchuan commented Apr 6, 2022

patak-dev commented Apr 6, 2022 • edited

ShenQingchuan commented Apr 6, 2022

patak-dev Apr 11, 2022

Choose a reason for hiding this comment

ShenQingchuan Apr 13, 2022

Choose a reason for hiding this comment

ShenQingchuan Apr 13, 2022 • edited

Choose a reason for hiding this comment

patak-dev Apr 13, 2022

Choose a reason for hiding this comment

ShenQingchuan Apr 14, 2022 • edited

Choose a reason for hiding this comment

patak-dev commented Apr 14, 2022 • edited

ShenQingchuan commented Apr 14, 2022

patak-dev commented Apr 14, 2022

ShenQingchuan commented Apr 14, 2022 • edited

ShenQingchuan commented Apr 25, 2022 • edited

patak-dev commented Apr 25, 2022

patak-dev commented Apr 25, 2022

bluwy commented May 18, 2024

ShenQingchuan commented May 20, 2024

ShenQingchuan commented Mar 20, 2022 •

edited

ShenQingchuan commented Mar 20, 2022 •

edited

ShenQingchuan commented Apr 6, 2022 •

edited

patak-dev commented Apr 6, 2022 •

edited

ShenQingchuan Apr 13, 2022 •

edited

ShenQingchuan Apr 14, 2022 •

edited

patak-dev commented Apr 14, 2022 •

edited

ShenQingchuan commented Apr 14, 2022 •

edited

ShenQingchuan commented Apr 25, 2022 •

edited