Skip to content

Improve examplary YAML file and correct typos #83

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

Merged
merged 6 commits into from
Jan 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@

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

This repository uses [GitHub's recommended release management for actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions):

* 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/[email protected]` 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/[email protected]` will pin a specific release.
* Major version changes (`v1` to `v2`) will often come with breaking changes, and workflows might require manual updates.
2 changes: 1 addition & 1 deletion examples/example-01-basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -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; a general change in your repository's settings for GitHub actions permissions is **not needed**.

2. **run `quarto publish gh-pages` locally, once**

Expand Down
1 change: 1 addition & 0 deletions examples/quarto-publish-example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ name: Render and Publish
jobs:
build-deploy:
runs-on: ubuntu-latest

steps:
- name: Check out repository
uses: actions/checkout@v4
Expand Down
15 changes: 12 additions & 3 deletions publish/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -34,6 +34,15 @@ 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
```

## Posit Connect
Expand All @@ -42,7 +51,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi

2. Add Posit 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.

Expand Down