{"id":19039897,"url":"https://github.com/cert-manager/issuer-lib","last_synced_at":"2025-09-01T17:46:28.569Z","repository":{"id":164778155,"uuid":"639413479","full_name":"cert-manager/issuer-lib","owner":"cert-manager","description":"issuer-lib is the Go library for building cert-manager issuers.","archived":false,"fork":false,"pushed_at":"2025-08-29T02:59:40.000Z","size":986,"stargazers_count":11,"open_issues_count":10,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-29T06:51:38.500Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/cert-manager.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-11T12:30:02.000Z","updated_at":"2025-08-27T01:45:08.000Z","dependencies_parsed_at":"2023-12-24T09:34:21.401Z","dependency_job_id":"f67285f5-6850-4d0e-8817-968a2ca3a725","html_url":"https://github.com/cert-manager/issuer-lib","commit_stats":{"total_commits":97,"total_committers":7,"mean_commits":"13.857142857142858","dds":"0.35051546391752575","last_synced_commit":"b443b10925b76f80e40dc32be8cbe990be5a78d7"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/cert-manager/issuer-lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cert-manager%2Fissuer-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cert-manager%2Fissuer-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cert-manager%2Fissuer-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cert-manager%2Fissuer-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cert-manager","download_url":"https://codeload.github.com/cert-manager/issuer-lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cert-manager%2Fissuer-lib/sbom","scorecard":{"id":271330,"data":{"date":"2025-08-11","repo":{"name":"github.com/cert-manager/issuer-lib","commit":"2ef15821de11997e75aa3f57fb13c903fb7ff5ff"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":8.2,"checks":[{"name":"Code-Review","score":10,"reason":"all changesets reviewed","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":"30 commit(s) and 1 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":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: 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":"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":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Warn: jobLevel 'contents' permission set to 'write': .github/workflows/make-self-upgrade.yaml:21","Info: topLevel 'contents' permission set to 'read': .github/workflows/govulncheck.yaml:14","Info: topLevel 'contents' permission set to 'read': .github/workflows/make-self-upgrade.yaml:12"],"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":"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":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info:   5 out of   5 GitHub-owned 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":"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: Apache License 2.0: 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":"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":"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":"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"}},{"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"}}]},"last_synced_at":"2025-08-17T13:26:57.253Z","repository_id":164778155,"created_at":"2025-08-17T13:26:57.253Z","updated_at":"2025-08-17T13:26:57.253Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272666708,"owners_count":24972732,"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","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-11-08T22:19:26.314Z","updated_at":"2025-09-01T17:46:28.524Z","avatar_url":"https://github.com/cert-manager.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cert-manager/cert-manager/d53c0b9270f8cd90d908460d69502694e1838f5f/logo/logo-small.png\" height=\"256\" width=\"256\" alt=\"cert-manager project logo\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://godoc.org/github.com/cert-manager/issuer-lib\"\u003e\u003cimg src=\"https://godoc.org/github.com/cert-manager/issuer-lib?status.svg\" alt=\"cert-manager/issuer-lib godoc\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/cert-manager/issuer-lib\"\u003e\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/cert-manager/issuer-lib\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# cert-manager issuer-lib\n\n\u003e issuer-lib is the Go library for building cert-manager issuers.\n\n## Stability disclaimer\n\n⚠️ Warning: This library's API is still subject to change. Developers using this library will have to update their\ncode when updating to a newer version.\n\n0. Currently, this library is used to build production Issuers, but no open-source Issuers/ examples are available yet. We advise to use this library only for experimentation.\n1. Once we have an open-source Issuer\nthat uses this library \u0026 we have an example project that shows how to use this library, we will start advising developers to build all new issuers on top of this library.\n2. Once we have a 2nd or 3rd open-source Issuer that uses this library, we should be able to guarantee more stability.\nAt this point, we will start advising developers to migrate their existing Issuers to this library.\n3. At 5+ open-source Issuers, we plan to make a stable v1 release of this library.\n\n## Introduction\n\ncert-manager issuers are responsible for watching CertificateRequest resources and updating\ntheir status with the signed certificate data. An issuer must only respond to\nCertificateRequests that have an IssuerRef that matches the Name, Kind and group\nof one of its Issuer resources. Additionally, the CertificateRequest must have been approved.\n\nThis library provides all the controllers necessary to implement a cert-manager\nissuer, these controllers contain all the common logic required to implement\nan issuer. The only thing you need to provide is the business logic for\ncommunicating with your CA, this is done by implementing the `Sign` and `Check`\nfunctions.\n\n## Goals\n\nThis library makes it easy to create a cert-manager issuer that integrates with\nyour CA.\n\nIt takes care of:\n\n- Watching CertificateRequests and your custom Issuer resources\n- Updating the Issuer status with status of the CA\n- Updating the CertificateRequest status with the signed certificate data\n- Handling errors and retries\n- Handling CertificateRequest approval and denial\n- Handling issuance of Kubernetes CSR resources\n- [FUTURE] Provide a set of conformance tests for issuers\n\n## Usage\n\nAn example issuer implementation can be found in the [`./examples/simple`](./examples/simple) subdirectory.\n\n## Log levels\n\nThe library relies on the log levels defined in `logr`, i.e., numbers from 0 to\n9\\. You can use any logging library you like in your controller as long as the\nlevels \"match\". The two only logr levels used in issuer-lib are 0 (\"info\") and 1\n(\"debug\").\n\nFor example, the message \"Succeeded signing the CertificateRequest\" is logged at\nthe level 0 (\"info\"). To integrate well with issuer-lib, your controller should\nalso use the level 0 when logging messages that inform the user about changes to\nthe CertificateRequest.\n\n## How it works\n\nThis repository provides a go libary that you can use for creating cert-manager controllers for your own Issuers.\n\nTo use the libary, your Issuer API types have to implement the `v1alpha1.Issuer` interface.\nThe business logic of the controllers can be provided to the libary through the `Check` and `Sign` functions.\n- The `Check` function is used by the Issuer controllers.  \nIf it returns a normal error, the controller will retry with backoff until the `Check` function succeeds.  \nIf the error is of type `signer.PermanentError`, the controller will not retry automatically. Instead, an increase in Generation is required to recheck the issuer.\n\n- The `Sign` function is used by the CertificateRequest controller.\nIf it returns a normal error, the `Sign` function will be retried as long as we have not spent more than the configured `MaxRetryDuration` after the certificate request was created.  \nIf the error is of type `signer.IssuerError`, the error is an error that should be set on the issuer instead of the CertificateRequest.  \nIf the error is of type `signer.SetCertificateRequestConditionError`, the controller will, additional to setting the ready condition, also set the specified condition. This can be used in case we have to store some additional state in the status.  \nIf the error is of type `signer.PermanentError`, the controller will not retry automatically. Instead, a new CertificateRequest has to be created.\n\n## Reconciliation loops\n\nThe reconciliation function of the CertificateRequest controller will:\n1. wait for the request to be Approved/ Denied\n2. only consider the configured Issuer API types\n3. leave Ready/ Failed/ Denied CertificateRequests as-is\n4. start by setting the Ready condition to Initializing\n5. set the Ready condition to Denied if the CertificateRequest is denied\n6. wait for the linked Issuer to exist and be in an up-to-date Ready state\n7. call the `Sign` function and handle errors as described above\n8. update the CertificateRequest with the returned Signed Certificate and set the state to Ready\n\nThe reconciliation function of the Issuer controllers will:\n1. only reconcile if the Ready condition is not \"failed permanently\" or the CertificateRequest controller notified that the Ready condition is no longer valid\n2. if the issuer status is Ready and we received an issuer error from the CertificateRequest controller, set the Ready condition to false and set the error\n3. start by setting the Ready condition to Initializing\n4. call the `Check` function and handle errors as described above\n5. update the Issuer by setting the state to Ready\n\nNote that a reconciliation will only be triggered:\n- for CertificateRequests:\n    - on create\n    - on update when an annotation is changed/ added or removed\n    - on update when a condition is added or removed\n    - on update when a non-readiness condition is changed\n    - on update when the Ready condition of the linked Issuer is changed/ added or removed\n    - when triggered in the previous reconciliation\n\n- for Issuers:\n    - on create\n    - on update when an annotation is changed/ added or removed\n    - on update when the generation (.Spec) changes\n    - on update when the Ready condition was added/ removed\n    - when triggered in the previous reconciliation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcert-manager%2Fissuer-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcert-manager%2Fissuer-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcert-manager%2Fissuer-lib/lists"}