Struct GithubBuildProvider 

pub struct GithubBuildProvider<R, P, A = NoVerifiedArtifactStore, C = SystemProviderClock> { /* private fields */ }

Concrete GitHub Actions implementation of the runtime-neutral build-provider contract.

Implementations

impl<R, P> GithubBuildProvider<R, P, NoVerifiedArtifactStore, SystemProviderClock>

where P: TemporaryRefPublisher,

pub fn new( config: GithubProviderConfig, transport: GithubTransport<R>, publisher: P, ) -> Self

Construct the provider without artifact ingestion.

Artifact listing/download capabilities remain false and GitHub success is reported as verification-pending, never as protocol success.

impl<R, P, A, C> GithubBuildProvider<R, P, A, C>

where P: TemporaryRefPublisher, A: VerifiedArtifactStore, C: ProviderClock,

pub fn with_artifact_store_and_clock( config: GithubProviderConfig, transport: GithubTransport<R>, publisher: P, artifacts: A, clock: C, ) -> Self

Construct with explicit verified artifact ingestion and clock.

pub fn with_checkpoint_sink( self, sink: impl GithubJobCheckpointSink + 'static, ) -> Self

Attach an atomic durable checkpoint sink without changing the protocol-v1 provider type.

pub const fn workflow_run_trigger(&self) -> WorkflowRunTrigger

Configured workflow trigger governing publication-to-run mapping.

pub fn wait_for_github_run( &self, job_id: &str, cancellation: &CancellationToken, ) -> RemoteBuildResult<RunSnapshot>

where R: GhRunner,

Explicitly poll one mapped run to terminal using the configured bounded policy.

This does not synthesize protocol success; a later events call still requires verified artifact manifests. Cancellation is checked before and after the bounded transport poll.

Errors

Returns a typed provider failure for an unknown/unmapped job or transport failure.

pub fn durable_identity(&self) -> RemoteBuildResult<GithubDurableIdentityV1>

where R: GhRunner,

Resolve the exact secret-free identity for a local durable record before submission.

This performs only bounded GitHub metadata reads. It never publishes a ref, starts a run, cancels a run, or deletes remote state. Repository-scoped credentials are rejected until a stable installation principal ID can be proven.

Errors

Returns a typed transport or stable-identity failure.

pub fn precompute_git_snapshot_graph( &self, inputs: &mut GitSnapshotPrecomputeInputs, operation_id: &str, source_created_at_ms: u64, cancellation: &CancellationToken, ) -> RemoteBuildResult<GitSnapshotObjectGraphV1>

Precompute one initial snapshot’s exact six-object graph without mutation.

This specialized boundary validates provider snapshot support and the operation-derived source ref, then delegates only to the retained-byte no-write publisher primitive. It does not create a stage, write a Git object, mutate a ref, access the network, or submit a job.

Errors

Returns a typed cancellation, unsupported-capability, unsafe-operation, retained-stage, object-format, fixed-Git, or canonical graph failure.

pub fn discover_uncheckpointed_git_snapshot_stages( &self, ) -> RemoteBuildResult<Vec<GithubGitSnapshotRecoveryCandidateV1>>

Discover complete provider-unowned snapshot stages using bounded private reads only.

This method neither adopts nor deletes any candidate. Provider jobs and in-process reservations are excluded, but the controller must separately prove that no on-disk JobStore record owns the operation before atomically creating that owner and invoking fresh-reconsent submission.

Errors

Returns a typed failure when snapshot support is unavailable or any private store entry is partial, unknown, over the fixed bound, non-canonical, rebound, or configuration-mismatched.

pub fn submit_git_snapshot( &self, submission: GithubGitSnapshotSubmissionV1, cancellation: &CancellationToken, ) -> RemoteBuildResult<JobHandle>

where R: GhRunner, P: TemporaryRefReconciler,

Submit one explicit-consent unsigned Git snapshot without an ordinary clean-Git fallback.

The first Prepared checkpoint is synchronously durable before this method permits a Git object write, ref mutation, or network request. Same-invocation stages must carry the exact accepted consent SHA. Restart adoption is available only through the distinct fresh- reconsent constructor and is no-mutation until that same checkpoint succeeds.

Errors

Returns a typed validation, checkpoint, retained-stage, Git, identity, transport, or publication failure. A checkpointed job remains resumable after any later failure.

pub fn precompute_exact_git_snapshot_retry( &self, parent_job_id: &str, child_operation_id: &str, child_source_created_at_ms: u64, cancellation: &CancellationToken, ) -> RemoteBuildResult<GithubGitSnapshotExactRetryPlanV1>

Derive one immutable exact-retry child request without creating a stage or mutating Git.

The terminal parent’s archive blob and keepalive are verified before and after bounded offline no-write hashing. The returned request and graph can therefore be persisted in the parent/child lineage before any child stage write.

Errors

Returns a typed failure for a nonterminal or releasing parent, missing/conflicting keepalive, invalid child identity, parent blob mismatch, or deterministic graph failure.

pub fn stage_exact_git_snapshot_retry( &self, authorization: &GithubGitSnapshotExactRetryAuthorizationV1, expected_plan: &GithubGitSnapshotExactRetryPlanV1, cancellation: &CancellationToken, ) -> RemoteBuildResult<GithubGitSnapshotExactRetryStageV1>

Create one exact child retry stage from a verified terminal parent’s private archive blob.

The caller must durably bind the parent/child retry lineage before invoking this method. No workspace is recaptured and no Git object or ref is mutated. The parent keepalive is required at its exact commit before and after the bounded child stage is published.

Errors

Returns a typed failure for missing lineage authority, a nonterminal or releasing parent, a missing/conflicting keepalive, parent blob size/SHA/object mismatch, or child stage and descriptor/graph failure.

pub fn release_git_snapshot_keepalive_for_prune( &self, authorization: &GithubGitSnapshotKeepaliveReleaseAuthorizationV1, cancellation: &CancellationToken, ) -> RemoteBuildResult<()>

Release one exact local snapshot keepalive under complete-lineage prune authority.

The caller remains responsible for proving complete-lineage prune authority and retaining every controller/store lease until this method returns. The provider binds the stable lineage IDs/edges/cutoff digest into its own checkpoint before any local ref mutation, verifies the exact expected commit, and checkpoints confirmed absence before returning.

Errors

Returns a typed failure unless the exact restored job has completed terminal cleanup, its remote source ref is already absent or conflict-proven, checkpoints are durable, and the local keepalive can be reconciled and removed without conflict.

pub fn restore_job_resumes_offline( &self, resumes: Vec<GithubJobResumeV1>, expected: &GithubDurableIdentityV1, ) -> RemoteBuildResult<()>

Restore durable jobs using only their stored identity and local provider configuration.

This method performs no transport or publisher operation. Call Self::revalidate_restored_job_live after any controller-owned mutation intent is durable and before relying on live GitHub state.

Errors

Rejects any configuration, principal, repository, request, ref, run, event, or state mismatch, duplicate job, capacity violation, or existing provider-state conflict.

pub fn revalidate_restored_job_live( &self, job_id: &str, cancellation: &CancellationToken, ) -> RemoteBuildResult<()>

where R: GhRunner,

Revalidate one offline-restored job against the current principal, repository, and run.

This performs bounded read-only GitHub requests and persists any refreshed exact run snapshot through the configured checkpoint sink. It never publishes, cancels, or cleans.

Errors

Returns a typed identity, transport, checkpoint, or restored-state failure.

pub fn restored_terminal_job_log_identity( &self, job_id: &str, ) -> RemoteBuildResult<Option<GithubDurableRunAttemptLogIdentity>>

Recover an offline-only identity for an exact terminal attempt restored from durable state.

This performs no transport or publisher operation. The returned type can validate an append-last durable log marker but cannot be passed to the network log fetcher.

Errors

Returns a typed restored-state or terminal-run identity failure.

pub fn export_job_resumes(&self) -> RemoteBuildResult<Vec<GithubJobResumeV1>>

where R: GhRunner,

Export all current jobs as strictly validated, secret-free durable records.

The current credential and stable execution-repository ID are revalidated before records are emitted.

Errors

Returns a typed identity, transport, state, or serialization failure.

pub fn restore_job_resumes( &self, resumes: Vec<GithubJobResumeV1>, ) -> RemoteBuildResult<()>

where R: GhRunner,

Restore an atomic batch of durable jobs after strict live identity revalidation.

Existing jobs and reservations are never overwritten.

Errors

Rejects unknown schema fields during deserialization and rejects any repository, principal, configuration, request, ref, run, attempt, event, or state mismatch here.

pub fn reconcile_restored_job( &self, job_id: &str, cancellation: &CancellationToken, ) -> RemoteBuildResult<GithubJobReconciliation>

where R: GhRunner, P: TemporaryRefPublisher + TemporaryRefReconciler,

Reconcile one restored pre-publication intent without issuing a duplicate push.

Errors

Returns a typed provider or read-only publisher failure. Exact remote bytes must match before a dispatch commit is adopted.

pub fn reconcile_restored_job_get_only( &self, job_id: &str, cancellation: &CancellationToken, ) -> RemoteBuildResult<GithubJobReconciliation>

where R: GhRunner, P: TemporaryRefPublisher + TemporaryRefReconciler,

Reconcile one restored publication using reads only, never cancellation dispatch.

This is the restart-safe path for a durable cancellation whose provider checkpoint already records cancellation intent but not dispatch acknowledgement.

Errors

Returns a typed provider or read-only publisher failure. Exact remote bytes must match before a dispatch commit is adopted.

pub fn refresh_restored_job_get_only( &self, job_id: &str, cancellation: &CancellationToken, ) -> RemoteBuildResult<()>

where R: GhRunner,

Refresh one restored job through bounded GET requests without cancellation dispatch.

Provider state and its checkpoint may advance from exact run observations, including to a terminal state. No remote mutation is issued even when durable cancellation intent exists.

Errors

Returns a typed identity, transport, checkpoint, or restored-state failure.

Trait Implementations

impl<R, P, A, C> BuildProvider for GithubBuildProvider<R, P, A, C>

where R: GhRunner + Send, P: TemporaryRefPublisher + Send, A: VerifiedArtifactStore + Send, C: ProviderClock,

fn id(&self) -> &str

Stable provider identifier used in events and errors.

fn capabilities(&self) -> &ProviderCapabilities

Capabilities active for this provider configuration.

fn handshake( &self, request: HandshakeRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, HandshakeResponse>

Negotiate protocol and worker compatibility.

fn doctor( &self, request: ProviderDoctorRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, ProviderDoctorReport>

Inspect provider, worker, and optional signing readiness.

fn submit( &self, request: IosDeviceBuildRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, JobHandle>

Submit one declarative physical-iPhone build.

fn events( &self, request: EventRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, EventPage>

Retrieve a bounded ordered page of events.

fn cancel( &self, request: CancellationRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, CancellationAck>

Request cancellation of an active job.

fn list_artifacts( &self, request: ArtifactListRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, Vec<ArtifactManifest>>

List verified artifact manifests for a job.

fn download_artifact( &self, request: ArtifactDownloadRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, ArtifactDownloadResult>

Download and independently verify one artifact.

fn cleanup( &self, request: CleanupRequest, cancellation: CancellationToken, ) -> ProviderFuture<'_, CleanupConfirmation>

Delete provider-owned workspace, signing material, and optional retained artifacts.