fastlane-plugin-circle_ci 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 310a5f9bf0095968820fde6642c4112fc1d6bc449dc9e38b0b408abcd3320613
-  data.tar.gz: 88089e5f6e51984ae7b8d13545e23bdc5bbe1bf92dc2c550f6d32b90faadfb64
+  metadata.gz: f30a30794b17b49d4c75989ea5028a5fd6692dc44ecaeb26c613fd5a62ee9587
+  data.tar.gz: c36eceb77e28ec2a2288807992805a56279af4b93a9bb90737f9caa2e1fc933b
 SHA512:
-  metadata.gz: 94b9b68f1e9bf5535b08d116d483f07d622c3af2951592f7396432c86bcbe0a331f3cc15d346da6c89058744884d8a79f92bb4348795169eb8063718735c99cf
-  data.tar.gz: 2d35a6e23b7f2f63bb3c6a3e07530e68c705c68c914a0c703d9742d61d83594d1426e3baec1fcdd4666b1a9e3a04e67ffd270528d0886990bfcf2ce4c2c85100
+  metadata.gz: c1732100632defd230826c2e0fdd6e496c74cda78ab4f46d4734d2d4cc7e9c062f4cb3051b3760d23e4988e70a69a4488a89fe508a39020a1795e6e48aad0bfc
+  data.tar.gz: d6d189737e89692030d89a0fcae0ccb7113e0c304f735058bdf337bf8b797b23aa9432e2685af7c130f19cbd9bbe03aa54b518802a0cd0fab5d8b859a6952465

data/README.md

@@ -14,13 +14,282 @@ fastlane add_plugin circle_ci
 
 A fastlane plugin for Circle CI. 🚀
 
-**Note to author:** Add a more detailed description about this plugin here. If your plugin contains multiple actions, make sure to mention them here.
+This plugin provides a set of actions that allow you to interact with CircleCI from your fastlane workflows. It supports both CircleCI API v1.1 (legacy) and API v2 (current).
+
+## Contributors
+
+The actions in this plugin were created and enhanced with the assistance of GitHub Copilot, working alongside human developers to provide a comprehensive set of CircleCI integrations for your fastlane workflows.
+
+## Available Actions
+
+### CircleCI API v2 Actions
+
+#### Pipeline Management
+- `circleci_trigger_pipeline`: Triggers a new CircleCI pipeline
+- `circleci_get_pipeline`: Gets details of a specific pipeline
+- `circleci_get_pipeline_workflows`: Gets workflows for a pipeline
+- `circleci_wait_for_pipeline`: Waits for a pipeline to complete
+- `circleci_continue_pipeline`: Continues a pipeline that is on hold
+- `circleci_get_pipeline_by_number`: Gets a pipeline by its number
+- `circleci_get_pipeline_config`: Gets the configuration of a pipeline
+- `circleci_get_my_pipelines`: Gets pipelines associated with the current user
+- `circleci_get_pipeline_values`: Gets pipeline parameter values
+
+#### Workflow and Job Management
+- `circleci_get_workflow_jobs`: Gets jobs for a workflow
+- `circleci_get_job_details`: Gets detailed information about a job
+- `circleci_get_job_artifacts`: Gets artifacts generated by a job
+- `circleci_download_artifact`: Downloads an artifact to a local path
+- `circleci_download_workflow_artifacts`: Downloads all artifacts from a specific workflow
+- `circleci_approve_job`: Approves a pending approval job in a workflow
+- `circleci_cancel_job`: Cancels a running job
+- `circleci_cancel_workflow`: Cancels a running workflow
+- `circleci_get_job_tests`: Gets test metadata for a job
+- `circleci_get_job_timeseries`: Gets timeseries data for a job
+
+#### Environment Variable Management
+- `circleci_get_env_vars`: Gets environment variables for a project
+- `circleci_set_env_var`: Sets an environment variable for a project
+- `circleci_delete_env_var`: Deletes an environment variable from a project
+
+#### Context Management
+- `circleci_list_contexts`: Lists available contexts for an owner
+- `circleci_get_context_env_vars`: Gets environment variables for a context
+- `circleci_add_context_env_var`: Adds an environment variable to a context
+- `circleci_delete_context_env_var`: Deletes an environment variable from a context
+
+#### Project Management
+- `circleci_add_project_collaborator`: Adds a collaborator to a project
+- `circleci_create_project`: Creates a new CircleCI project
+- `circleci_get_project_branches`: Gets all branches for a project
+- `circleci_get_project_config`: Gets the configuration of a project
+- `circleci_get_project_workflow_metrics`: Gets workflow metrics for a project
+
+#### Schedule Management
+- `circleci_create_pipeline_schedule`: Creates a pipeline schedule
+- `circleci_list_pipeline_schedules`: Lists all pipeline schedules for a project
+- `circleci_delete_pipeline_schedule`: Deletes a pipeline schedule
+
+#### Webhook Management
+- `circleci_create_webhook`: Creates a webhook for a project
+- `circleci_delete_webhook`: Deletes a webhook
+
+#### Pipeline Definition Management
+- `circleci_create_pipeline_definition`: Creates a pipeline definition
+- `circleci_get_pipeline_definition`: Gets details of a pipeline definition
+- `circleci_get_pipeline_definitions`: Lists all pipeline definitions
+- `circleci_delete_pipeline_definition`: Deletes a pipeline definition
+- `circleci_create_pipeline_definition_trigger`: Creates a pipeline definition trigger
+- `circleci_delete_trigger`: Deletes a pipeline trigger
+- `circleci_get_trigger`: Gets information about a pipeline trigger
+
+#### Checkout Key Management
+- `circleci_create_checkout_key`: Creates a checkout key for a project
+- `circleci_get_checkout_key`: Gets details of a specific checkout key
+- `circleci_get_checkout_keys`: Lists all checkout keys for a project
+- `circleci_delete_checkout_key`: Deletes a checkout key
+
+#### Analytics and Insights
+- `circleci_get_flaky_tests`: Gets flaky tests information for a project
+- `circleci_get_workflow_insights`: Gets insights data for a workflow
+- `circleci_get_workflow_job_metrics`: Gets metrics for jobs in a workflow
+- `circleci_get_workflow_runs`: Gets recent runs of a workflow
+- `circleci_get_workflow_summary`: Gets summary metrics for a workflow
+- `circleci_get_org_summary`: Gets summary metrics for an organization
+- `circleci_get_user_info`: Gets information about the authenticated user
+
+### Legacy API v1.1 Actions
+- `trigger_circle_ci_job`: Triggers a specific job in CircleCI
+- `get_circle_ci_build_status`: Gets the status of a CircleCI build
+- `get_circle_ci_artifacts`: Gets artifacts from a CircleCI build
+- `download_circle_ci_artifact`: Downloads a CircleCI artifact
 
 ## Example
 
-Check out the [example `Fastfile`](fastlane/Fastfile) to see how to use this plugin. Try it by cloning the repo, running `fastlane install_plugins` and `bundle exec fastlane test`.
+### Triggering a Pipeline and Waiting for Completion
+
+```ruby
+# Trigger a pipeline on the main branch
+pipeline = circleci_trigger_pipeline(
+  project_slug: "github/myorg/myrepo",
+  branch: "main",
+  parameters: {
+    "deploy_env" => "staging",
+    "run_integration_tests" => true
+  }
+)
+
+# Wait for the pipeline to complete
+result = circleci_wait_for_pipeline(
+  pipeline_id: pipeline["id"],
+  timeout: 1800,  # 30 minutes
+  poll_interval: 30  # Check status every 30 seconds
+)
+
+if result[:status] == "success"
+  UI.success("Pipeline completed successfully!")
+else
+  UI.error("Pipeline failed with status: #{result[:status]}")
+end
+```
+
+### Managing Environment Variables
+
+```ruby
+# Set an environment variable
+circleci_set_env_var(
+  project_slug: "github/myorg/myrepo",
+  name: "DEPLOY_KEY",
+  value: ENV["MY_DEPLOY_KEY"]
+)
+
+# Get all environment variables
+env_vars = circleci_get_env_vars(
+  project_slug: "github/myorg/myrepo"
+)
+
+# Check if a variable exists
+has_api_key = env_vars.any? { |var| var["name"] == "API_KEY" }
+```
+
+### Working with Contexts
 
-**Note to author:** Please set up a sample project to make it easy for users to explore what your plugin does. Provide everything that is necessary to try out the plugin in this project (including a sample Xcode/Android project if necessary)
+```ruby
+# List all contexts
+contexts = circleci_list_contexts(
+  owner_slug: "github/myorg"
+)
+
+# Get a specific context by name
+deploy_context = contexts.find { |ctx| ctx["name"] == "deploy-context" }
+
+if deploy_context
+  # Add an environment variable to the context
+  circleci_add_context_env_var(
+    context_id: deploy_context["id"],
+    env_var_name: "RELEASE_TOKEN",
+    env_var_value: ENV["RELEASE_TOKEN"]
+  )
+end
+```
+
+### Downloading Artifacts
+
+```ruby
+# Download only JSON files (default)
+circleci_download_workflow_artifacts(
+  project_slug: "github/myorg/myrepo"
+)
+
+# Download only XML files
+circleci_download_workflow_artifacts(
+  project_slug: "github/myorg/myrepo",
+  file_extensions: "xml"
+)
+
+# Download both JSON and XML files
+circleci_download_workflow_artifacts(
+  project_slug: "github/myorg/myrepo",
+  file_extensions: ["json", "xml"]
+)
+
+# Download artifacts from a specific job only
+circleci_download_workflow_artifacts(
+  project_slug: "github/myorg/myrepo",
+  job_name: "build"
+)
+
+# Download all artifacts from a specific workflow
+artifacts_info = circleci_download_workflow_artifacts(
+  project_slug: "github/myorg/myrepo",
+  branch: "master",
+  workflow_name: "test",
+  destination_dir: "./artifacts"
+)
+
+# Check how many artifacts were downloaded
+UI.message("Downloaded #{artifacts_info[:total_artifacts]} artifacts from #{artifacts_info[:workflow_name]} workflow")
+
+# Process downloaded artifacts if needed
+artifacts_info[:downloaded_artifacts].each do |job_artifacts|
+  job_name = job_artifacts[:job_name]
+  job_artifacts[:artifacts].each do |artifact|
+    path = artifact[:download_path]
+    # Process artifact files as needed
+    puts "Processing #{path} from job #{job_name}"
+  end
+end
+
+# Get artifacts from a job
+artifacts = circleci_get_job_artifacts(
+  project_slug: "github/myorg/myrepo",
+  job_number: "123"
+)
+
+# Download a specific artifact
+if artifacts.any?
+  test_results = artifacts.find { |a| a["path"].end_with?("test-results.xml") }
+  
+  if test_results
+    circleci_download_artifact(
+      artifact_url: test_results["url"],
+      destination_path: "./test-results/circle-results.xml"
+    )
+  end
+end
+```
+
+### Working with Pipeline Schedules
+
+```ruby
+# Create a pipeline schedule to run nightly
+circleci_create_pipeline_schedule(
+  project_slug: "github/myorg/myrepo",
+  name: "Nightly Build",
+  description: "Runs every night at midnight",
+  timetable: {
+    per_hour: 1,
+    hours_of_day: [0],
+    days_of_week: [1, 2, 3, 4, 5]
+  },
+  branch: "main",
+  parameters: {
+    "deploy_env" => "staging"
+  }
+)
+
+# List all schedules for a project
+schedules = circleci_list_pipeline_schedules(
+  project_slug: "github/myorg/myrepo"
+)
+
+# Find a specific schedule by name
+nightly_build = schedules.find { |schedule| schedule["name"] == "Nightly Build" }
+```
+
+### Working with Project Insights
+
+```ruby
+# Get flaky tests for a project
+flaky_tests = circleci_get_flaky_tests(
+  project_slug: "github/myorg/myrepo"
+)
+
+# Take action on flaky tests
+if flaky_tests["most_failed_tests"].any?
+  UI.important("Found #{flaky_tests["most_failed_tests"].count} flaky tests that need attention")
+  flaky_tests["most_failed_tests"].each do |test|
+    puts "  - #{test["test_name"]}: Failed #{test["times_flaked"]} times"
+  end
+end
+
+# Get workflow metrics
+workflow_metrics = circleci_get_project_workflow_metrics(
+  project_slug: "github/myorg/myrepo",
+  branch: "main",
+  reporting_window: "last-30-days"
+)
+```
 
 ## Run tests for this plugin
 

data/lib/fastlane/plugin/circle_ci/actions/circleci_add_context_env_var.rb

@@ -0,0 +1,117 @@
+require 'fastlane/action'
+require_relative '../helper/circle_ci_helper'
+
+module Fastlane
+  module Actions
+    class CircleciAddContextEnvVarAction < Action
+      def self.run(params)
+        UI.message("Adding environment variable to CircleCI context via API v2...")
+        
+        api_token = params[:api_token]
+        context_id = params[:context_id]
+        env_var_name = params[:env_var_name]
+        env_var_value = params[:env_var_value]
+        
+        # Prepare request body
+        body = {
+          variable: env_var_name,
+          value: env_var_value
+        }
+        
+        # Make API request
+        result = Helper::CircleCiHelper.put_v2("context/#{context_id}/environment-variable/#{env_var_name}", api_token, body)
+        
+        UI.success("Successfully added environment variable '#{env_var_name}' to context #{context_id}")
+        
+        return result
+      end
+
+      def self.description
+        "Adds an environment variable to a CircleCI context using API v2"
+      end
+
+      def self.details
+        "This action adds or updates an environment variable in a specific CircleCI context using the CircleCI API v2. Environment variables in contexts are used to securely share configuration across projects."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :api_token,
+                                       env_name: "CIRCLE_CI_API_TOKEN",
+                                       description: "API Token for CircleCI API",
+                                       sensitive: true,
+                                       code_gen_sensitive: true,
+                                       is_string: true,
+                                       default_value: ENV["CIRCLE_CI_API_TOKEN"],
+                                       default_value_dynamic: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :context_id,
+                                       env_name: "CIRCLE_CI_CONTEXT_ID",
+                                       description: "The ID of the context to add the environment variable to",
+                                       is_string: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :env_var_name,
+                                       env_name: "CIRCLE_CI_ENV_VAR_NAME",
+                                       description: "The name of the environment variable",
+                                       is_string: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :env_var_value,
+                                       env_name: "CIRCLE_CI_ENV_VAR_VALUE",
+                                       description: "The value of the environment variable",
+                                       sensitive: true,
+                                       code_gen_sensitive: true,
+                                       is_string: true,
+                                       optional: false)
+        ]
+      end
+
+      def self.return_value
+        "Returns a hash containing the created environment variable information (without the actual value for security)."
+      end
+
+      def self.authors
+        ["crazymanish", "copilot"]
+      end
+
+      def self.example_code
+        [
+          'circleci_add_context_env_var(
+            context_id: "context-uuid",
+            env_var_name: "API_KEY",
+            env_var_value: "secret-value"
+          )',
+          '# First find the context, then add a variable to it
+          contexts = circleci_list_contexts(
+            owner_slug: "github/myorg"
+          )
+          
+          # Find the staging context
+          staging_context = contexts.find { |c| c["name"] == "staging" }
+          
+          if staging_context
+            # Add or update environment variables for staging
+            circleci_add_context_env_var(
+              context_id: staging_context["id"],
+              env_var_name: "DEPLOY_URL",
+              env_var_value: "https://staging.example.com"
+            )
+            
+            circleci_add_context_env_var(
+              context_id: staging_context["id"],
+              env_var_name: "STAGE",
+              env_var_value: "staging"
+            )
+          end'
+        ]
+      end
+
+      def self.is_supported?(platform)
+        true
+      end
+
+      def self.category
+        :ci
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/circle_ci/actions/circleci_add_project_collaborator.rb

@@ -0,0 +1,109 @@
+require 'fastlane/action'
+require_relative '../helper/circle_ci_helper'
+
+module Fastlane
+  module Actions
+    module SharedValues
+      CIRCLECI_PROJECT_COLLABORATOR = :CIRCLECI_PROJECT_COLLABORATOR
+    end
+
+    class CircleciAddProjectCollaboratorAction < Action
+      def self.run(params)
+        UI.message("Adding collaborator to CircleCI project via API v2...")
+        
+        api_token = params[:api_token]
+        project_slug = params[:project_slug]
+        username = params[:username]
+        
+        # Construct the request body
+        body = {
+          id: username
+        }
+        
+        # Make API request
+        endpoint = "project/#{project_slug}/user/#{username}"
+        result = Helper::CircleCiHelper.post_v2(endpoint, api_token, body)
+        
+        # Store values in lane context
+        Actions.lane_context[SharedValues::CIRCLECI_PROJECT_COLLABORATOR] = result
+        
+        UI.success("Successfully added collaborator #{username} to project")
+        
+        return result
+      end
+
+      def self.description
+        "Adds a user as a collaborator to a CircleCI project using API v2"
+      end
+
+      def self.details
+        "This action adds a user as a collaborator to a CircleCI project using the CircleCI API v2. " +
+        "The collaborator will be granted access to view and manage the project based on their role permissions."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :api_token,
+                                       env_name: "CIRCLE_CI_API_TOKEN",
+                                       description: "API Token for CircleCI API",
+                                       sensitive: true,
+                                       code_gen_sensitive: true,
+                                       is_string: true,
+                                       default_value: ENV["CIRCLE_CI_API_TOKEN"],
+                                       default_value_dynamic: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :project_slug,
+                                       env_name: "CIRCLE_CI_PROJECT_SLUG",
+                                       description: "Project slug in the form of :vcs-type/:org-name/:project-name (e.g. github/myorg/myrepo)",
+                                       is_string: true,
+                                       default_value: ENV["CIRCLE_CI_PROJECT_SLUG"],
+                                       default_value_dynamic: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :username,
+                                       env_name: "CIRCLE_CI_COLLABORATOR_USERNAME",
+                                       description: "The username of the user to add as a collaborator",
+                                       is_string: true,
+                                       optional: false)
+        ]
+      end
+
+      def self.output
+        [
+          ['CIRCLECI_PROJECT_COLLABORATOR', 'A hash containing the collaborator data']
+        ]
+      end
+
+      def self.return_value
+        "Returns a hash containing the collaborator information and their role in the project."
+      end
+
+      def self.authors
+        ["crazymanish", "copilot"]
+      end
+
+      def self.example_code
+        [
+          'circleci_add_project_collaborator(
+            project_slug: "github/myorg/myrepo",
+            username: "new-collaborator"
+          )',
+          '# Add a collaborator and verify they were added
+          collaborator = circleci_add_project_collaborator(
+            project_slug: "github/myorg/myrepo",
+            username: "new-collaborator"
+          )
+          
+          UI.message("Added #{collaborator["id"]} with role #{collaborator["role"]}")'
+        ]
+      end
+
+      def self.is_supported?(platform)
+        true
+      end
+
+      def self.category
+        :ci
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/circle_ci/actions/circleci_approve_job.rb

@@ -0,0 +1,95 @@
+require 'fastlane/action'
+require_relative '../helper/circle_ci_helper'
+
+module Fastlane
+  module Actions
+    class CircleciApproveJobAction < Action
+      def self.run(params)
+        UI.message("Approving CircleCI job via API v2...")
+        
+        api_token = params[:api_token]
+        approval_request_id = params[:approval_request_id]
+        
+        # Make API request with empty body as required by the API
+        result = Helper::CircleCiHelper.post_v2("workflow/#{approval_request_id}/approve", api_token, {})
+        
+        UI.success("Successfully approved job with approval request ID #{approval_request_id}")
+        
+        return { success: true, message: "Job approved" }
+      end
+
+      def self.description
+        "Approves a pending approval job in a CircleCI workflow using API v2"
+      end
+
+      def self.details
+        "This action approves a pending approval job in a CircleCI workflow using the CircleCI API v2. This is useful for automated approval of deployment jobs."
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :api_token,
+                                       env_name: "CIRCLE_CI_API_TOKEN",
+                                       description: "API Token for CircleCI API",
+                                       sensitive: true,
+                                       code_gen_sensitive: true,
+                                       is_string: true,
+                                       default_value: ENV["CIRCLE_CI_API_TOKEN"],
+                                       default_value_dynamic: true,
+                                       optional: false),
+          FastlaneCore::ConfigItem.new(key: :approval_request_id,
+                                       env_name: "CIRCLE_CI_APPROVAL_REQUEST_ID",
+                                       description: "The ID of the approval request to approve",
+                                       is_string: true,
+                                       optional: false)
+        ]
+      end
+
+      def self.return_value
+        "Returns a hash with success status and a message."
+      end
+
+      def self.authors
+        ["crazymanish", "copilot"]
+      end
+
+      def self.example_code
+        [
+          'circleci_approve_job(
+            approval_request_id: "approval-request-uuid"
+          )',
+          '# First get workflows for a pipeline, then find and approve any pending approval jobs
+          workflows = circleci_get_pipeline_workflows(
+            pipeline_id: "some-pipeline-id"
+          )
+          
+          # For each workflow
+          workflows.each do |workflow|
+            # Get jobs for the workflow
+            jobs = circleci_get_workflow_jobs(
+              workflow_id: workflow["id"]
+            )
+            
+            # Find approval jobs that are on_hold
+            approval_jobs = jobs.select { |job| job["type"] == "approval" && job["status"] == "on_hold" }
+            
+            # Approve each job
+            approval_jobs.each do |job|
+              circleci_approve_job(
+                approval_request_id: job["id"]
+              )
+            end
+          end'
+        ]
+      end
+
+      def self.is_supported?(platform)
+        true
+      end
+
+      def self.category
+        :ci
+      end
+    end
+  end
+end