R/jobs.R

In cloudyr/travisci: Travis-CI API Client Package

#' @title Get Job
#' @description Retrieve a Travis-CI job
#' @details \code{get_job} retrieves a list of details about a given job. \code{cancel_job} cancels and \code{restart_job} restarts a given job.
#' @param job A numeric job ID, or an object of class \dQuote{travis_job}.
#' @param ... Additional arguments passed to \code{\link{travisHTTP}}.
#' @return A list.
#' @examples
#' \dontrun{
#' # authenticate based on Sys.setenv("GITHUB_TOKEN" = "sometoken")
#' auth_travis()
#'
#' # get a job
#' get_job("12345")
#'
#' # cancel a job
#' cancel_job("12345")
#'
#' # restart a job
#' restart_job("1235")
#' }
#' @seealso \code{\link{get_annotations}}, \code{\link{get_logs}}
#' @export
get_job <- function(job, ...) {
    if (inherits(job, "travis_job")) {
        job <- job$id
    }
    out <- travisHTTP("GET", path = paste0("/jobs/", job), ...)
    structure(list(job = `class<-`(out$job, "travis_job"),
                   commit = `class<-`(out$commit, "travis_commit"),
                   annotations = lapply(out$annotations, `class<-`, "travis_annotation")))
}

#' @export
#' @rdname get_job
cancel_job <- function(job, ...) {
    travisHTTP("POST", path = paste0("/jobs/", job, "/cancel"), ...)
}

#' @export
#' @rdname get_job
restart_job <- function(job, ...) {
    travisHTTP("POST", path = paste0("/jobs/", job, "/restart"), ...)
}


#' @title Job Annotations
#' @description Retrieve and create job Travis CI annotations
#' @details \code{get_annotations} retrieves any annotations attached to a Travis CI job. \code{create_annotation} creates a new annotation for a job. Note: As of October, 2015 support for annotations is considered \dQuote{experimental}.
#' @param job A numeric job ID, or an object of class \dQuote{travis_job}.
#' @param body A list of arguments specifying the annotation. See \href{http://docs.travis-ci.com/api/#annotations}{API documentation} for details.
#' @param ... Additional arguments passed to \code{\link{travisHTTP}}.
#' @return A list.
#' @seealso \code{\link{get_job}}
#' @examples
#' \dontrun{
#' # authenticate based on Sys.setenv("GITHUB_TOKEN" = "sometoken")
#' auth_travis()
#'
#' # get annotations for a job
#' get_annotations(12345)
#'
#' # create a new annotation
#' create_annotations(12345, body = list(description = "job description", status = "passed"))
#' }
#' @seealso \code{\link{get_job}}, \code{\link{get_logs}}
#' @export
get_annotations <- function(job, ...) {
    if (inherits(job, "travis_job")) {
        job <- job$id
    }
    travisHTTP("GET", path = paste0("/jobs/", job, "/annotations"), ...)
}

#' @export
#' @rdname get_annotations
create_annotation <- function(job, body = list(), ...) {
    if (inherits(job, "travis_job")) {
        job <- job$id
    }
    travisHTTP("GET", path = paste0("/jobs/", job, "/annotations"), body = body, encode = "json", ...)
}


#' @title Job Logs
#' @description Retrieve logs for Travis CI jobs
#' @details This can retrieve logs for a given job or a specific log by its job ID.
#' @param job A numeric job ID, or an object of class \dQuote{travis_job}. Must specify \code{job} or \code{log}.
#' @param log A numeric log ID. Must specify \code{job} or \code{log}.
#' @param ... Additional arguments passed to \code{\link{travisHTTP}}.
#' @return A list.
#' @seealso \code{\link{get_job}}
#' @examples
#' \dontrun{
#' # authenticate based on Sys.setenv("GITHUB_TOKEN" = "sometoken")
#' auth_travis()
#'
#' # get logs for a job
#' get_logs(job = 12345)
#' }
#' @seealso \code{\link{get_job}}, \code{\link{get_annotations}}
#' @export
get_logs <- function(job, log, ...) {
    if (!missing(log)) {
        travisHTTP("GET", path = paste0("/logs/", log), ...)
    } else {
        if (inherits(job, "travis_job")) {
            job <- job$id
        }
        travisHTTP("GET", path = paste0("/jobs/", job, "/logs"), ...)
    }
}