add CI to preview PRs #5

earl-warren commented 2023年08月15日 21:02:13 +02:00

TODO:

• clone from website instead of caesar
• skip the proof of change commit

Preview: https://forgejo.codeberg.page/@docs_pull_5/

This is a simplistic approach to get started with previews. It copies the website, moves the docs under /forgejo-docs/{{ base branch }}, create the website and publishes it for preview. No doubt the actual workflow will be different but that needs to be decided.

• Added a WEBSITETOKEN secret created from the forgejo-website user. It is a token with write access to repositories. https://codeberg.org/forgejo/docs/settings/actions/secrets. Contrary to woodpecker it is not in an environment variable but will be replaced when inserting ${{ secrets.WEBSITETOKEN }} somewhere
• In the environment the variable was replaced CI_COMMIT_PULL_REQUEST → ${{ env.GITHUB_REF_NAME }}
• The preview is published at https://forgejo.codeberg.page/@docs_pull_N/ instead of https://forgejo.codeberg.page/@pull_N/
• The $$ were replaced with $ in the script because Forgejo Actions does not interpret $ and therefore does not need escaping them to $$

TODO: - [x] clone from website instead of caesar - [x] skip the proof of change commit Preview: https://forgejo.codeberg.page/@docs_pull_5/ This is a simplistic approach to get started with previews. It copies the website, moves the docs under `/forgejo-docs/{{ base branch }}`, create the website and publishes it for preview. No doubt the actual workflow will be different but that needs to be decided. * Added a WEBSITETOKEN secret created from the forgejo-website user. It is a token with write access to repositories. https://codeberg.org/forgejo/docs/settings/actions/secrets. Contrary to woodpecker it is not in an environment variable but will be replaced when inserting `${{ secrets.WEBSITETOKEN }}` somewhere * In the environment the variable was replaced CI_COMMIT_PULL_REQUEST → `${{ env.GITHUB_REF_NAME }}` * The preview is published at https://forgejo.codeberg.page/@docs_pull_N/ instead of https://forgejo.codeberg.page/@pull_N/ * The `$$` were replaced with `$` in the script because Forgejo Actions does not interpret `$` and therefore does not need escaping them to `$$`

earl-warren commented 2023年08月15日 21:16:21 +02:00

I forgot that secrets are not available to workflows running from pull requests from remote repositories. So... all PRs have to be from branches within the docs repository. That's not ideal but given that 99% of the contributions are from people with write access to the repository that should not be too much of a problem.

If someone contributes via a PR on a remote repository it can be dealt manually. That happened less than 10 times. This will change once the runner is more secure.

An alternative would be to stick to Woodpecker. But I'm not eager to keep maintaining the server/agents and all that entails. So I would rather live with this inconvenience than relying more on Woodpecker, unless it is absolutely necessary.

I forgot that secrets are not available to workflows running from pull requests from remote repositories. So... all PRs have to be from branches within the docs repository. That's not ideal but given that 99% of the contributions are from people with write access to the repository that should not be too much of a problem. If someone contributes via a PR on a remote repository it can be dealt manually. That happened less than 10 times. This **will change** once the runner is more secure. An alternative would be to stick to Woodpecker. But I'm not eager to keep maintaining the server/agents and all that entails. So I would rather live with this inconvenience than relying more on Woodpecker, unless it is absolutely necessary.

crystal commented 2023年08月15日 21:42:16 +02:00

I feel very strongly that it is important for anyone with any level of involvement with the project to be able to easily send documentation pull requests. In general, I feel we should be lowering the barrier to entry for contributing to the docs at all costs. That was one of the main reasons I wanted this in a separate repo in the first place. It'll also make a mess of the branches in this repo. I suppose the previews aren't as important here as they are for the website repo, most of the content is textual and we should be able to get an idea of what it'll look like by checking the markdown preview in Forgejo. I'm rambling on, this is just a bit disappointing.

I see three potential paths forward

• Proceed with this strategy
  • Add a check to skip the preview upload if the secret isn't available
• Don't worry about previews for now
• Use Woodpecker until we have a more secure runner that can handle this situation more gracefully

I'm somewhat indifferent. I wouldn't mind personally putting in some extra effort to adopt the latter strategy, but if others are strongly opposed to it, I'll let it go.

I feel very strongly that it is important for anyone with any level of involvement with the project to be able to easily send documentation pull requests. In general, I feel we should be lowering the barrier to entry for contributing to the docs at all costs. That was one of the main reasons I wanted this in a separate repo in the first place. It'll also make a mess of the branches in this repo. I suppose the previews aren't as important here as they are for the website repo, most of the content is textual and we should be able to get an idea of what it'll look like by checking the markdown preview in Forgejo. I'm rambling on, this is just a bit disappointing. I see three potential paths forward - Proceed with this strategy - Add a check to skip the preview upload if the secret isn't available - Don't worry about previews for now - Use Woodpecker until we have a more secure runner that can handle this situation more gracefully I'm somewhat indifferent. I wouldn't mind personally putting in some extra effort to adopt the latter strategy, but if others are strongly opposed to it, I'll let it go.

earl-warren commented 2023年08月15日 21:47:23 +02:00

I feel very strongly that it is important for anyone with any level of involvement with the project to be able to easily send documentation pull requests.

I agree and I'm quite unhappy that I did not see this problem coming although it was under my nose the whole time.

Proceed with this strategy

• Add a check to skip the preview upload if the secret isn't available

And fix Forgejo Actions to make it possible. I think that's the only path forward because Forgejo Actions users will face the same situation. It's one of the unpleasant side effect of dogfooding: when something goes wrong, it stings.

Use Woodpecker until we have a more secure runner that can handle this situation more gracefully

I strongly feel that is a last resort, if it is entirely impossible to use Forgejo Actions for some reason.

> I feel very strongly that it is important for anyone with any level of involvement with the project to be able to easily send documentation pull requests. I agree and I'm quite unhappy that I did not see this problem coming although it was under my nose the whole time. > Proceed with this strategy > * Add a check to skip the preview upload if the secret isn't available And fix Forgejo Actions to make it possible. I think that's the only path forward because Forgejo Actions users will face the same situation. It's one of the unpleasant side effect of dogfooding: when something goes wrong, it stings. > Use Woodpecker until we have a more secure runner that can handle this situation more gracefully I strongly feel that is a last resort, if it is entirely impossible to use Forgejo Actions for some reason.

crystal commented 2023年08月15日 21:49:54 +02:00

And fix Forgejo Actions to make it possible. I think that's the only path forward because Forgejo Actions users will face the same situation. It's one of the unpleasant side effect of dogfooding: when something goes wrong, it stings.

Well, yes, of course. I kind of took for granted that this needs to be fixed eventually.

> And fix Forgejo Actions to make it possible. I think that's the only path forward because Forgejo Actions users will face the same situation. It's one of the unpleasant side effect of dogfooding: when something goes wrong, it stings. Well, yes, of course. I kind of took for granted that this needs to be fixed eventually.

Ghost commented 2023年08月15日 22:10:49 +02:00

I'm unhappy about that situation. But I also agree that, as active Forgejo contributors, it is better to use Forgejo Actions with all the inconveniences that come with it rather than use another CI.

I'm unhappy about that situation. But I also agree that, as active Forgejo contributors, it is better to use Forgejo Actions with all the inconveniences that come with it rather than use another CI.

caesar commented 2023年08月16日 00:43:32 +02:00

Well, I'm glad I asked for help instead of trying to sort it out myself 😀

I have to say I'm not a fan of having to use branches in this repo for PRs, for all the reasons @crystal articulated. In addition to the extra friction for contributors, I'm particularly not a fan of the mess of having extra branches in this repo. Perhaps we can agree on a branch prefix we will all use, such as pr/.

But if it's an interim solution until Forgejo Actions can be improved to support PRs from other repos, I guess we can put up with that for now for the sake of dogfooding.

Well, I'm glad I asked for help instead of trying to sort it out myself 😀 I have to say I'm not a fan of having to use branches in this repo for PRs, for all the reasons @crystal articulated. In addition to the extra friction for contributors, I'm particularly not a fan of the mess of having extra branches in this repo. Perhaps we can agree on a branch prefix we will all use, such as `pr/`. But if it's an interim solution until Forgejo Actions can be improved to support PRs from other repos, I guess we can put up with that for now for the sake of dogfooding.

earl-warren commented 2023年08月16日 07:18:07 +02:00

Added conditional preview (ignored if secrets is not available) and a PR to verify that #7

image

Added conditional preview (ignored if secrets is not available) and a PR to verify that https://codeberg.org/forgejo/docs/pulls/7 

earl-warren commented 2023年08月16日 07:26:57 +02:00

But if it's an interim solution until Forgejo Actions can be improved to support PRs from other repos, I guess we can put up with that for now for the sake of dogfooding.

Thanks for your understanding. I realize it is an inconvenience and I'm hoping that won't last too long.

I'm particularly not a fan of the mess of having extra branches in this repo.

image

"Delete PR branch from PR" was set (it is not by default) to help mitigate the proliferation.

> But if it's an interim solution until Forgejo Actions can be improved to support PRs from other repos, I guess we can put up with that for now for the sake of dogfooding. Thanks for your understanding. I realize it is an inconvenience and I'm hoping that won't last too long. > I'm particularly not a fan of the mess of having extra branches in this repo.  "Delete PR branch from PR" was set (it is not by default) to help mitigate the proliferation.

earl-warren commented 2023年08月16日 07:46:52 +02:00

The preview shows the proof of change https://forgejo.codeberg.page/@docs_pull_5/docs/next/

image

The preview shows the proof of change https://forgejo.codeberg.page/@docs_pull_5/docs/next/