{"id":19905562,"url":"https://github.com/ekristen/go-project-template","last_synced_at":"2026-01-24T01:21:01.671Z","repository":{"id":173802688,"uuid":"651312482","full_name":"ekristen/go-project-template","owner":"ekristen","description":"Opinionated Go Project Template","archived":false,"fork":false,"pushed_at":"2025-01-08T14:33:26.000Z","size":118,"stargazers_count":5,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-08T15:53:55.555Z","etag":null,"topics":["automated","golang","goreleaser","mkdocs-material","opinionated","renovate","template"],"latest_commit_sha":null,"homepage":"https://ekristen.github.io/go-project-template/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ekristen.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-09T01:24:21.000Z","updated_at":"2025-01-08T14:33:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"af0a0001-22bb-473a-b369-cf9bf7b76984","html_url":"https://github.com/ekristen/go-project-template","commit_stats":null,"previous_names":["ekristen/go-project-template"],"tags_count":39,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekristen%2Fgo-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekristen%2Fgo-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekristen%2Fgo-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekristen%2Fgo-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ekristen","download_url":"https://codeload.github.com/ekristen/go-project-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234152694,"owners_count":18787672,"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":["automated","golang","goreleaser","mkdocs-material","opinionated","renovate","template"],"created_at":"2024-11-12T20:33:54.327Z","updated_at":"2025-09-25T04:31:43.021Z","avatar_url":"https://github.com/ekristen.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go Project Template\n\nThis is an opinionated go project template to use as a starting point for new projects.\n\n## Features\n\n- Builds with [GoReleaser](https://goreleaser.com)\n  - Automated with GitHub Actions\n  - Signed with Cosign (providing you generate a private key)\n- Linting with [golangci-lint](https://golangci-lint.run/)\n  - Automated with GitHub Actions\n- Builds with Docker\n  - While designed to use goreleaser, you can still just run `docker build`\n- Apple Notary Signing Support\n- Opinionated Layout\n  - Never use `internal/` folder\n  - Everything is under `pkg/` folder\n- Commits must meet [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)\n  - Automated with GitHub Actions ([commit-lint](https://github.com/conventional-changelog/commitlint/#what-is-commitlint))\n- Automatic Dependency Management with [Renovate](https://github.com/renovatebot/renovate)\n- Automatic [Semantic Releases](https://semantic-release.gitbook.io/)\n- Documentation with Material for MkDocs\n- API Server Example\n  - Uses Gorilla Mux (yes it's been archived, still the best option)\n- Stubbed out Go Tests (**note:** they are not comprehensive)\n\n### Opinionated Decisions\n\n- Uses `init` functions for registering commands globally.\n  - This allows for multiple `main` package files to be written and include different commands.\n  - Allows the command code to remain isolated from each other and a simple import to include the command.\n\n### Multi-Platform Builds\n\nThis project is designed to build for multiple platforms, including macOS, Linux, and Windows. It also supports\nmultiple architectures including amd64 and arm64. \n\nThe goreleaser configuration is set up to build for all platforms and architectures by default. It even supports pushing\nmulti-architecture docker manifests by default. Some knowledge about GoReleaser's configuration is required should you\nwant to remove these capabilities.\n\n### Apple Notary Signing\n\nThis makes use of a tool called [quill](https://github.com/anchore/quill). To make use of this feature you will need\nto have an Apple Developer account and be able to create an Developer ID certificate.\n\nThe workflow is designed to pull the necessary secrets from 1Password. This is done to keep the secrets out of the\nGitHub Actions logs. The secrets are pulled from 1Password if the event triggering the workflow is a tag **AND** the\nactor is the owner of the repository. This is to prevent forks from being able to pull the secrets and is an extra\nguard to help prevent theft.\n\nGoReleaser is configured to always sign and notarize for macOS. However, it will not notarize if the build is a snapshot.\n\nIf configured properly, the binaries located within the archives produced by GoReleaser will be signed and notarized\nby the Apple Notary Service and will automatically run on any macOS system without having to approve it under System\nPreferences.\n\nIf you do not wish to use 1Password simply export the same environment variables using secrets to populate them. The \n`QUILL_SIGN_P12` and `QUILL_NOTARY_KEY` need to be base64 encoded or paths to the actual files.\n\n## Building\n\nThe following will build binaries in snapshot order.\n\n```console\ngoreleaser --clean --snapshot --skip sign\n```\n\n**Note:** we are skipping signing because this project uses cosign's keyless signing with GitHub Actions OIDC provider.\n\nYou can opt to generate a cosign keypair locally and set the following environment variables, and then you can run\n`goreleaser --clean --snapshot` without the `--skip sign` flag to get signed artifacts.\n\nEnvironment Variables:\n- \n- COSIGN_PASSWORD\n- COSIGN_KEY (path to the key file) (recommend cosign.key, it is git ignored already)\n\n```console\ncosign generate-key-pair\n```\n\n## Configure\n\n1. Rename Repository\n2. Generate Cosign Keys (optional if you want to run with signing locally, see above)\n3. Update `.goreleaser.yml`, search/replace go-project-template with new project name, adjust GitHub owner\n4. Update `main.go`,\n5. Update `go.mod`, rename go project (using IDE is best so renames happen across all files)\n\n### Docker\n\nThe Dockerfile is set up to build the project and then copy the artifacts from the build into the final image. It is\nalso configured to allow you to just run `docker build` directly if you do not want to use GoReleaser. \n\nTo make things easier and faster, the Dockerfile has a default build argument set to `go-project-template`. GoReleaser\nwill pass the new project name down (if you update the `.goreleaser.yml` file) and the Dockerfile will use that instead.\n\nHowever, it would be better longer term to update this argument in the file or remove it all together.\n\n### Signing\n\nSigning happens via cosign's keyless features using the GitHub Actions OIDC provider.\n\n### Releases\n\nIn order for Semantic Releases and GoReleaser to work properly you have to create a PAT to run Semantic Release\nso it's actions against the repository can trigger other workflows. Unfortunately there is no way to trigger\na workflow from a workflow if both are run by the automatically generated GitHub Actions secret.\n\n1. Create PAT that has content `write` permissions to the repository\n2. Create GitHub Action Secret\n   - `SEMANTIC_GITHUB_TOKEN` -\u003e populated with PAT from step 1\n3. Done\n\n## Documentation\n\nThe project is built to have the documentation right alongside the code in the `docs/` directory leveraging Mkdocs Material.\n\nIn the root of the project exists mkdocs.yml which drives the configuration for the documentation.\n\nThis README.md is currently copied to `docs/index.md` and the documentation is automatically published to the GitHub\npages location for this repository using a GitHub Action workflow. It does not use the `gh-pages` branch.\n\n### Running Locally\n\n```console\nmake docs-serve\n```\n\nOR (if you have docker)\n\n```console\ndocker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekristen%2Fgo-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fekristen%2Fgo-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekristen%2Fgo-project-template/lists"}