knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
{tic} uses CI client packages ({circle}) for setting up deployment on the CI systems.
On Circle CI, setting up deployment convenient as there is no need to create a SSH key pair for deployment.
When calling circle::use_circle_deploy()
directly (or indirectly via tic::use_tic()
), a so called "user-key" is created and stored in the Circle CI repo.
This key makes it possible to deploy from Circle CI builds to your GitHub repo.
No extra deploy key need to be stored in the GitHub repo.
GitHub Actions offers multiple options related to deployment:
DEPLOY_PAT
secret as r-lib/actions suggestsTo reflect a successful deployment in the repo checks, actions from the GitHub marketplace help. For the actual deployment we recommend to use a SSH key pair. A SSH key can be easily created, is safe to use and when browsing at the "Deploy key" section of a repo, one can directly see if deployment was granted to a CI service for the repository.
To simplify the creation of a SSH key pair for deployment and adding the keys to the appropriate places, {tic} comes with a little helper function use_ghactions_deploy()
.
To use this function, you need a GITHUB_PAT
with public repo scope defined in your .Renviron
.
usethis::create_github_token()
helps setting one up if you haven't done so already.
To update the deployment status in the "environments" menu (next to "release" and "branches") conditionally on the outcome of the "Deployment" stage, one can use the chrnorm/deployment-status
.
Add the following before the "Before Deploy" stage:
- uses: chrnorm/deployment-action@v1.1.1 name: Create GitHub deployment id: deployment with: token: "${{ github.token }}" environment: production
and then this part after the "After Deploy" stage:
- name: Update deployment status (success) if: success() uses: chrnorm/deployment-status@releases/v1 with: token: "${{ github.token }}" target-url: http://my-app-url.com state: "success" deployment_id: ${{ steps.deployment.outputs.deployment_id }} - name: Update deployment status (failure) if: failure() uses: chrnorm/deployment-status@releases/v1 with: token: "${{ github.token }}" target-url: http://my-app-url.com state: "failure" deployment_id: ${{ steps.deployment.outputs.deployment_id }}
{pkgdown} is an R package which builds a documentation wrapper-site of an R package. It collects all the vignettes, function references and metadata information of a package and presents it in an eye-appealing HTML version.
It has become a quasi-standard to provide a {pkgdown} site for an R package. However, it is tedious to update the {pkgdown} site manually on every commit, check whether something has changed and commit the changes. {tic} comes with the ability to automate this process.
The following example shows how {tic} deploys a {pkgdown} site on GitHub Actions.
Remember that you can freely choose your favorite provider for this task.
In tic.yml
file the "before_deploy" and "deploy" stages are redirected to {tic}.
```{yml eval = FALSE} - name: "[Stage] Before Deploy" run: | Rscript -e "tic::before_deploy()"
In the "before_deploy" stage, {tic} will do the following: ```r if (ci_on_ghactions()) { get_stage("before_deploy") %>% add_step(step_setup_ssh()) }
step_setup_ssh()
if the environment variable "BUILD_PKGDOWN"
is set in the CI build.
This step sets up SSH key previously added to the GitHub via tic::use_ghactions_deploy()
.
Argument private_key_name
can be ignored as long as no custom private key name was used during tic::use_ghactions_deploy()
.
If so, then supply it via the private_key_name
argument in do_pkgdown()
.For backward compatibility, the deprecated default "id_rsa"
is supported out of the box.
add_step(step_build_pkgdown())
and add_step(step_push_deploy())
in the "deploy" stage.get_stage("deploy") %>% add_step(step_build_pkgdown()) %>% add_step(step_push_deploy())
step_build_pkgdown()
will build the {pkgdown} site and afterwards (note the pipe
operator chaining the commands), step_push_deploy()
takes care pushing the results to the repo.
By default the site will be pushed to the gh-pages
branch of your repo, keeping the history.
docs/
(default branch) or gh-pages
branchBy default deployment is pushed to the gh-pages
branch.
This has the following advantages:
Deploying to the docs/
directory of the default branch has the following advantages:
The disadvantage is that the default branch will be cluttered by automatic commits that push the changes of the {pkgdown} site to the default branch.
gh-pages
branchBy default, changes to the {pkgdown} site will be added as incremental commits to the gh-pages
branch.
This is useful to keep a history of past versions and to enable a release and dev version of the site.
To have this feature, set
development: mode: auto
in your _pkgdown.yml
file.
See ?pkgdown::build_site()
for more information.
If you only want to have one version of your {pkgdown} site and not fill your repo with many commits in the gh-pages
branch, you can use do_pkgdown(orphan = TRUE)
.
This will wipe all commits of this branch on every CI run so that there is only one commit corresponding to the latest version of your pkgdown site.
The step_push_deploy()
step has the ability to restrict the files that are committed and pushed.
This can be very useful for conditionally pushing documentation files like NEWS
or man/
and NAMESPACE
if these are automatically created during the CI run.
In the following example, these files are created/updated by calling devtools::document()
.
The commit_paths
argument in step_push_deploy()
decides which files are committed and pushed:
get_stage("before_deploy") %>% add_step(step_setup_ssh()) get_stage("deploy") %>% add_code_step(devtools::document(roclets = c("rd", "collate", "namespace"))) %>% add_step(step_push_deploy(commit_paths = c("NAMESPACE", "man/*")))
Applying this idea depends on your overall R package development strategy: Commit files like /man/
and NAMESPACE
directly or let them be created during the CI run?
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.