lib/trav3.rb in trav3-0.4.1 vs lib/trav3.rb in trav3-0.5.0

- old
+ new

@@ -12,10 +12,72 @@ # Trav3 project namespace module Trav3 # An abstraction for the Travis CI v3 API # + # + # You can get started with the following. + # + # ```ruby + # require 'trav3' + # project = Trav3::Travis.new("name/example") + # ``` + # + # When you instantiate an instance of `Travis` + # you get some default headers and default options. + # + # #### Default Options + # + # * `limit: 25` - for limiting data queries to 25 items at most + # + # Options can be changed via the {#options} getter method which will give you a + # {Options} instance. All changes to it affect the options that the `Travis` + # instance will submit in url requests. + # + # #### Default Headers + # + # * `'Content-Type': 'application/json'` + # * `'Accept': 'application/json'` + # * `'Travis-API-Version': 3` + # + # Headers can be changed via the {#headers} getter method which will give you a + # {Headers} instance. All changes to it affect the headers that the `Travis` + # instance will submit in url requests. + # + # #### General Usage + # + # ```ruby + # project.owner + # project.owner("owner") + # project.repositories + # project.repositories("owner") + # project.repository + # project.repository("owner/repo") + # project.builds + # project.build(12345) + # project.build_jobs(12345) + # project.job(1234) + # project.log(1234) + # + # # API Request Options + # project.options.build({limit: 25}) + # + # # Pagination + # builds = project.builds + # builds.page.next + # builds.page.first + # builds.page.last + # + # # Recommended inspection + # builds.keys + # builds.dig("some_key") + # + # # Follow `@href` + # repositories = project.repositories("owner")['repositories'] + # repositories.first.follow + # ``` + # # @author Daniel P. Clark https://6ftdan.com # @!attribute [r] api_endpoint # @return [String] API endpoint # @!attribute [r] options # @return [Options] Request options object @@ -111,37 +173,65 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark/active # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.active + # # or + # travis.active('danielpclark') + # ``` + # # GET <code>/owner/{user.login}/active</code> # # Template Variable Type Description # user.login String Login set on GitHub. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark/active # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.active + # # or + # travis.active('danielpclark') + # ``` + # # GET <code>/owner/{organization.login}/active</code> # # Template Variable Type Description # organization.login String Login set on GitHub. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/travis-ci/active # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.active('travis-ci') + # ``` + # # GET <code>/owner/github_id/{owner.github_id}/active</code> # # Template Variable Type Description # owner.github_id Integer User or organization id set on GitHub. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/github_id/639823/active # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.active(639_823) + # ``` + # # @param owner [String] username, organization name, or github id # @return [Success, RequestError] def active(owner = username) number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}/active") get("#{without_repo}/owner/#{owner}/active") @@ -182,20 +272,43 @@ # beta_feature.id Integer Value uniquely identifying the beta feature. # Accepted Parameter Type Description # beta_feature.id Integer Value uniquely identifying the beta feature. # beta_feature.enabled Boolean Indicates if the user has this feature turned on. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # + # # Enable comic-sans for user id 119240 + # travis.beta_feature(:enable, 3, 119_240) + # + # # Disable comic-sans for user id 119240 + # travis.beta_feature(:disable, 3, 119_240) + # ``` + # # **Delete** # # This will delete a user's beta feature. # # DELETE <code>/user/{user.id}/beta_feature/{beta_feature.id}</code> # # Template Variable Type Description # user.id Integer Value uniquely identifying the user. # beta_feature.id Integer Value uniquely identifying the beta feature. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # + # # Disable comic-sans via delete for user id 119240 + # travis.beta_feature(:delete, 3, 119_240) + # ``` + # # @param action [Symbol] either `:enable`, `:disable` or `:delete` # @param beta_feature_id [String, Integer] id for the beta feature # @param user_id [String] user id # @return [Success, RequestError] def beta_feature(action, beta_feature_id, user_id) @@ -231,10 +344,16 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /user/119240/beta_features # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.beta_features(119_240) + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @param user_id [String, Integer] user id # @return [Success, RequestError] def beta_features(user_id) @@ -286,20 +405,32 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/branch/master # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.branch('master') + # ``` + # # GET <code>/repo/{repository.slug}/branch/{branch.name}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # branch.name String Name of the git branch. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/branch/master # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.branch('master') + # ``` + # # @param name [String] the branch name for the current repository # @return [Success, RequestError] def branch(name) get("#{with_repo}/branch/#{name}") end @@ -346,10 +477,17 @@ # Example: GET /repo/891/branches?limit=5&exists_on_github=true # # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order. # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5, exists_on_github: true}) + # travis.branches + # ``` + # # GET <code>/repo/{repository.slug}/branches</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description @@ -363,10 +501,17 @@ # Example: GET /repo/rails%2Frails/branches?limit=5&exists_on_github=true # # **Sortable by:** <code>name</code>, <code>last_build</code>, <code>exists_on_github</code>, <code>default_branch</code>, append <code>:desc</code> to any attribute to reverse order. # The default value is <code>default_branch</code>,<code>exists_on_github</code>,<code>last_build:desc</code>. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5, exists_on_github: true}) + # travis.branches + # ``` + # # @return [Success, RequestError] def branches get("#{with_repo}/branches#{opts}") end @@ -402,10 +547,17 @@ # broadcast.active [Boolean] Filters broadcasts by whether or not the brodacast should still be displayed. # include [String] List of attributes to eager load. # # Example: GET /broadcasts # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.broadcasts + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @return [Success, RequestError] def broadcasts get("#{without_repo}/broadcasts") @@ -469,10 +621,16 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /build/86601346 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.build(351_778_872) + # ``` + # # **Cancel** # # This cancels a currently running build. It will set the build and associated jobs to "state": "canceled". # # POST <code>/build/{build.id}/cancel</code> @@ -480,10 +638,17 @@ # Template Variable Type Description # build.id Integer Value uniquely identifying the build. # # Example: POST /build/86601346/cancel # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.build(478_772_528, :cancel) + # ``` + # # **Restart** # # This restarts a build that has completed or been canceled. # # POST <code>/build/{build.id}/restart</code> @@ -491,10 +656,17 @@ # Template Variable Type Description # build.id Integer Value uniquely identifying the build. # # Example: POST /build/86601346/restart # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.build(478_772_528, :restart) + # ``` + # # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param build_id [String, Integer] the build id number # @param option [Symbol] options for :cancel or :restart # @raise [TypeError] if given build id is not a number @@ -563,10 +735,18 @@ # # Example: GET /builds?limit=5 # # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.builds(false) + # ``` + # # **Find** # # This returns a list of builds for an individual repository. It is possible to use the repository id or slug in the request. The result is paginated. Each request will return 25 results. # # GET <code>/repo/{repository.id}/builds</code> @@ -591,10 +771,17 @@ # # Example: GET /repo/891/builds?limit=5 # # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5}) + # travis.builds + # ``` + # # GET <code>/repo/{repository.slug}/builds</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # @@ -615,13 +802,24 @@ # # Example: GET /repo/rails%2Frails/builds?limit=5 # # **Sortable by:** <code>id</code>, <code>started_at</code>, <code>finished_at</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5}) + # travis.builds + # ``` + # + # @note requests may require an authorization token set in the headers. See: {authorization=} + # + # @param repo [Boolean] If true get repo builds, otherwise get user builds # @return [Success, RequestError] - def builds - get("#{with_repo}/builds#{opts}") + def builds(repo = true) + repo and return get("#{with_repo}/builds#{opts}") + get("#{without_repo}/builds#{opts}") end # A list of jobs. # # ## Attributes @@ -664,10 +862,16 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /build/86601346/jobs # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.build_jobs(86_601_346) + # ``` + # # **For Current User** # # This returns a list of jobs a current user has access to. # # GET <code>/jobs</code> @@ -687,14 +891,25 @@ # Example: GET /jobs?limit=5 # # **Sortable by:** <code>id</code>, append <code>:desc</code> to any attribute to reverse order. # The default value is id:desc. # - # @param build_id [String, Integer] the build id number + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.build_jobs(false) + # ``` + # + # @note requests may require an authorization token set in the headers. See: {authorization=} + # + # @param build_id [String, Integer, Boolean] the build id number. If falsey then get all jobs for current user # @return [Success, RequestError] def build_jobs(build_id) - get("#{without_repo}/build/#{build_id}/jobs") + build_id and return get("#{without_repo}/build/#{build_id}/jobs") + get("#{without_repo}/jobs#{opts}") end # A list of caches. # # If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters. @@ -719,18 +934,34 @@ # -H "Travis-API-Version: 3" \ # -H "Authorization: token xxxxxxxxxxxx" \ # https://api.travis-ci.com/repo/1234/caches?branch=master # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({branch: :master}) + # travis.caches + # ``` + # # ```bash # curl \ # -H "Content-Type: application/json" \ # -H "Travis-API-Version: 3" \ # -H "Authorization: token xxxxxxxxxxxx" \ # https://api.travis-ci.com/repo/1234/caches?match=linux # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({match: :linux}) + # travis.caches + # ``` + # # GET <code>/repo/{repository.id}/caches</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # Query Parameter Type Description @@ -767,10 +998,18 @@ # -H "Travis-API-Version: 3" \ # -H "Authorization: token xxxxxxxxxxxx" \ # https://api.travis-ci.com/repo/1234/caches?branch=master # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({branch: :master}) + # travis.caches(:delete) + # ``` + # # DELETE <code>/repo/{repository.id}/caches</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # @@ -786,12 +1025,14 @@ # @note DELETE requests require an authorization token set in the headers. See: {authorization=} # # @param delete [Boolean] option for deleting cache(s) # @return [Success, RequestError] def caches(delete = false) - delete and return without_limit { delete("#{with_repo}/caches#{opts}") } - get("#{with_repo}/caches") + without_limit do + delete and return delete("#{with_repo}/caches#{opts}") + get("#{with_repo}/caches#{opts}") + end end # An individual cron. There can be only one cron per branch on a repository. # # If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters. @@ -831,19 +1072,33 @@ # Template Variable Type Description # cron.id Integer Value uniquely identifying the cron. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.cron(id: 78_199) + # ``` + # # **Delete** # # This deletes a single cron. # # DELETE <code>/cron/{cron.id}</code> # # Template Variable Type Description # cron.id Integer Value uniquely identifying the cron. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.cron(id: 78_199, delete: true) + # ``` + # # **For Branch** # # This returns the cron set for the specified branch for the specified repository. It is possible to use the repository id or slug in the request. # # GET <code>/repo/{repository.id}/branch/{branch.name}/cron</code> @@ -854,20 +1109,34 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/branch/master/cron # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.cron(branch_name: 'master') + # ``` + # # GET <code>/repo/{repository.slug}/branch/{branch.name}/cron</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # branch.name String Name of the git branch. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/branch/master/cron # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.cron(branch_name: 'master') + # ``` + # # **Create** # # This creates a cron on the specified branch for the specified repository. It is possible to use the repository id or slug in the request. Content-Type MUST be set in the header and an interval for the cron MUST be specified as a parameter. # # ```bash @@ -877,10 +1146,17 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "cron.interval": "monthly" }' \ # https://api.travis-ci.com/repo/1234/branch/master/cron # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.cron(branch_name: 'master', create: { 'interval' => 'monthly' }) + # ``` + # # POST <code>/repo/{repository.id}/branch/{branch.name}/cron</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # branch.name String Name of the git branch. @@ -958,10 +1234,18 @@ # limit Integer How many crons to include in the response. Used for pagination. # offset Integer How many crons to skip before the first entry in the response. Used for pagination. # # Example: GET /repo/891/crons?limit=5 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.crons + # ``` + # # GET <code>/repo/{repository.slug}/crons</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description @@ -969,29 +1253,51 @@ # limit Integer How many crons to include in the response. Used for pagination. # offset Integer How many crons to skip before the first entry in the response. Used for pagination. # # Example: GET /repo/rails%2Frails/crons?limit=5 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.crons + # ``` + # # @return [Success, RequestError] def crons - get("#{with_repo}/crons") + get("#{with_repo}/crons#{opts}") end # POST <code>/repo/{repository.id}/email_subscription</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/email_subscription # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.email_resubscribe + # ``` + # # POST <code>/repo/{repository.slug}/email_subscription</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/email_subscription # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.email_resubscribe + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @return [Success, RequestError] def email_resubscribe post("#{with_repo}/email_subscription") @@ -1002,17 +1308,31 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: DELETE /repo/891/email_subscription # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.email_unsubscribe + # ``` + # # DELETE <code>/repo/{repository.slug}/email_subscription</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: DELETE /repo/rails%2Frails/email_subscription # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.email_unsubscribe + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @return [Success, RequestError] def email_unsubscribe delete("#{with_repo}/email_subscription") @@ -1058,10 +1378,17 @@ # env_var.id String The environment variable id. # id String Alias for env_var.id. # include [String] List of attributes to eager load. # repository.id Integer Value uniquely identifying the repository. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c') + # ``` + # # GET <code>/repo/{repository.slug}/env_var/{env_var.id}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # env_var.id String The environment variable id. @@ -1069,10 +1396,17 @@ # env_var.id String The environment variable id. # id String Alias for env_var.id. # include [String] List of attributes to eager load. # repository.id Integer Value uniquely identifying the repository. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c') + # ``` + # # **Update** # # This updates a single environment variable. It is possible to use the repository id or slug in the request. # # Use namespaced params in the request body to pass the new environment variable: @@ -1084,10 +1418,17 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "env_var.value": "bar", "env_var.public": false }' \ # https://api.travis-ci.com/repo/1234/{env_var.id} # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', update: { value: 'bar', public: false }) + # ``` + # # PATCH <code>/repo/{repository.id}/env_var/{env_var.id}</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # env_var.id String The environment variable id. @@ -1114,16 +1455,30 @@ # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # env_var.id String The environment variable id. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', delete: true) + # ``` + # # DELETE <code>/repo/{repository.slug}/env_var/{env_var.id}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # env_var.id String The environment variable id. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_var('76f9d8bd-642d-47ed-9f35-4c25eb030c6c', delete: true) + # ``` + # # @overload env_var(env_var_id) # Gets current env var # @param env_var_id [String] environment variable id # @overload env_var(env_var_id, action: params) # Performs action per specific key word argument @@ -1163,19 +1518,33 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/env_vars # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_vars + # ``` + # # GET <code>/repo/{repository.slug}/env_vars</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/env_vars # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_vars + # ``` + # # **Create** # # This creates an environment variable for an individual repository. It is possible to use the repository id or slug in the request. # # Use namespaced params in the request body to pass the new environment variables: @@ -1187,10 +1556,17 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "env_var.name": "FOO", "env_var.value": "bar", "env_var.public": false }' \ # https://api.travis-ci.com/repo/1234/env_vars # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.env_vars(name: 'FOO', value: 'bar', public: false) + # ``` + # # POST <code>/repo/{repository.id}/env_vars</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # Accepted Parameter Type Description @@ -1252,10 +1628,18 @@ # Template Variable Type Description # installation.github_id Integer The installation's id on GitHub. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.installation(617_754) + # ``` + # # @param installation_id [String, Integer] GitHub App installation id # @return [Success, RequestError] def installation(installation_id) validate_number installation_id @@ -1307,10 +1691,17 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /job/86601347 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.job(351_778_875) + # ``` + # # **Cancel** # # This cancels a currently running job. # # POST <code>/job/{job.id}/cancel</code> @@ -1318,10 +1709,17 @@ # Template Variable Type Description # job.id Integer Value uniquely identifying the job. # # Example: POST /job/86601347/cancel # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.job(351_778_875, :cancel) + # ``` + # # **Restart** # # This restarts a job that has completed or been canceled. # # POST <code>/job/{job.id}/restart</code> @@ -1329,10 +1727,17 @@ # Template Variable Type Description # job.id Integer Value uniquely identifying the job. # # Example: POST /job/86601347/restart # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.job(351_778_875, :restart) + # ``` + # # **Debug** # # This restarts a job in debug mode, enabling the logged-in user to ssh into the build VM. Please note this feature is only available on the travis-ci.com domain, and those repositories on the travis-ci.org domain for which the debug feature is enabled. See this document for more details. # # POST <code>/job/{job.id}/debug</code> @@ -1340,11 +1745,20 @@ # Template Variable Type Description # job.id Integer Value uniquely identifying the job. # # Example: POST /job/86601347/debug # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.job(351_778_875, :debug) + # ``` + # # @note POST requests require an authorization token set in the headers. See: {authorization=} + # @note **Debug** is only available on the travis-ci.com domain, and those repositories on the travis-ci.org domain for which the debug feature is enabled. # # @param job_id [String, Integer] the job id number # @param option [Symbol] options for :cancel, :restart, or :debug # @return [Success, RequestError] def job(job_id, option = nil) @@ -1397,19 +1811,35 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/key_pair # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair + # ``` + # # GET <code>/repo/{repository.slug}/key_pair</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/key_pair # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair + # ``` + # # **Create** # # Creates a new key pair. # # ```bash @@ -1419,10 +1849,18 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "key_pair.description": "FooBar", "key_pair.value": "xxxxx"}' \ # https://api.travis-ci.com/repo/1234/key_pair # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair(create: { description: 'FooBar', value: OpenSSL::PKey::RSA.generate(2048).to_s }) + # ``` + # # POST <code>/repo/{repository.id}/key_pair</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # Accepted Parameter Type Description @@ -1452,10 +1890,18 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "key_pair.description": "FooBarBaz" }' \ # https://api.travis-ci.com/repo/1234/key_pair # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair(update: { description: 'FooBarBaz' }) + # ``` + # # PATCH <code>/repo/{repository.id}/key_pair</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # Accepted Parameter Type Description @@ -1483,17 +1929,33 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: DELETE /repo/891/key_pair # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair(delete: true) + # ``` + # # DELETE <code>/repo/{repository.slug}/key_pair</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: DELETE /repo/rails%2Frails/key_pair # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair(delete: true) + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # @note API enpoint needs to be set to `https://api.travis-ci.com` See: {api_endpoint=} # # @overload key_pair() # Gets current key_pair if any @@ -1549,19 +2011,35 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/key_pair/generated # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair_generated + # ``` + # # GET <code>/repo/{repository.slug}/key_pair/generated</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/key_pair/generated # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair_generated + # ``` + # # **Create** # # Generate a new key pair, replacing the previous one. # # POST <code>/repo/{repository.id}/key_pair/generated</code> @@ -1569,17 +2047,33 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/key_pair/generated # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair_generated(:create) + # ``` + # # POST <code>/repo/{repository.slug}/key_pair/generated</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/key_pair/generated # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.api_endpoint = 'https://api.travis-ci.com' + # travis.authorization = 'xxxx' + # travis.key_pair_generated(:create) + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @param action [String, Symbol] defaults to getting current key pair, use `:create` if you would like to generate a new key pair # @return [Success, RequestError] def key_pair_generated(action = :get) @@ -1603,10 +2097,16 @@ # # POST <code>/lint</code> # # Example: POST /lint # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.lint(File.read('.travis.yml')) + # ``` + # # @param yaml_content [String] the contents for the file `.travis.yml` # @return [Success, RequestError] def lint(yaml_content) validate_string yaml_content @@ -1647,10 +2147,18 @@ # curl -H "Travis-API-Version: 3" \ # -H "Accept: text/plain" \ # -H "Authorization: token xxxxxxxxxxxx" \ # https://api.travis-ci.org/job/{job.id}/log # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.log(351_778_875) + # # or + # travis.log(351_778_875, :text) + # ``` + # # The default response type is application/json, and will include additional meta data such as @type, @representation etc. (see [https://developer.travis-ci.org/format](https://developer.travis-ci.org/format)). # # GET <code>/job/{job.id}/log</code> # # Template Variable Type Description @@ -1680,10 +2188,17 @@ # curl -X DELETE \ # -H "Travis-API-Version: 3" \ # -H "Authorization: token xxxxxxxxxxxx" \ # https://api.travis-ci.org/job/{job.id}/log # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.log(478_772_530, :delete) + # ``` + # # DELETE <code>/job/{job.id}/log</code> # # Template Variable Type Description # job.id Integer Value uniquely identifying the job. # @@ -1735,20 +2250,34 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # limit Integer How many messages to include in the response. Used for pagination. # offset Integer How many messages to skip before the first entry in the response. Used for pagination. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.messages(147_731_561) + # ``` + # # GET <code>/repo/{repository.slug}/request/{request.id}/messages</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # request.id Integer Value uniquely identifying the request. # Query Parameter Type Description # include [String] List of attributes to eager load. # limit Integer How many messages to include in the response. Used for pagination. # offset Integer How many messages to skip before the first entry in the response. Used for pagination. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.messages(147_731_561) + # ``` + # # @param request_id [String, Integer] the request id # @return [Success, RequestError] def messages(request_id) validate_number request_id @@ -1799,10 +2328,16 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /org/87 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.organization(87) + # ``` + # # @param org_id [String, Integer] the organization id # @raise [TypeError] if given organization id is not a number # @return [Success, RequestError] def organization(org_id) validate_number org_id @@ -1850,13 +2385,21 @@ # # Example: GET /orgs?limit=5 # # **Sortable by:** <code>id</code>, <code>login</code>, <code>name</code>, <code>github_id</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.organizations + # ``` + # # @return [Success, RequestError] def organizations - get("#{without_repo}/orgs") + get("#{without_repo}/orgs#{opts}") end # This will be either a {https://developer.travis-ci.com/resource/user user} or {https://developer.travis-ci.com/resource/organization organization}. # # ## Attributes @@ -1899,48 +2442,80 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.owner + # # or + # travis.owner('danielpclark') + # ``` + # # GET <code>/owner/{user.login}</code> # # Template Variable Type Description # user.login String Login set on GitHub. # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.owner + # # or + # travis.owner('danielpclark') + # ``` + # # GET <code>/owner/{organization.login}</code> # # Template Variable Type Description # organization.login String Login set on GitHub. # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/travis-ci # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.owner('travis-ci') + # ``` + # # GET <code>/owner/github_id/{owner.github_id}</code> # # Template Variable Type Description # owner.github_id Integer User or organization id set on GitHub. # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/github_id/639823 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.owner(639_823) + # ``` + # # @param owner [String] username or github id # @return [Success, RequestError] def owner(owner = username) number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}") get("#{without_repo}/owner/#{owner}") end - # Document `resources/preference/overview` not found. + # Individual preferences for current user or organization. # # ## Attributes # # **Standard Representation** # @@ -1960,50 +2535,80 @@ # # ## Actions # # **For Organization** # - # Document `resources/preference/actions/for_organization` not found. + # Get preference for organization. # # GET <code>/org/{organization.id}/preference/{preference.name}</code> # # Template Variable Type Description # organization.id Integer Value uniquely identifying the organization. # preference.name Unknown The preference's name. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preference('private_insights_visibility', org_id: 107_660) + # ``` + # # **Update** # - # Document `resources/preference/actions/update` not found. + # Set preference for organization. # # PATCH <code>/org/{organization.id}/preference/{preference.name}</code> # # Template Variable Type Description # organization.id Integer Value uniquely identifying the organization. # preference.name Unknown The preference's name. # Accepted Parameter Type Description # preference.value Unknown The preference's value. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preference('private_insights_visibility', 'admins', org_id: 107_660) + # ``` + # + # Set preference for current user. + # # PATCH <code>/preference/{preference.name}</code> # # Template Variable Type Description # preference.name Unknown The preference's name. # Accepted Parameter Type Description # preference.value Unknown The preference's value. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preference('build_emails', true) + # ``` + # # **Find** # - # Document `resources/preference/actions/find` not found. + # Get preference for current user. # # GET <code>/preference/{preference.name}</code> # # Template Variable Type Description # preference.name Unknown The preference's name. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preference('build_emails') + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @param key [String] preference name to get or set # @param value [String] optional value to set preference # @param org_id [String, Integer] optional keyword argument for an organization id @@ -2016,43 +2621,57 @@ value and return patch("#{without_repo}#{org_id}/preference/#{key}", 'preference.value' => value) get("#{without_repo}#{org_id}/preference/#{key}") end - # Document `resources/preferences/overview` not found. + # Preferences for current user or organization. # # ## Attributes # # Name Type Description # preferences [Preferenc] List of preferences. # # ## Actions # # **For Organization** # - # Document `resources/preferences/actions/for_organization` not found. + # Gets preferences for organization. # # GET <code>/org/{organization.id}/preferences</code> # # Template Variable Type Description # organization.id Integer Value uniquely identifying the organization. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /org/87/preferences # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preferences(107_660) + # ``` + # # **For User** # - # Document `resources/preferences/actions/for_user` not found. + # Gets preferences for current user. # # GET <code>/preferences</code> # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /preferences # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.preferences + # ``` + # # @note requests require an authorization token set in the headers. See: {authorization=} # # @param org_id [String, Integer] optional organization id # @return [Success, RequestError] def preferences(org_id = nil) @@ -2114,10 +2733,19 @@ # # Example: GET /owner/danielpclark/repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5, sort_by: 'active,name'}) + # travis.repositories + # # or + # travis.repositories('danielpclark') + # ``` + # # GET <code>/owner/{user.login}/repos</code> # # Template Variable Type Description # user.login String Login set on GitHub. # @@ -2135,10 +2763,19 @@ # # Example: GET /owner/danielpclark/repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5, sort_by: 'active,name'}) + # travis.repositories + # # or + # travis.repositories('danielpclark') + # ``` + # # GET <code>/owner/{organization.login}/repos</code> # # Template Variable Type Description # organization.login String Login set on GitHub. # @@ -2156,10 +2793,18 @@ # # Example: GET /owner/travis-ci/repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5, sort_by: 'active,name'}) + # travis.repositories('travis-ci') + # ``` + # # GET <code>/owner/github_id/{owner.github_id}/repos</code> # # Template Variable Type Description # owner.github_id Integer User or organization id set on GitHub. # @@ -2177,10 +2822,17 @@ # # Example: GET /owner/github_id/639823/repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.options.build({limit: 5, sort_by: 'active,name'}) + # travis.repositories(639_823) + # ``` + # # **For Current User** # # This returns a list of repositories the current user has access to. # # GET <code>/repos</code> @@ -2199,13 +2851,22 @@ # # Example: GET /repos?limit=5&sort_by=active,name # # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # - # @param owner [String] username or github id + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5, sort_by: 'active,name'}) + # travis.repositories(:self) + # ``` + # + # @param owner [String, Integer, Symbol] username, github id, or `:self` # @return [Success, RequestError] def repositories(owner = username) + owner.equal?(:self) and return get("#{without_repo}/repos#{opts}") number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}") get("#{without_repo}/owner/#{owner}/repos#{opts}") end # An individual repository. @@ -2251,20 +2912,32 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.repository('danielpclark/trav3') + # ``` + # # GET <code>/repo/{repository.slug}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.repository('danielpclark/trav3') + # ``` + # # **Activate** # # This will activate a repository, allowing its tests to be run on Travis CI. # # POST <code>/repo/{repository.id}/activate</code> @@ -2272,17 +2945,31 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/activate # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :activate) + # ``` + # # POST <code>/repo/{repository.slug}/activate</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/activate # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :activate) + # ``` + # # **Deactivate** # # This will deactivate a repository, preventing any tests from running on Travis CI. # # POST <code>/repo/{repository.id}/deactivate</code> @@ -2290,17 +2977,31 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/deactivate # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :deactivate) + # ``` + # # POST <code>/repo/{repository.slug}/deactivate</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/deactivate # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :deactivate) + # ``` + # # **Star** # # This will star a repository based on the currently logged in user. # # POST <code>/repo/{repository.id}/star</code> @@ -2308,17 +3009,31 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/star # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :star) + # ``` + # # POST <code>/repo/{repository.slug}/star</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/star # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :star) + # ``` + # # **Unstar** # # This will unstar a repository based on the currently logged in user. # # POST <code>/repo/{repository.id}/unstar</code> @@ -2326,17 +3041,31 @@ # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # # Example: POST /repo/891/unstar # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :unstar) + # ``` + # # POST <code>/repo/{repository.slug}/unstar</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/unstar # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.repository('danielpclark/trav3', :unstar) + # ``` + # # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param repo [String] github_username/repository_name # @param action [String, Symbol] Optional argument for star/unstar/activate/deactivate # @raise [InvalidRepository] if given input does not @@ -2386,28 +3115,42 @@ # # ## Actions # # **Find** # - # Document `resources/request/actions/find` not found. + # Get the request by id for the current repository # # GET <code>/repo/{repository.id}/request/{request.id}</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # request.id Integer Value uniquely identifying the request. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.request(147_776_757) + # ``` + # # GET <code>/repo/{repository.slug}/request/{request.id}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # request.id Integer Value uniquely identifying the request. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.request(147_776_757) + # ``` + # # @param request_id [String, Integer] request id # @return [Success, RequestError] def request(request_id) validate_number request_id @@ -2458,10 +3201,18 @@ # limit Integer How many requests to include in the response. Used for pagination. # offset Integer How many requests to skip before the first entry in the response. Used for pagination. # # Example: GET /repo/891/requests?limit=5 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.requests + # ``` + # # GET <code>/repo/{repository.slug}/requests</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description @@ -2469,10 +3220,18 @@ # limit Integer How many requests to include in the response. Used for pagination. # offset Integer How many requests to skip before the first entry in the response. Used for pagination. # # Example: GET /repo/rails%2Frails/requests?limit=5 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.options.build({limit: 5}) + # travis.requests + # ``` + # # **Create** # # This will create a request for an individual repository, triggering a build to run on Travis CI. # # Use namespaced params in JSON format in the request body to pass any accepted parameters. Any keys in the request's config will override keys existing in the `.travis.yml`. @@ -2485,10 +3244,20 @@ # -d '{ "request": { # "message": "Override the commit message: this is an api request", "branch": "master" }}'\ # https://api.travis-ci.com/repo/1/requests # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.requests( + # message: 'Override the commit message: this is an api request', + # branch: 'master' + # ) + # ``` + # # The response includes the following body: # # ```json # { # "@type": "pending", @@ -2586,10 +3355,17 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /build/86601346/stages # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.stages(479_113_572) + # ``` + # # @param build_id [String, Integer] build id # @raise [TypeError] if given build id is not a number # @return [Success, RequestError] def stages(build_id) validate_number build_id @@ -2638,18 +3414,32 @@ # repository.id Integer Value uniquely identifying the repository. # setting.name String The setting's name. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.setting('auto_cancel_pull_requests') + # ``` + # # GET <code>/repo/{repository.slug}/setting/{setting.name}</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # setting.name String The setting's name. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.setting('auto_cancel_pull_requests') + # ``` + # # **Update** # # This updates a single setting. It is possible to use the repository id or slug in the request. # # Use namespaced params in the request body to pass the new setting: @@ -2661,10 +3451,17 @@ # -H "Authorization: token xxxxxxxxxxxx" \ # -d '{ "setting.value": true }' \ # https://api.travis-ci.com/repo/1234/setting/{setting.name} # ``` # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.setting('auto_cancel_pull_requests', false) + # ``` + # # PATCH <code>/repo/{repository.id}/setting/{setting.name}</code> # # Template Variable Type Description # repository.id Integer Value uniquely identifying the repository. # setting.name String The setting's name. @@ -2725,19 +3522,33 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/891/settings # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.settings + # ``` + # # GET <code>/repo/{repository.slug}/settings</code> # # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /repo/rails%2Frails/settings # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.settings + # ``` + # # @return [Success, RequestError] def settings get("#{with_repo}/settings") end @@ -2788,10 +3599,16 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /user/119240 # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.user(119_240) + # ``` + # # **Sync** # # This triggers a sync on a user's account with their GitHub account. # # POST <code>/user/{user.id}/sync</code> @@ -2799,19 +3616,33 @@ # Template Variable Type Description # user.id Integer Value uniquely identifying the user. # # Example: POST /user/119240/sync # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.user(114_816, :sync) + # ``` + # # **Current** # # This will return information about the current user. # # GET <code>/user</code> # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /user + # + # ```ruby + # # RUBY EXAMPLE + # travis = Trav3::Travis.new('danielpclark/trav3') + # travis.authorization = 'xxxx' + # travis.user + # ``` # # @note sync feature may not be permitted # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param user_id [String, Integer] optional user id