feat: activity service overview

[scotwells]

Summary

Introduce high-level overview of the Activity service that provides human-readable activity records for platform operations.

Key sections:

• Examples: DNS Zone and Proxy activity timelines demonstrating how activity records tell the story of resource changes
• User stories for consumers, service providers, and platform administrators
• Key capabilities: activity viewing, filtering (time range, actor, service, action type, source, outcome), 31-day retention, and IAM-based access control

---

Relates to #469

[drewr]

Looks really good. Dumb question but this is fleshing out how to use the activity API right?

[drewr]

Is this a starting point, or do we want to limit to 31 days? I'm assuming we can tune this over time, so this isn't a major point.

I was curious how long, eg, GitHub retains them. Below is what Copilot told me.

---

Short answer: it depends on the type of log. On GitHub.com most built‑in activity logs are retained for about 90 days by default, but retention varies by product and can often be extended by exporting or using enterprise features.

Quick reference (common log types)

• Organization / enterprise audit logs (GitHub.com): retained ~90 days by default. Enterprise customers can stream/export audit data to an external SIEM for long‑term retention or use Enterprise Server where admins can configure retention.
  • Docs: Review the audit log for your organization — https://docs.github.com/en/organizations/keeping-your-organization-secure/reviewing-audit-logs-for-your-organization
  • Streaming/exporting audit logs — https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring/streaming-audit-logs-to-your-log-management-solution
• GitHub Actions workflow run logs: default/maximum retention is usually 90 days on GitHub.com. Repository or enterprise settings can change retention between 1–90 days for private repos; public repo artifact/log retention policies differ. You can also upload artifacts or export logs to external storage.
  • Docs: Configuring log retention for workflows — https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/configuring-log-retention-for-workflows
• Webhook delivery history / delivery attempts: generally viewable in the repo/org UI for a limited time (commonly 90 days). If you need longer history, log deliveries on your webhook endpoint or send them to an external store.
• Dependabot/Security alerts, code scanning results, issue/PR events: retention and visibility depend on the feature; many are kept indefinitely in the repository history (issues/PRs remain until deleted), but short‑lived derived artifacts (alerts, temporary logs) may follow shorter retention windows.
• GitHub Enterprise Server: retention is configurable by admins (audit, logs, Actions) because you control the server and storage.

If you tell me which specific activity log you mean (organization audit log, Actions workflow logs, webhook deliveries, security alerts, etc.) and whether you’re on GitHub.com, Enterprise Cloud, or Enterprise Server, I’ll give the exact retention details and the steps to extend/export those logs.

[scotwells]

I don't have a strong opinion on retention period for these since they're just the human-descriptive activity logs. I'd be surprised if folks looked further back than 30 days.

Audit logs are more crucial to retain long-term which we store indefinitely right now (moved to cold storage after 90 days).

[jacobsmith928]

@scotwells and @drewr this caught my eye as well. The main use case beyond convenience is usually related to compliance.

"SaaS activity logs should generally be retained for 12 to 24 months for security monitoring, debugging, and audit compliance. While 90 days is common for basic usage, regulatory requirements like HIPAA or SOC 2 often dictate 6 months to 7 years, depending on the industry and risk profile."

Also as we look at audit logs:
https://www.enterpriseready.io/features/audit-log/

Customizable retention time
By default an audit log should generally be kept for 1-3 years. The specific default timeframe should be documented but also made configurable (generally shorter) for customers who have data retention requirements."

[scotwells]

I would expect compliance to be handled by Audit logs since that tracks every action across the platform for a user's organization. The activity log will only show a subset of activity based on what we feel is important to surface to the user.

That's why I had compliance as a non-goal for this enhancement, it's already solved for with our raw audit log source.

• Compliance reporting (use raw audit logs for compliance requirements)

[drewr]

These look good 👍

[drewr]

(Yes, to my question, looking back at #469...)

[scotwells]

@drewr it's just focused on what functionality should be expected from the service. Technical details / user guides on how to use the activity service would be in a separate document.

[jacobsmith928]

...users and agents.... (let's try to bring forward AX in our planning)

[scotwells]

@jacobsmith928 agents probably would care more about seeing audit logs since they're well structured. I could add a note that agents can retrieve the raw data sources directly.

[jacobsmith928]

Thanks! Not looking to go crazy, just keep the context top of mind that the human might be interacting through different tools with assistance.

[jacobsmith928]

Overall looks good, i think let's just align our retention policies with industry standards. It would be great to explicitly call out a few scaling Alt Clouds that we love and respect as examples to shoot for.

[drewr]

Agree that the scope for activity logs is humans not agents, and that the retention if more important for audit logs than activity (which should be able to be regenerated from audit logs if it's really necessary).