{"id":19472225,"url":"https://github.com/fluxcd/go-git-providers","last_synced_at":"2025-05-15T21:06:04.024Z","repository":{"id":37488246,"uuid":"281059559","full_name":"fluxcd/go-git-providers","owner":"fluxcd","description":"Git provider client for Go","archived":false,"fork":false,"pushed_at":"2025-05-08T12:00:29.000Z","size":1304,"stargazers_count":71,"open_issues_count":27,"forks_count":36,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-08T12:38:08.197Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://fluxcd.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluxcd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-20T08:28:17.000Z","updated_at":"2025-05-08T12:00:31.000Z","dependencies_parsed_at":"2023-10-11T20:19:15.444Z","dependency_job_id":"cccd738c-7e39-4cd9-ab1d-596852a8310d","html_url":"https://github.com/fluxcd/go-git-providers","commit_stats":{"total_commits":355,"total_committers":32,"mean_commits":11.09375,"dds":0.7014084507042253,"last_synced_commit":"1d532ae6adf29e545055fddcf98cb668d23b8fe1"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxcd%2Fgo-git-providers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxcd%2Fgo-git-providers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxcd%2Fgo-git-providers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluxcd%2Fgo-git-providers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluxcd","download_url":"https://codeload.github.com/fluxcd/go-git-providers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254422756,"owners_count":22068678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T19:13:32.889Z","updated_at":"2025-05-15T21:06:04.006Z","avatar_url":"https://github.com/fluxcd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-git-providers\n\n[![godev](https://img.shields.io/static/v1?label=godev\u0026message=reference\u0026color=00add8)](https://pkg.go.dev/github.com/fluxcd/go-git-providers)\n[![build](https://github.com/fluxcd/go-git-providers/workflows/build/badge.svg)](https://github.com/fluxcd/go-git-providers/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fluxcd/go-git-providers)](https://goreportcard.com/report/github.com/fluxcd/go-git-providers)\n[![LICENSE](https://img.shields.io/github/license/fluxcd/go-git-providers)](https://github.com/fluxcd/go-git-providers/blob/master/LICENSE)\n[![Release](https://img.shields.io/github/v/release/fluxcd/go-git-providers?include_prereleases)](https://github.com/fluxcd/go-git-providers/releases/latest)\n\n[go-git-providers](https://pkg.go.dev/github.com/fluxcd/go-git-providers)\nis a general-purpose Go client for interacting with Git providers' APIs.\n\nSupported providers:\n\n- GitHub API (GitHub.com and on-prem)\n- GitLab API (GitLab.com and on-prem)\n- Bitbucket Server API (on-prem)\n\n## Features\n\n- **Consistency:** Using the same Client interface and high-level structs for multiple backends.\n- **Authentication:** Personal Access Tokens/OAuth2 Tokens, and unauthenticated.\n- **Pagination:** List calls automatically return all available pages.\n- **Conditional Requests:** Asks the Git provider if cached data is up-to-date before requesting, to avoid being rate limited.\n- **Reconciling:** Support reconciling desired state towards actual state and drift detection.\n- **Low-level access:** Access the underlying, provider-specific data easily, if needed, and support applying it to the server.\n- **Wrapped errors:** Data-rich, Go 1.14-errors are consistent across provider, including cases like rate limit, validation, not found, etc.\n- **Go modules:** The major version is bumped if breaking changes, or major library upgrades are made.\n- **Validation-first:** Both server and user data is validated prior to manipulation.\n- **URL Parsing:** HTTPS user, organization and repository URLs can be parsed into machine-readable structs.\n- **Enums:** Consistent enums are used across providers for similar lists of values.\n- **Domain customization:** The user can specify their desired domain for the Git provider backend.\n- **Context-first:** `context.Context` is the first parameter for every API call.\n\n## Operations and Design\n\nThe top-level `gitprovider.Client` has the following sub-clients with their described capabilities:\n\n- `OrganizationsClient` operates on organizations the user has access to.\n  - `Get` a specific organization the user has access to.\n  - `List` all top-level organizations the specific user has access to.\n  - `Children` returns the immediate child-organizations for the specific OrganizationRef.\n\n- `{Org,User}RepositoriesClient` operates on repositories for organizations and users, respectively.\n  - `Get` returns the repository for the given reference.\n  - `List` all repositories in the given organization or user account.\n  - `Create` creates a repository, with the specified data and options.\n  - `Reconcile` makes sure the given desired state becomes the actual state in the backing Git provider.\n\nThe sub-clients above return `gitprovider.Organization` or `gitprovider.{Org,User}Repository` interfaces.\nThese object interfaces lets you access their data (through their `.Get()` function), internal,\nprovider-specific representation (through their `.APIObject()` function), or sub-resources like deploy keys\nand teams.\n\nThe following object-scoped clients are available:\n\n- `Organization` represents an organization in a Git provider.\n  - `Teams` gives access to the `TeamsClient` for this specific organization.\n    - `Get` a team within the specific organization.\n    - `List` all teams within the specific organization.\n\n- `UserRepository` describes a repository owned by an user.\n  - `DeployKeys` gives access to manipulating deploy keys, using this `DeployKeyClient`.\n    - `Get` a DeployKey by its name.\n    - `List` all deploy keys for the given repository.\n    - `Create` a deploy key with the given specifications.\n    - `Reconcile` makes sure the given desired state becomes the actual state in the backing Git provider.\n\n- `OrgRepository` is a superset of `UserRepository`, and describes a repository owned by an organization.\n  - `DeployKeys` as in `UserRepository`.\n  - `TeamAccess` returns a `TeamsAccessClient` for operating on teams' access to this specific repository.\n    - `Get` a team's permission level of this given repository.\n    - `List` the team access control list for this repository.\n    - `Create` adds a given team to the repository's team access control list.\n    - `Reconcile` makes sure the given desired state (req) becomes the actual state in the backing Git provider.\n\nWait, how do I `Delete` or `Update` an object?\n\nThat's done on the returned objects themselves, using the following `Updatable`, `Reconcilable` and `Deletable`\ninterfaces implemented by `{Org,User}Repository`, `DeployKey` and `TeamAccess`:\n\n```go\n// Updatable is an interface which all objects that can be updated\n// using the Client implement.\ntype Updatable interface {\n    // Update will apply the desired state in this object to the server.\n    // Only set fields will be respected (i.e. PATCH behaviour).\n    // In order to apply changes to this object, use the .Set({Resource}Info) error\n    // function, or cast .APIObject() to a pointer to the provider-specific type\n    // and set custom fields there.\n    //\n    // ErrNotFound is returned if the resource does not exist.\n    //\n    // The internal API object will be overridden with the received server data.\n    Update(ctx context.Context) error\n}\n\n// Deletable is an interface which all objects that can be deleted\n// using the Client implement.\ntype Deletable interface {\n    // Delete deletes the current resource irreversibly.\n    //\n    // ErrNotFound is returned if the resource doesn't exist anymore.\n    Delete(ctx context.Context) error\n}\n\n// Reconcilable is an interface which all objects that can be reconciled\n// using the Client implement.\ntype Reconcilable interface {\n    // Reconcile makes sure the desired state in this object (called \"req\" here) becomes\n    // the actual state in the backing Git provider.\n    //\n    // If req doesn't exist under the hood, it is created (actionTaken == true).\n    // If req doesn't equal the actual state, the resource will be updated (actionTaken == true).\n    // If req is already the actual state, this is a no-op (actionTaken == false).\n    //\n    // The internal API object will be overridden with the received server data if actionTaken == true.\n    Reconcile(ctx context.Context) (actionTaken bool, err error)\n}\n```\n\nIn order to access the provider-specific, internal object, all resources implement the `gitprovider.Object` interface:\n\n```go\n// Object is the interface all types should implement.\ntype Object interface {\n    // APIObject returns the underlying value that was returned from the server.\n    // This is always a pointer to a struct.\n    APIObject() interface{}\n}\n```\n\nSo, how do I set the desired state for an object before running `Update` or `Reconcile`?\n\nUsing the `Get() {Resource}Info` or `Set({Resource}Info) error` methods. An example as follows, for `TeamAccess`:\n\n```go\n// TeamAccess describes a binding between a repository and a team.\ntype TeamAccess interface {\n    // TeamAccess implements the Object interface,\n    // allowing access to the underlying object returned from the API.\n    Object\n    // The deploy key can be updated.\n    Updatable\n    // The deploy key can be reconciled.\n    Reconcilable\n    // The deploy key can be deleted.\n    Deletable\n    // RepositoryBound returns repository reference details.\n    RepositoryBound\n\n    // Get returns high-level information about this team access for the repository.\n    Get() TeamAccessInfo\n    // Set sets high-level desired state for this team access object. In order to apply these changes in\n    // the Git provider, run .Update() or .Reconcile().\n    Set(TeamAccessInfo) error\n}\n\n// TeamAccessInfo contains high-level information about a team's access to a repository.\ntype TeamAccessInfo struct {\n    // Name describes the name of the team. The team name may contain slashes.\n    // +required\n    Name string `json:\"name\"`\n\n    // Permission describes the permission level for which the team is allowed to operate.\n    // Default: pull.\n    // Available options: See the RepositoryPermission enum.\n    // +optional\n    Permission *RepositoryPermission `json:\"permission,omitempty\"`\n}\n```\n\n## Examples\n\nSee the following (automatically tested) examples:\n\n- [github/example_organization_test.go](github/example_organization_test.go)\n- [github/example_repository_test.go](github/example_repository_test.go)\n\n## Getting Help\n\nIf you have any questions about this library:\n\n- Read [the pkg.go.dev reference](https://pkg.go.dev/github.com/fluxcd/go-git-providers).\n- Invite yourself to the \u003ca href=\"https://slack.cncf.io\" target=\"_blank\"\u003eCNCF community\u003c/a\u003e\n  slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/)\n  channel.\n- To be part of the conversation about Flux's development, join the\n  [flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev).\n- [File an issue.](https://github.com/fluxcd/go-git-providers/issues/new)\n\nYour feedback is always welcome!\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluxcd%2Fgo-git-providers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluxcd%2Fgo-git-providers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluxcd%2Fgo-git-providers/lists"}