From 0e7d00eee7c9105c7aee9607677062895484351a Mon Sep 17 00:00:00 2001 From: Jakob Arendt <78620868+jakobarendt@users.noreply.github.com> Date: Tue, 4 Jul 2023 11:11:18 +0200 Subject: [PATCH 1/5] Add minimum required access permissions to examplary YAML and corresponding READMEs --- examples/example-01-basics.md | 2 +- examples/quarto-publish-example.yml | 6 ++++++ publish/README.md | 13 ++++++++++--- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/examples/example-01-basics.md b/examples/example-01-basics.md index 02a832a..eef9a6d 100644 --- a/examples/example-01-basics.md +++ b/examples/example-01-basics.md @@ -6,7 +6,7 @@ The simplest workflow using Quarto Actions uses the `setup` and `publish` action 1. **Add the GitHub Actions workflow to your project** - Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. No further changes are needed to the action (in particular, do *not* edit the line below to add a secret to this file. This file has the same permissions as your repository, and might be publicly readable) + Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. Do *not* edit the line below to add a secret to this file. Also uncomment the minimum required access permissions below `runs-on: ubuntu-latest`; a general change in your repository's settings for GitHub actions permissions is **not needed**. 2. **run `quarto publish gh-pages` locally, once** diff --git a/examples/quarto-publish-example.yml b/examples/quarto-publish-example.yml index 05f11d4..a9c3335 100644 --- a/examples/quarto-publish-example.yml +++ b/examples/quarto-publish-example.yml @@ -7,6 +7,12 @@ name: Render and Publish jobs: build-deploy: runs-on: ubuntu-latest + + # Uncomment this when publishing to GitHub Pages + # Minimum required access needed for running the publish@v2 Quarto action + # permissions: + # contents: write + steps: - name: Check out repository uses: actions/checkout@v3 diff --git a/publish/README.md b/publish/README.md index b2a591d..29c47a1 100644 --- a/publish/README.md +++ b/publish/README.md @@ -5,7 +5,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi 2. Add Netlify auth token to your repository's secrets. Go to the repository that will be using this GHA. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `NETLIFY_AUTH_TOKEN`, and for the "Value" field, paste the string you got from step 1. -3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example). +3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example). 4. Add `_publish.yml` to your repository. Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish netlify` locally once. @@ -21,7 +21,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi ## GitHub Pages -1. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example). +1. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example). 2. Head over to your repository on GitHub. Under Settings > Pages > Build and deployment, under source, ensure **Deploy from a branch** is selected. Under the branch option, select the root of the gh-pages branch. @@ -34,6 +34,13 @@ Give this token a memorable name, and note the resulting string (or keep this wi uses: quarto-dev/quarto-actions/publish@v2 with: target: gh-pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions + ``` +5. Configure the minimum required access for the `publish` action to function (see also [quarto-publish-example.yml]()). Add these two lines below and on the same level of indentation as `runs-on:`: + ```yaml + permissions: + contents: write ``` ## RStudio Connect @@ -42,7 +49,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi 2. Add RStudio Connect auth token to your GitHub repository. Go to the GitHub webpage for the repository that will be using this GitHub Action. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `CONNECT_API_KEY`, and for the "Value" field, paste the string you got from step 1. -3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example). +3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example). 4. Add `_publish.yml` to your repository. Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish connect` locally once. From 97f409a56b16579f512ae67cb457ffa8e8f3aec5 Mon Sep 17 00:00:00 2001 From: Jakob Arendt <78620868+jakobarendt@users.noreply.github.com> Date: Tue, 4 Jul 2023 11:18:31 +0200 Subject: [PATCH 2/5] Improvements in text and corrections of typos --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d425e04..dede079 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,15 @@ This repository stores [Github Actions](https://github.com/features/actions) useful for building and publishing [Quarto](https://quarto.org/) documents. -1. [quarto-dev/quarto-actions/setup](https://github.com/quarto-dev/quarto-actions/tree/main/setup) - Install Quarto -2. [quarto-dev/quarto-actions/render](https://github.com/quarto-dev/quarto-actions/tree/main/render) - Render project -3. [quarto-dev/quarto-actions/publish](https://github.com/quarto-dev/quarto-actions/tree/main/publish) - Publish project +1. [quarto-dev/quarto-actions/setup](./setup) - Install Quarto +2. [quarto-dev/quarto-actions/render](./render) - Render project +3. [quarto-dev/quarto-actions/publish](./publish) - Publish project We recommend using `v2` for your actions, and our examples all use `v2`. ## Examples -In [Examples](./examples), you will find some YAML workflow files to serve as templates to be reused as a base for your project. We are also sharing some links to real example Github repositories using Quarto with Github Actions for rendering and deploying documents and projects. If you want to add your repository in the list, we welcome a PR. +In [Examples](./examples), you will find a YAML workflow file to serve as a template to be reused as a base for your project. We are also sharing some links to real example Github repositories using Quarto with Github Actions for rendering and deploying documents and projects. If you want to add your repository in the list, we welcome a PR. ## Release Management @@ -18,5 +18,5 @@ This repository uses [GitHub's recommended release management for actions](https * GitHub releases with tags are used for updates on the actions. * Semantic versioning is used, with major, minor and possibly patch release. -* Major versions (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update to). This means using `quarto-dev/quarto-actions/setup@v2` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/setup@v1.0.2` will pin a specific release. +* Major versions (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update, too). This means using `quarto-dev/quarto-actions/setup@v2` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/setup@v1.0.2` will pin a specific release. * Major version changes (`v1` to `v2`) will often come with breaking changes, and workflows might require manual updates. \ No newline at end of file From c1382a01d8f8fd0135ef4f15ef4f985df5558d51 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Mon, 8 Jan 2024 16:36:43 +0100 Subject: [PATCH 3/5] permissions already added --- examples/quarto-publish-example.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/examples/quarto-publish-example.yml b/examples/quarto-publish-example.yml index 1b28a5e..71dc1b0 100644 --- a/examples/quarto-publish-example.yml +++ b/examples/quarto-publish-example.yml @@ -12,11 +12,6 @@ name: Render and Publish jobs: build-deploy: runs-on: ubuntu-latest - - # Uncomment this when publishing to GitHub Pages - # Minimum required access needed for running the publish@v2 Quarto action - # permissions: - # contents: write steps: - name: Check out repository From 87888b388b0fd237ce61fe52a6f5592e17e7c4bc Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Mon, 8 Jan 2024 16:37:44 +0100 Subject: [PATCH 4/5] wording --- examples/example-01-basics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/example-01-basics.md b/examples/example-01-basics.md index eef9a6d..cabe18d 100644 --- a/examples/example-01-basics.md +++ b/examples/example-01-basics.md @@ -6,7 +6,7 @@ The simplest workflow using Quarto Actions uses the `setup` and `publish` action 1. **Add the GitHub Actions workflow to your project** - Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. Do *not* edit the line below to add a secret to this file. Also uncomment the minimum required access permissions below `runs-on: ubuntu-latest`; a general change in your repository's settings for GitHub actions permissions is **not needed**. + Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. Do *not* edit the line below to add a secret to this file. Also uncomment the minimum required access permissions; a general change in your repository's settings for GitHub actions permissions is **not needed**. 2. **run `quarto publish gh-pages` locally, once** From df6e73ec50968aec22ac226ba32444cd5c31886c Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Mon, 8 Jan 2024 16:39:31 +0100 Subject: [PATCH 5/5] Add new lines --- publish/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/publish/README.md b/publish/README.md index 5e27bb2..9ce27e7 100644 --- a/publish/README.md +++ b/publish/README.md @@ -37,7 +37,9 @@ Give this token a memorable name, and note the resulting string (or keep this wi env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions ``` + 5. Configure the minimum required access for the `publish` action to function (see also [quarto-publish-example.yml]()). Add these two lines below and on the same level of indentation as `runs-on:`: + ```yaml permissions: contents: write