or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

actions.mdadditional-services.mdapps.mdchecks.mdclient.mdenterprise.mdgit.mdindex.mdissues.mdorganizations.mdrepositories.mdteams.mdusers.md
tile.json

checks.mddocs/

Checks

Create and manage check runs and check suites for continuous integration.

ChecksService

The ChecksService provides methods for managing GitHub Checks API.

type ChecksService struct{}

Check Runs

Create and Get Check Runs

// CreateCheckRun creates a new check run
func (s *ChecksService) CreateCheckRun(ctx context.Context, owner, repo string, opts CreateCheckRunOptions) (*CheckRun, *Response, error)

// GetCheckRun gets a single check run
func (s *ChecksService) GetCheckRun(ctx context.Context, owner, repo string, checkRunID int64) (*CheckRun, *Response, error)

// UpdateCheckRun updates a check run
func (s *ChecksService) UpdateCheckRun(ctx context.Context, owner, repo string, checkRunID int64, opts UpdateCheckRunOptions) (*CheckRun, *Response, error)

type CreateCheckRunOptions struct {
    Name        string  // Required
    HeadSHA     string  // Required
    DetailsURL  *string
    ExternalID  *string
    Status      *string  // "queued", "in_progress", "completed"
    Conclusion  *string  // "success", "failure", "neutral", "cancelled", "skipped", "timed_out", "action_required"
    StartedAt   *Timestamp
    CompletedAt *Timestamp
    Output      *CheckRunOutput
    Actions     []*CheckRunAction
}

type UpdateCheckRunOptions struct {
    Name        string  // Required
    DetailsURL  *string
    ExternalID  *string
    Status      *string
    Conclusion  *string
    CompletedAt *Timestamp
    Output      *CheckRunOutput
    Actions     []*CheckRunAction
}

type CheckRun struct {
    ID          *int64
    NodeID      *string
    HeadSHA     *string
    ExternalID  *string
    URL         *string
    HTMLURL     *string
    DetailsURL  *string
    Status      *string
    Conclusion  *string
    StartedAt   *Timestamp
    CompletedAt *Timestamp
    Output      *CheckRunOutput
    Name        *string
    CheckSuite  *CheckSuite
    App         *App
    PullRequests []*PullRequest
}

type CheckRunOutput struct {
    Title            *string
    Summary          *string  // Required
    Text             *string
    AnnotationsCount *int
    AnnotationsURL   *string
    Annotations      []*CheckRunAnnotation
    Images           []*CheckRunImage
}

type CheckRunAnnotation struct {
    Path            *string  // Required
    StartLine       *int     // Required
    EndLine         *int     // Required
    StartColumn     *int
    EndColumn       *int
    AnnotationLevel *string  // Required: "notice", "warning", "failure"
    Message         *string  // Required
    Title           *string
    RawDetails      *string
}

type CheckRunAction struct {
    Label       string  // Required
    Description string  // Required
    Identifier  string  // Required
}

Usage:

// Create a check run
opts := github.CreateCheckRunOptions{
    Name:    "lint",
    HeadSHA: "commit-sha",
    Status:  github.Ptr("in_progress"),
    Output: &github.CheckRunOutput{
        Title:   github.Ptr("Linting Results"),
        Summary: github.Ptr("Checking code style..."),
    },
}

checkRun, _, err := client.Checks.CreateCheckRun(ctx, "owner", "repo", opts)

// Update check run with results
updateOpts := github.UpdateCheckRunOptions{
    Name:       "lint",
    Status:     github.Ptr("completed"),
    Conclusion: github.Ptr("success"),
    Output: &github.CheckRunOutput{
        Title:   github.Ptr("Linting Results"),
        Summary: github.Ptr("All checks passed!"),
        Annotations: []*github.CheckRunAnnotation{
            {
                Path:            github.Ptr("main.go"),
                StartLine:       github.Ptr(10),
                EndLine:         github.Ptr(10),
                AnnotationLevel: github.Ptr("warning"),
                Message:         github.Ptr("Consider using a more descriptive variable name"),
            },
        },
    },
}

checkRun, _, err = client.Checks.UpdateCheckRun(
    ctx, "owner", "repo", *checkRun.ID, updateOpts)

List Check Runs

// ListCheckRunsForRef lists check runs for a specific ref
func (s *ChecksService) ListCheckRunsForRef(ctx context.Context, owner, repo, ref string, opts *ListCheckRunsOptions) (*ListCheckRunsResults, *Response, error)

// ListCheckRunsCheckSuite lists check runs in a check suite
func (s *ChecksService) ListCheckRunsCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64, opts *ListCheckRunsOptions) (*ListCheckRunsResults, *Response, error)

type ListCheckRunsOptions struct {
    CheckName *string
    Status    *string
    Filter    *string  // "latest", "all"
    ListOptions
}

type ListCheckRunsResults struct {
    Total     *int
    CheckRuns []*CheckRun
}

Check Run Annotations

// ListCheckRunAnnotations lists annotations for a check run
func (s *ChecksService) ListCheckRunAnnotations(ctx context.Context, owner, repo string, checkRunID int64, opts *ListOptions) ([]*CheckRunAnnotation, *Response, error)

Rerequest Check Run

// ReRequestCheckRun triggers GitHub to rerequest an existing check run
func (s *ChecksService) ReRequestCheckRun(ctx context.Context, owner, repo string, checkRunID int64) (*Response, error)

Check Suites

Create and Get Check Suites

// CreateCheckSuite manually creates a check suite
func (s *ChecksService) CreateCheckSuite(ctx context.Context, owner, repo string, opts CreateCheckSuiteOptions) (*CheckSuite, *Response, error)

// GetCheckSuite gets a single check suite
func (s *ChecksService) GetCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64) (*CheckSuite, *Response, error)

type CreateCheckSuiteOptions struct {
    HeadSHA string  // Required
}

type CheckSuite struct {
    ID           *int64
    NodeID       *string
    HeadBranch   *string
    HeadSHA      *string
    URL          *string
    BeforeSHA    *string
    AfterSHA     *string
    Status       *string
    Conclusion   *string
    App          *App
    Repository   *Repository
    CreatedAt    *Timestamp
    UpdatedAt    *Timestamp
    LatestCheckRunsCount  *int
    CheckRunsURL *string
    HeadCommit   *Commit
    PullRequests []*PullRequest
}

List Check Suites

// ListCheckSuitesForRef lists check suites for a specific ref
func (s *ChecksService) ListCheckSuitesForRef(ctx context.Context, owner, repo, ref string, opts *ListCheckSuiteOptions) (*ListCheckSuiteResults, *Response, error)

type ListCheckSuiteOptions struct {
    CheckName *string
    AppID     *int
    ListOptions
}

type ListCheckSuiteResults struct {
    Total       *int
    CheckSuites []*CheckSuite
}

Rerequest Check Suite

// ReRequestCheckSuite triggers GitHub to rerequest an existing check suite
func (s *ChecksService) ReRequestCheckSuite(ctx context.Context, owner, repo string, checkSuiteID int64) (*Response, error)

Check Suite Preferences

// SetRepositoryCheckSuitePreferences sets check suite preferences for a repository
func (s *ChecksService) SetRepositoryCheckSuitePreferences(ctx context.Context, owner, repo string, opts CheckSuitePreferenceOptions) (*CheckSuitePreferenceResults, *Response, error)

type CheckSuitePreferenceOptions struct {
    AutoTriggerChecks []*AutoTriggerCheck  // Required
}

type AutoTriggerCheck struct {
    AppID   int64  // Required
    Setting bool   // Required
}

type CheckSuitePreferenceResults struct {
    Preferences *PreferenceList
    Repository  *Repository
}

Complete Example

import (
    "context"
    "github.com/google/go-github/v79/github"
)

// Create a check run workflow
func runChecks(ctx context.Context, client *github.Client, owner, repo, sha string) error {
    // 1. Create check run in queued state
    createOpts := github.CreateCheckRunOptions{
        Name:    "my-ci-check",
        HeadSHA: sha,
        Status:  github.Ptr("queued"),
        Output: &github.CheckRunOutput{
            Title:   github.Ptr("CI Check"),
            Summary: github.Ptr("Running tests..."),
        },
    }

    checkRun, _, err := client.Checks.CreateCheckRun(ctx, owner, repo, createOpts)
    if err != nil {
        return err
    }

    // 2. Update to in_progress
    updateOpts := github.UpdateCheckRunOptions{
        Name:   "my-ci-check",
        Status: github.Ptr("in_progress"),
    }

    checkRun, _, err = client.Checks.UpdateCheckRun(
        ctx, owner, repo, *checkRun.ID, updateOpts)
    if err != nil {
        return err
    }

    // 3. Run your actual checks here
    passed, annotations := runYourTests()

    // 4. Complete the check run with results
    var conclusion string
    if passed {
        conclusion = "success"
    } else {
        conclusion = "failure"
    }

    completeOpts := github.UpdateCheckRunOptions{
        Name:       "my-ci-check",
        Status:     github.Ptr("completed"),
        Conclusion: github.Ptr(conclusion),
        Output: &github.CheckRunOutput{
            Title:       github.Ptr("CI Check Complete"),
            Summary:     github.Ptr("Test results are ready"),
            Annotations: annotations,
        },
    }

    _, _, err = client.Checks.UpdateCheckRun(
        ctx, owner, repo, *checkRun.ID, completeOpts)
    return err
}

func runYourTests() (bool, []*github.CheckRunAnnotation) {
    // Your test logic here
    annotations := []*github.CheckRunAnnotation{
        {
            Path:            github.Ptr("test.go"),
            StartLine:       github.Ptr(15),
            EndLine:         github.Ptr(15),
            AnnotationLevel: github.Ptr("failure"),
            Message:         github.Ptr("Test failed: expected 5, got 3"),
        },
    }
    return false, annotations
}