# Advanced usage and {tic} integration

# Overview

This vignette covers advanced workflows with {circle} and how to integrate them with {tic}. It assumes you have completed the basics in the “Getting Started” vignette.

# Advanced API usage

## Pipelines, workflows, and jobs

Use the high-level helpers to browse recent activity and drill down into details.

    # list recent pipelines for a repo
    circle::get_pipelines(owner = "ropensci", repo = "circle")

    # list workflows of a given pipeline id
    # (replace with a pipeline id from the previous result)
    circle::get_workflows(pipeline_id = "<pipeline-id>")

    # list jobs of a workflow
    circle::get_jobs(workflow_id = "<workflow-id>")

## Restarting and retrying

    # trigger a new build (pipeline) for a branch
    circle::new_build(branch = "main")

    # retry a workflow (if supported by the API)
    circle::retry_workflow(workflow_id = "<workflow-id>")

## Artifacts and logs

    # list and download build artifacts
    arts <- circle::get_build_artifacts(job_number = 123)
    arts

## Environment variables

    # read and set environment variables in a project context
    circle::get_env_vars(owner = "ropensci", repo = "circle")
    circle::set_env_var(owner = "ropensci", repo = "circle", name = "MY_TOKEN", value = "***")

# Deep integration with {tic}

The {tic} package provides a CI-agnostic DSL and ready-made templates for CircleCI. Combine {circle} (API client) with {tic} (workflow setup) to automate checks and deployments.

## Initialize CircleCI with {tic}

    # writes .circleci/config.yml and a tic.R with sensible defaults
    tic::use_circle_yml()

    # or go through the interactive wizard
    tic::use_tic()

## Customize stages

Edit `tic.R` to add or modify stages. For example, enable pkgdown deployment only on tags:

    if (ci_has_env("BUILD_PKGDOWN") && tic::on_tag()) {
      get_stage("deploy") %>>% {
        tic::step_do_call("pkgdown::build_site")
        tic::step_do_call("tic::do_pkgdown")
      }
    }

## Authentication and permissions

For deployments, set up a user key once using {circle}:

    circle::use_circle_deploy()

This adds a user key on CircleCI and registers the corresponding key in your GitHub account, so that `tic::deploy()` can push the pkgdown site to `gh-pages`.

## Making vignettes robust on CI/CRAN

Ensure vignettes build in non-interactive environments by guarding heavy code (already enabled at the top of this vignette):

    knitr::opts_chunk$set(
      eval = !identical(Sys.getenv("CI"), "true") && !identical(Sys.getenv("CRAN"), "true")
    )

# See also

- Getting Started (introductory guide)
- Using {circle} with {tic} (step-by-step setup walkthrough)