Set `CARGO_GENERATE_PAT` using a maintainer's token

[BD103]

This is targeted towards @alice-i-cecile or @mockersf, since they are owners of this org and have write permissions for this repo.

---

1. Go to https://github.com/settings/tokens?type=beta and click "Generate new token".
2. On the setup screen, set the name to "bevy_quickstart_cargo_generate" (or anything else that reminds you what it is).
3. Set the expiration date to "Custom..." and choose a date 1 year in the future. (Github won't let you set it farther than that!) In a year, you'll have to regenerate this token.
4. Set the description to "Used to automatically updated the cargo-generate branch in the bevy_quickstart repository." (Or anything else! You choose!)
5. Set the "Resource owner" as "TheBevyFlock", since that's where bevy_quickstart lives.
6. Under "Repository access", click "Only select repositories" and select "bevy_quickstart" from the dropdown.
7. If you did everything correctly, it should look like this:

8. Great! Next, scroll down to "Permissions" and click the "Repository permissions" box.
9. Set "Contents" to "Read and write" and "Workflows" to "Read and write". "Metadata" will automatically enable itself to be "Read-only", but the rest should remain "No access".
10. Scroll down to "Overview". If you did everything correctly, it should look like this:

11. Click "Generate token" and copy the token displayed on screen.
12. Navigate to https://github.com/TheBevyFlock/bevy_quickstart/settings/secrets/actions and click "New repository secret".
13. Set the name to "CARGO_GENERATE_PAT" and paste your copied token into the "Secret" box.
14. If you did everything correctly, it should look like this:

15. Click "Add secret". Everything should be setup now!
16. To test that it now works, navigate to https://github.com/TheBevyFlock/bevy_quickstart/actions/workflows/cargo-generate.yaml, click "Run workflow", then click the new green "Run workflow" button.
17. The spawned workflow should either pass or log an error about merge conflicts. You're good to go!

Regenerating the PAT

1. Go back to https://github.com/settings/tokens?type=beta and click on the token you previously generated. It should be named "bevy_quickstart_cargo_generate".
2. Click the red "Regenerate token" button.
3. Set the expiration date to another year in the future.
4. Copy the new token to your clipboard.
5. Go back to https://github.com/TheBevyFlock/bevy_quickstart/settings/secrets/actions, find "CARGO_GENERATE_PAT" under "Repository secrets", and click the edit button.
6. Paste the new token into the box and click "Update secret".
7. Congrats, you're done! See you next year :)

[mockersf]

my opinion on this is that it should be reworked to not need a token...

[janhohenheim]

@mockersf how do you push a branch in a workflow without a token?

[BD103]

my opinion on this is that it should be reworked to not need a token...

I don't believe that's possible. This action needs write permissions to "Workflow", which is impossible to set through the usual permissions table in the workflow file due to security reasons. Write permissions to workflow is required because this action can push to the .github/workflows folder, which is not allowed with normal "Content" write access.

[mockersf]

@mockersf how do you push a branch in a workflow without a token?

Actions have a token provided by default that can push to branches

This action needs write permissions to "Workflow", which is impossible to set through the usual permissions table in the workflow file due to security reasons.

If the issue is only workflows, you could maintain them in another folder in the generate branch and move them to the one GitHub expect with a hook in cargo-generate. Or consider that when a workflow need updating, it will be a manual action like a merge conflict. Or using actions to automatically update it is the wrong way around

[BD103]

If the issue is only workflows, you could maintain them in another folder in the generate branch and move them to the one GitHub expect with a hook in cargo-generate. Or consider that when a workflow need updating, it will be a manual action like a merge conflict.

I'm not sure I understand, could you clarify what you mean?

[mockersf]

I think this should not be part of the template. You're exposing template management things to template users, it should be separate.

If you really want it, I think there are ways around needing a PAT:

• have the user workflows in a separate folder than the template management workflows, and move them as needed when instantiating the template
• avoid writing to the workflows folder from an automatic updates, and handle those manually

But in my opinion, this workflow should be removed.

[janhohenheim]

@mockersf the user won't receive this workflow when using cargo-generate, which is our recommended way of receiving the template. Same for when bevy new is supported in the CLI. Having the user workflows in a separate folder would be a bit tricky since we dogfood them. I don't think GitHub will ever execute them when they are outside the .github directory, right?

@BD103 is there a way to get this working without a maintainer's token? I can gladly contribute one of mine if needed, but that of course would only work until we are upstreamed. Or maybe the action could submit a PR to the branch? Would that require fewer permissions?

[BD103]

@BD103 is there a way to get this working without a maintainer's token?

The only ways around this that I can think of is to create a custom GitHub app, which is overkill and a lot of setup, or to make a local cron job on someone's computer run the update manually, which is painful to maintain.

In summary, no. I think GitHub Actions is the best path forward here, and renewing a token once per year is a worthy price to pay.

[janhohenheim]

Yeah, agreed. @alice-i-cecile, I'd be happy if you could chime in here as well. @BD103 if getting a maintainer token really is out of the question, I can set up a cron job on a Fedora server I own and will continue owning for the foreseeable future, as I run all my tiny websites on it. That way, there is no extra cost, as that thing is running anyways. I could then also give you access to it. It's a bit meh, but it's at least better than (forgetting to) manually update the cargo-generate branch. Plus, I think that once it's set up, it should not really need any significant maintenance :)

[alice-i-cecile]

I really don't have strong opinions or expertise here either way, sorry!

[mockersf]

when using cargo-generate, which is our recommended way of receiving the template. Same for when bevy new is supported in the CLI.

We should stick to keep the cargo-generate version, and don't keep the github template compatibility. It has many issues, first of which is that it just copy the template without any possibility of customisation, making it a bit awkward to document the template itself as it will end up in the users projects.

I think keeping the two versions and having some automation keep them in sync is a bad idea.

The Bevy CLI is being worked on and could realistically have template instantiation before the next jam, let's make the compatible template version the only one now and look into improving template creation interactivity

[benfrankel]

The other reason that cargo-generate is currently a separate branch is so that rust-analyzer and the ci.yaml / release.yaml workflows are functional in the main branch. We have Liquid template syntax like {{ project-name }} etc. in the workflow files, Cargo.toml, and some other places, which would be a syntax error.

We may be able to rename the workflow files to *.yaml.liquid so that GitHub doesn't run them, then add template-local *.yaml workflow files (that cargo-generate will delete) that use cargo-generate to clone the template before running the actual workflow. A similar thing might work for rust-analyzer as well, e.g. if we move Cargo.toml to Cargo.toml.liquid and have an instantiated copy of it named Cargo.toml that gets deleted by cargo-generate.

[alice-i-cecile]

Removing the Github Template functionality is fine by me: I've always found it quite frustrating and fragile.

[janhohenheim]

I'm all in favor of dropping support for the non-cargo-generate workflow, but I would like to make sure that our dev experience does not suffer in the process. I have two concerns:

A) If the cargo generate version is the only one, I guess the CI needs to instantiate the template? I'm not sure if cargo-generate supports a fully noninteractive workflow for our case. If it does, how do we run the generated workflows? B) I also find the idea a bit clumsy of having to work on the template itself by first running cargo generate, changing things, and then backporting those changes to the repo that is not itself buildable.

I guess we could fix both of these by creating a buildable branch and then running git merge on main, which would effectively swap our two current branches.

If we have an answer for these, I'm fine with closing this issue

[BD103]

In CI you can use yes, printf, or something similar to automated user input. (Source) It’s a bit flaky, but it works.

[janhohenheim]

@BD103 that sounds good enough, thanks. Do you know if we can run workflows of the instantiated project? If we have a workflow to instantiate the template with cargo-generate, that will result in a further workflows being generated. Can we execute those somehow? I guess swapping the main and the cargo-generate branch would also solve this, but I feel like the vibe here is against that.

[BD103]

Yes, actually! It's possible to execute local actions and workflows, but you need to checkout the repository in order to do so. This implies that we could generate our own actions before running them! I'm not at a computer right now, but tomorrow I may be able to create a demo.

[janhohenheim]

@BD103 that's really nice! That takes care of my issue A) then :)

[janhohenheim]

Closing this in favor of https://github.com/TheBevyFlock/bevy_quickstart/pull/305