diff --git a/docs/developer-docs/secrets.md b/docs/developer-docs/secrets.md new file mode 100644 index 000000000..b4ba8118e --- /dev/null +++ b/docs/developer-docs/secrets.md @@ -0,0 +1,68 @@ +# Secrets management + +This document covers secrets management for the github/copilot-sdk repository. It lists the GitHub Actions secrets that maintainers must keep configured and not expired. + +> [!WARNING] +> If any of these secrets expire or are revoked, the corresponding workflows will fail silently or with opaque permission errors. Review this list periodically and rotate secrets before they expire. + +## SDK test secrets + +These secrets are used by the per-language SDK test workflows and the canary workflow. + +* **`COPILOT_DEVELOPER_CLI_INTEGRATION_HMAC_KEY`**: HMAC key used to authenticate with the Copilot Developer CLI integration endpoint during tests. Injected as `COPILOT_HMAC_KEY` in test environments. + * Workflows: `nodejs-sdk-tests.yml`, `python-sdk-tests.yml`, `go-sdk-tests.yml`, `dotnet-sdk-tests.yml`, `rust-sdk-tests.yml`, `sdk-canary.yml` + +## Agentic workflow secrets + +These secrets power the GitHub Agentic Workflows (gh-aw) used for issue triage, code generation, and release automation. + +* **`COPILOT_GITHUB_TOKEN`**: GitHub OAuth token consumed by the Copilot CLI for AI authentication. Required by all agentic workflows when invoking `copilot` for AI inference. + * Workflows: `issue-triage.lock.yml`, `issue-classification.lock.yml`, `handle-bug.lock.yml`, `handle-enhancement.lock.yml`, `handle-question.lock.yml`, `handle-documentation.lock.yml`, `java-codegen-check.yml`, `java-codegen-fix.lock.yml`, `java-smoke-test.yml`, `java-adapt-handwritten-code-to-accept-upgrade-changes.lock.yml`, `release-changelog.lock.yml`, `sdk-consistency-review.lock.yml`, `cross-repo-issue-analysis.lock.yml` + +* **`GH_AW_GITHUB_TOKEN`**: Optional GitHub token override for repository operations (reading code, creating pull requests, and making GitHub API calls). If unset, workflows use the automatic `GITHUB_TOKEN`. + * Workflows: `issue-triage.lock.yml`, `issue-classification.lock.yml`, `handle-bug.lock.yml`, `handle-enhancement.lock.yml`, `handle-question.lock.yml`, `handle-documentation.lock.yml`, `java-codegen-fix.lock.yml`, `java-adapt-handwritten-code-to-accept-upgrade-changes.lock.yml`, `release-changelog.lock.yml`, `sdk-consistency-review.lock.yml`, `cross-repo-issue-analysis.lock.yml` + +* **`GH_AW_GITHUB_MCP_SERVER_TOKEN`**: Optional token override for the GitHub MCP server container. If unset, workflows fall back to `GH_AW_GITHUB_TOKEN` and then the automatic `GITHUB_TOKEN`. + * Workflows: `issue-triage.lock.yml`, `issue-classification.lock.yml`, `handle-bug.lock.yml`, `handle-enhancement.lock.yml`, `handle-question.lock.yml`, `handle-documentation.lock.yml`, `java-codegen-fix.lock.yml`, `java-adapt-handwritten-code-to-accept-upgrade-changes.lock.yml`, `release-changelog.lock.yml`, `sdk-consistency-review.lock.yml`, `cross-repo-issue-analysis.lock.yml` + +* **`GH_AW_CI_TRIGGER_TOKEN`**: Token used to trigger CI workflows from within agentic workflow runs. + * Workflows: `java-codegen-fix.lock.yml`, `java-adapt-handwritten-code-to-accept-upgrade-changes.lock.yml`, `release-changelog.lock.yml` + +* **`RUNTIME_TRIAGE_TOKEN`**: Token with read access to `github/copilot-agent-runtime`. Used to clone that repository and make GitHub API calls for cross-repo issue analysis. + * Workflows: `cross-repo-issue-analysis.lock.yml` + +## Java publishing secrets + +These secrets are used by the Java SDK Maven Central publishing workflow (`java-publish-maven.yml`) and the snapshot publishing workflow (`java-publish-snapshot.yml`). + +* **`JAVA_MAVEN_CENTRAL_USERNAME`**: Username generated by a Maven Central Portal user token. + * Workflows: `java-publish-maven.yml`, `java-publish-snapshot.yml` + +* **`JAVA_MAVEN_CENTRAL_PASSWORD`**: Password or token for Maven Central (Sonatype OSSRH) authentication. + * Workflows: `java-publish-maven.yml`, `java-publish-snapshot.yml` + +* **`JAVA_GPG_SECRET_KEY`**: GPG private key used to sign Java release artifacts for Maven Central. + * Workflows: `java-publish-maven.yml` + +* **`JAVA_GPG_PASSPHRASE`**: Passphrase for the GPG signing key. + * Workflows: `java-publish-maven.yml` + +* **`JAVA_RELEASE_TOKEN`**: GitHub token with **push** permission on the repository. Used by the release workflow for `actions/checkout`, pushing release commits and tags to `main`, and running `mvn release:prepare -DpushChanges=true`. + * Workflows: `java-publish-maven.yml` + +* **`JAVA_RELEASE_GITHUB_TOKEN`**: GitHub token with **workflow dispatch** (actions:write) permission on this repository and `github/copilot-sdk-java`. Used to trigger the `release-changelog.lock.yml` workflow and the documentation site deployment after a release is published. + * Workflows: `java-publish-maven.yml` + +## Rust publishing secret + +* **`CARGO_REGISTRY_TOKEN`**: Authentication token for publishing the Rust SDK crate to crates.io. + * Workflows: `publish.yml` + +## Secrets not managed in this repository + +* **`GITHUB_TOKEN`**: Automatically provided by GitHub Actions. No manual management required. + +## Further reading + +* [GitHub docs: Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) +* [Repository secrets settings](https://github.com/github/copilot-sdk/settings/secrets/actions) (maintainer access required)