{"id":19040809,"url":"https://github.com/cloudfoundry/go-cfclient","last_synced_at":"2026-03-07T07:01:34.193Z","repository":{"id":23110728,"uuid":"26465103","full_name":"cloudfoundry/go-cfclient","owner":"cloudfoundry","description":"Golang client lib for Cloud Foundry","archived":false,"fork":false,"pushed_at":"2026-02-25T07:25:01.000Z","size":2259,"stargazers_count":70,"open_issues_count":5,"forks_count":133,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-02-25T12:40:02.934Z","etag":null,"topics":["client","cloudfoundry","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"morika-t/go-cfclient","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudfoundry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-11-11T02:02:52.000Z","updated_at":"2026-02-25T07:21:37.000Z","dependencies_parsed_at":"2023-02-12T00:16:50.816Z","dependency_job_id":"f4659644-f2aa-4178-b7f5-d831c035bffb","html_url":"https://github.com/cloudfoundry/go-cfclient","commit_stats":{"total_commits":608,"total_committers":108,"mean_commits":5.62962962962963,"dds":0.6266447368421053,"last_synced_commit":"1561eb61298b3a4982e5a387b630236ad55315d3"},"previous_names":["cloudfoundry/go-cfclient"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/cloudfoundry/go-cfclient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cfclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cfclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cfclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cfclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfoundry","download_url":"https://codeload.github.com/cloudfoundry/go-cfclient/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cfclient/sbom","scorecard":{"id":292789,"data":{"date":"2025-08-11","repo":{"name":"github.com/cloudfoundry/go-cfclient","commit":"2048735b23fb933a8c3b26afdb019d4708004381"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":6.3,"checks":[{"name":"Code-Review","score":8,"reason":"Found 7/8 approved changesets -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":10,"reason":"20 commit(s) and 2 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/golangci-lint.yml:13","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudfoundry/go-cfclient/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudfoundry/go-cfclient/build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/golangci-lint.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudfoundry/go-cfclient/golangci-lint.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/golangci-lint.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/cloudfoundry/go-cfclient/golangci-lint.yml/main?enable=pin","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/cloudfoundry/.github/SECURITY.md:1","Info: Found linked content: github.com/cloudfoundry/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/cloudfoundry/.github/SECURITY.md:1","Info: Found text in security policy: github.com/cloudfoundry/.github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T18:43:36.193Z","repository_id":23110728,"created_at":"2025-08-17T18:43:36.193Z","updated_at":"2025-08-17T18:43:36.193Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["client","cloudfoundry","golang"],"created_at":"2024-11-08T22:25:26.920Z","updated_at":"2026-03-07T07:01:34.186Z","avatar_url":"https://github.com/cloudfoundry.png","language":"Go","readme":"# go-cfclient\n\n[![build workflow](https://github.com/cloudfoundry/go-cfclient/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/cloudfoundry/go-cfclient/actions/workflows/build.yml)\n[![GoDoc](https://godoc.org/github.com/cloudfoundry/go-cfclient/v3?status.svg)](http://godoc.org/github.com/cloudfoundry/go-cfclient/v3)\n[![Report card](https://goreportcard.com/badge/github.com/cloudfoundry/go-cfclient/v3)](https://goreportcard.com/report/github.com/cloudfoundry/go-cfclient/v3)\n\n## Overview\n\n`go-cfclient` is a go module library to assist you in writing apps that need to interact the [Cloud Foundry](http://cloudfoundry.org)\nCloud Controller [v3 API](https://v3-apidocs.cloudfoundry.org). The v2 API is no longer supported, however if you **really**\nneed to use the older API you may use the go-cfclient v2 branch and releases.\n\n**NOTE** - The v3 version in the main branch is currently under development and may have **breaking changes** until a v3.0.0 release is\ncut. Until then, you may want to pin to a specific v3.0.0-alpha.x release.\n\n## Installation\n\ngo-cfclient is compatible with modern Go releases in module mode, with Go installed:\n\n```shell\ngo get github.com/cloudfoundry/go-cfclient/v3\n```\n\nWill resolve and add the package to the current development module, along with its dependencies. Eventually this\nlibrary will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the Versioning section below.\n\n## Usage\n\n- [Authentication](./README.md#authentication)\n- [Resources](./README.md#resources)\n- [Filtering](./README.md#filtering)\n- [Pagination](./README.md#pagination)\n- [Asynchronous Jobs](./README.md#asynchronous-jobs)\n- [Error Handling](./README.md#error-handling)\n- [Migrating v2 to v3](./README.md#migrating-v2-to-v3)\n\nUsing go modules import the client, config and resource packages:\n\n```go\nimport (\n    \"github.com/cloudfoundry/go-cfclient/v3/client\"\n    \"github.com/cloudfoundry/go-cfclient/v3/config\"\n    \"github.com/cloudfoundry/go-cfclient/v3/resource\"\n)\n```\n\n### Authentication\n\nConstruct a new CF client configuration object. The configuration object configures how the client will authenticate to the \nCF API. There are various supported auth mechanisms.\n\nThe simplest being - use the existing CF CLI configuration and auth token:\n\n```go\ncfg, _ := config.NewFromCFHome()\ncf, _ := client.New(cfg)\n```\n\nUsername and password:\n\n```go\ncfg, _ := config.New(\"https://api.example.org\", config.UserPassword(\"user\", \"pass\"))\ncf, _ := client.New(cfg)\n```\n\nClient and client secret:\n\n```go\ncfg, _ := config.New(\"https://api.example.org\", config.ClientCredentials(\"cf\", \"secret\"))\ncf, _ := client.New(cfg)\n```\n\nClient and client assertion:\n\n```go\ncfg, _ := config.New(\"https://api.example.org\", config.ClientCredentials(\"cf\",\"\"),config.ClientAssertion(\"client-assertion-token\"))\ncf, _ := client.New(cfg)\n```\n\nStatic OAuth token, which requires both an access and refresh token:\n\n```go\ncfg, _ := config.New(\"https://api.example.org\", config.Token(accessToken, refreshToken))\ncf, _ := client.New(cfg)\n```\n\nUsing JWT Bearer Assertion Grant\n\n```go\ncfg, _ := config.New(\"https://api.example.org\",config.JWTBearerAssertion(\"jwt-assertion-token\"))\ncf, _ := client.New(cfg)\n```\n\nFor more detailed examples of using the various authentication and configuration options, see the\n[auth example](./examples/auth/main.go).\n\n### Resources\n\nThe services of a client divide the API into logical chunks and correspond to the structure of the CF API documentation\nat [https://v3-apidocs.cloudfoundry.org](https://v3-apidocs.cloudfoundry.org). In other words each major resource type has its own service client that\nis accessible via the main client instance.\n\n```go\napps, _ := cf.Applications.ListAll(context.Background(), nil)\nfor _, app := range apps {\n    fmt.Printf(\"Application %s is %s\\n\", app.Name, app.State)\n}\n```\n\nAll clients and their functions that interact with the CF API live in the `client` package. The client package\nis responsible for making HTTP requests using the resources defined in the `resource` package. All generic serializable\nresource definitions live in the `resource` package and could be reused with other client's outside this library.\n\n**NOTE** - Using the context package you can easily pass cancellation signals and deadlines to various client calls\nfor handling a request. In case there is no context available, then `context.Background()` can be used as a starting\npoint.\n\n### Filtering\n\nThis library should support all possible\n[filtering combinations that the CF API supports](https://v3-apidocs.cloudfoundry.org/version/3.188.0/index.html#filters),\nincluding those that may not be valid. While the library tries to steer you in a direction that won't allow for invalid\ncombinations it's still possible to create filters that are nonsensical. The support matrix for filters:\n\n| Type | Multi-valued | Empty | Relational Op | Not |\n| --- | --- | --- | --- | --- |\n| Timestamp | x | | x | x |\n| String | x | x | | x |\n\nFull filtering example, find all apps with the name of spring-music:\n\n```go\nopts := client.NewAppListOptions()\nopts.Names.EqualTo(\"spring-music\")\napps, _ := cf.Applications.ListAll(context.Background(), opts)\nfmt.Printf(\"Found %d apps named spring-music\\n\", len(apps))\n```\n\nFind multiple applications with specific names:\n\n```go\nopts.Names.EqualTo(\"credit-processor-service\", \"credit-processor-ui\")\n```\n\nFind all apps not named spring-music:\n\n```go\nopts.Names.NotEqualTo(\"spring-music\")\n```\n\nFind all spring-music apps created within a date range:\n\n```go\nopts.Names.EqualTo(\"spring-music\")\nopts.CreateAts.After(date1)\nopts.CreateAts.Before(date2)\n```\n\n### Pagination\n\nAll requests for resource collections (apps, orgs, spaces etc) support pagination. Pagination options are described\nin the client.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific\nlist options struct (for example client.AppListOptions).\n\nExample iterating through all apps one page at a time:\n\n```go\nopts := client.NewAppListOptions()\nfor {\n    apps, pager, _ := cf.Applications.List(context.Background(), opts)\n    for _, app := range apps {\n        fmt.Printf(\"Application %s is %s\\n\", app.Name, app.State)\n    }  \n    if !pager.HasNextPage() {\n        break\n    }\n    pager.NextPage(opts)\n}\n```\n\nIf you'd rather get _all_ of the resources in one go and not worry about paging, every collection\nhas a corresponding `All` method that gathers all the resources from every page before returning. While this may be\nconvenient, this could have negative performance consequences on larger foundations/collections.\n\n```go\nopts := client.NewAppListOptions()\napps, _ := cf.Applications.ListAll(context.Background(), opts)\nfor _, app := range apps {\n    fmt.Printf(\"Application %s is %s\\n\", app.Name, app.State)\n}\n```\n\n### Asynchronous Jobs\n\nSome API calls are long-running so immediately return a JobID (GUID) instead of waiting and returning a resource. In\nthose cases you only know if the job was accepted. You will need to poll the Job API to find out when the job\nfinishes. There's a `PollComplete` utility function that you can use to block until the job finishes:\n\n```go\njobGUID, err := cf.Manifests.ApplyManifest(context.Background(), spaceGUID, manifest))\nif err != nil {\n    return err\n}\nopts := client.NewPollingOptions()\nerr = cf.Jobs.PollComplete(context.Background(), jobGUID, opts)\nif err != nil {\n    return err\n}\n```\n\nThe timeout and polling interval can be configured using the PollingOptions struct.\n\nThe PollComplete function will return a nil error if the job completes successfully. If PollComplete\ntimes out waiting for the job to complete a `client.AsyncProcessTimeoutError` is returned. If the job itself\nfailed then the job API is queried for the job error which is then returned as a `resource.CloudFoundryError`\nwhich can be inspected to find the failure cause.\n\n### Error Handling\n\nAll client methods will return a `resource.CloudFoundryError` or sub-type for any response that isn't a 200 level\nstatus code. All CF errors have a corresponding error code and the client uses those codes to construct a specific\nclient side error type. This allows you to easily branch your logic based off specific API error codes using one of\nthe many `resource.IsSomeTypeOfError(err error)` functions, for example:\n\n```go\nparams, err := cf.ServiceCredentialBindings.GetParameters(guid)\nif resource.IsServiceFetchBindingParametersNotSupportedError(err) {\n    fmt.Println(err.(resource.CloudFoundryError).Detail)\n} else if err != nil {\n    return err // all other errors\n} else {\n    fmt.Printf(\"Parameters: %v\\n\", params)\n}\n```\n\n### Migrating v2 to v3\n\nA very basic example using the v2 client:\n\n```go\nc := \u0026cfclient.Config{\n    ApiAddress: \"https://api.sys.example.com\",\n    Username:   \"user\",\n    Password:   \"password\",\n}\nclient, _ := cfclient.NewClient(c)\napps, _ := client.ListApps()\nfor _, a := range apps {\n    fmt.Println(a.Name)\n}\n```\n\nConverted to do the same in the v3 client:\n\n```go\ncfg, _ := config.New(\"https://api.sys.example.org\", config.UserPassword(\"user\", \"pass\"))\nclient, _ := client.New(cfg)\napps, _ := client.Applications.ListAll(context.Background(), nil)\nfor _, app := range apps {\n    fmt.Println(app.Name)\n}\n```\n\nIf you need to migrate over to the new client iteratively you can do that by referencing both the old and new modules\nsimultaneously and creating two separate client instances - one for each module version.\n\nSome of the main differences between the old client and the new v3 client include:\n\n- The old v2 client supported most v2 resources and few a v3 resources. The new v3 client supports all v3 resources and\nno v2 resources. While most v2 resources are similar to their v3 counterparts, some code changes will need to be made.\n- The v2 client had a single type that contained resource functions disambiguated by function name. The v3\nclient has a separate client nested under the main client for each resource. For example:\n`client.ListApps()` vs `client.Applications.ListAll()`\n- All v3 client functions take a cancellable context object as their first parameter.\n- All v3 client list functions take a type specific options struct that support type safe filtering.\n- All v3 client list functions support paging natively in the client for ease of use.\n- The v3 client supports shared access across goroutines.\n\n## Versioning\n\nIn general, go-cfclient follows [semver](https://go.dev/doc/modules/version-number) as closely as we can for [tagging\nreleases](https://go.dev/doc/modules/publishing) of the package. We've adopted the following versioning policy:\n\n- We increment the major version with any incompatible change to non-preview functionality, including changes to the exported Go API surface or behavior of the API.\n- We increment the minor version with any backwards-compatible changes to functionality\n- We increment the patch version with any backwards-compatible bug fixes.\n\n## Development\n\nAll development takes place on feature branches and is merged to the `main` branch. Therefore the main\nbranch is considered a potentially unstable branch until a new release (see below) is cut.\n\n```shell\nmake all\n```\n\nPlease attempt to use standard go naming conventions for all structs, for example use GUID over Guid. All client\nfunctions should have at least once basic unit test.\n\n### Errors\n\nIf the Cloud Foundry error definitions change at [https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml](https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml)\nthen the error predicate functions in this package need to be regenerated.\n\nTo do this, simply use Go to regenerate the code:\n\n```shell\nmake generate\n```\n\n## Contributing\n\nPull requests welcome. Please ensure you run all the unit tests, go fmt the code, and golangci-lint via `make all`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fgo-cfclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfoundry%2Fgo-cfclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fgo-cfclient/lists"}