feat(deliverables): add dev-helpers suite for GitHub automation friction - #285
Closed
fig-ai-agent[bot] wants to merge 88 commits into
Closed
fig-ai-agent[bot] wants to merge 88 commits into
fig-ai-agent[bot] wants to merge 88 commits into
Conversation
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
…p conditions (#243) The workflow on main failed all 781 runs: five action refs point at commit SHAs that do not exist upstream (Set up job -> "unable to find version"). Replaced with SHAs verified against the commit API. Implements the four documented skip conditions: 1. on.paths trigger filters (images + web assets) 2. bot-loop guard on scan — github.ref AND github.head_ref, null-safe 3. inputs.target gating on compress-images / compress-web 4. summary skips when both children are skipped Three intentional deviations from the original spec, each noted in the README: - '**/*.ext' instead of '**.ext' (the latter is YAML-invalid, not a GitHub glob) - head_ref added to the bot guard (github.ref is refs/pull/N/merge on PRs) - compression-level: 0 on upload-artifact (payload is already compressed) Ships to deliverables/ci/ because the GitHub App lacks the workflows permission to write .github/workflows/ directly. Includes a 26-check validator. Co-authored-by: fig-ai-agent <fig-ai-agent@users.noreply.github.com>
Co-authored-by: Fig AI Agent <fig-ai-agent@users.noreply.github.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Supabase Oauth Apps Documents GuidelinesSupabase Oauth Apps Documents Guidelines
## Supabase OAuth app guidelines
This guide covers documentation for **Supabase OAuth applications**, including OAuth provider login and Supabase’s OAuth 2.1 server. These are related but different:
- **Social login:** Your Supabase project acts as the OAuth client and lets users sign in with Google, GitHub, Azure, or another provider.
- **OAuth 2.1 server:** Your Supabase project acts as the authorization server, and external applications register as OAuth clients.[1][2]
## Document the OAuth app
Use one record per OAuth application:
```yaml
oauth_app:
name: "Example Web Application"
environment: production
owner: "Platform Engineering"
purpose: "User authentication"
provider: "Google"
client_type: confidential
client_id_location: "Secrets manager: prod/oauth/example/client-id"
client_secret_location: "Secrets manager: prod/oauth/example/client-secret"
redirect_uris:
- "https://app.example.com/auth/callback"
supabase_callback_uri:
- "https://project-ref.supabase.co/auth/v1/callback"
scopes:
- "openid"
- "email"
- "profile"
consent_behavior: "User consent required"
status: active
created_at: "YYYY-MM-DD"
secret_expires_at: "YYYY-MM-DD"
review_date: "YYYY-MM-DD"
```
Do not put client secrets, refresh tokens, private keys, or access tokens directly into the document. Store them in a secrets manager and record only the secret reference.
## Redirect URI rules
Redirect URIs are security-critical. The URI registered with the OAuth provider must match the configured application flow exactly. Supabase’s allow list controls where users can be redirected after authentication, and the `redirectTo` value used by the client must match that allow list. The Site URL is used when no specific redirect is supplied.[3]
Recommended rules:
- Use HTTPS in staging and production.
- Register exact production callback URLs.
- Keep localhost URLs limited to development.
- Do not use broad wildcards in production.
- Keep preview wildcards restricted to a controlled subdomain.
- Maintain separate redirect URIs for development, staging, and production.
- Review every redirect URI during security audits.
- Remove old callback URLs after migrations.
For a standard Supabase social-login provider, the provider callback generally follows:
```text
https://<project-ref>.supabase.co/auth/v1/callback
```
The exact callback should be copied from the provider configuration in the Supabase Dashboard rather than typed manually.[4][5]
## Client type
For Supabase OAuth 2.1 applications, document the client type:
| Client type | Use case | Secret |
|---|---|---|
| Public | Mobile apps, browser-only apps, single-page applications | No client secret |
| Confidential | Server-side web applications and backend services | Client secret required |
Supabase documents these two choices when registering an OAuth client under **Authentication → OAuth Apps**.[2]
Never embed a confidential client secret in frontend JavaScript, a mobile binary, a public repository, or a downloadable desktop application.
## Scopes and consent
Document the smallest scope set required:
```yaml
scopes:
- openid
- email
- profile
```
Avoid requesting additional provider permissions unless the feature needs them. For calendar, file, email, or administrative access, document:
- Why the scope is needed.
- Which feature uses it.
- Whether it is read-only or write-enabled.
- Whether consent is shown to the user.
- How tokens are stored and revoked.
- How access is removed when the user disconnects.
OAuth allows users to grant an application access without sharing their password, but the scope still determines what the application can do.[1]
## Provider configuration
For each external provider, document:
- Provider name.
- Developer-console application name.
- Client ID location.
- Client-secret location.
- Authorized JavaScript origins, if applicable.
- Authorized redirect URIs.
- Requested scopes.
- Consent-screen status.
- Test users or assigned users.
- Production approval status.
- Secret expiration date.
- Provider owner.
For Google, Supabase’s setup requires an OAuth client ID for a web application, the application URL under authorized JavaScript origins, and the Supabase callback URL under authorized redirect URIs.[4]
For Azure, record the client-secret expiry date and create a renewal reminder well in advance. Microsoft’s provider configuration requires the **secret value**, not the secret ID, in the Supabase configuration.[6]
## OAuth 2.1 server records
If Supabase is acting as the authorization server, use this additional structure:
```yaml
oauth_client:
client_name: "Partner Integration"
client_type: confidential
client_id: "stored-in-secrets-manager"
redirect_uris:
- "https://partner.example.com/oauth/callback"
allowed_scopes:
- "openid"
- "email"
owner: "Partner Engineering"
approval_ticket: "SEC-0000"
created_at: "YYYY-MM-DD"
last_reviewed: "YYYY-MM-DD"
status: active
```
Supabase’s OAuth 2.1 setup requires enabling the server, configuring the authorization path, building the authorization UI, and registering client applications. The authorization request uses parameters such as `client_id`, `redirect_uri`, `response_type=code`, and `state`.[2][7]
Use the authorization-code flow with PKCE where supported. Validate:
- `state` to prevent request forgery.
- `redirect_uri` against the registered value.
- `code_verifier` and `code_challenge` for PKCE.
- Token issuer and audience.
- Token expiration.
- Required scopes.
- User consent status.
The `state` value should not contain sensitive information, and Supabase documents a combined size limit of 4 kB for `redirect_uri` and `state`.[7]
## Security checklist
- [ ] Each environment has a separate OAuth application or clearly isolated configuration.
- [ ] Production uses HTTPS.
- [ ] Redirect URIs are exact and reviewed.
- [ ] No client secret is exposed in frontend code.
- [ ] Secrets are stored in a managed secret store.
- [ ] The minimum required scopes are requested.
- [ ] OAuth state is validated.
- [ ] PKCE is used for public clients.
- [ ] Callback errors do not reveal secrets or authorization codes.
- [ ] Tokens are not written to logs.
- [ ] Provider secrets have expiration reminders.
- [ ] Revocation and account-disconnection procedures are documented.
- [ ] A break-glass or recovery process exists for provider outages.
- [ ] Old redirect URIs and unused applications are removed.
## Ready-to-use document
```markdown
# Supabase OAuth Application Record
## Document control
- Application name:
- Environment:
- Document owner:
- Technical owner:
- Security reviewer:
- Version:
- Last reviewed:
- Next review:
## Purpose
Describe why this OAuth application exists and which product feature uses it.
## OAuth model
- [ ] Supabase is the OAuth client for social login.
- [ ] Supabase is the OAuth authorization server.
- Provider:
- OAuth/OIDC version:
- Flow:
- Client type: Public / Confidential
## Application registration
- Provider console:
- Application name:
- Client ID reference:
- Client secret reference:
- Secret expiration:
- Assigned users or groups:
- Consent-screen status:
## Redirect configuration
- Development redirect URI:
- Staging redirect URI:
- Production redirect URI:
- Supabase provider callback URI:
- Supabase Site URL:
- Supabase redirect allow-list entries:
- Wildcards used:
- Wildcard justification:
## Scopes
| Scope | Purpose | Required |
|---|---|---|
| `openid` | Identify the user | Yes |
| `email` | Retrieve the user email | As needed |
| `profile` | Retrieve basic profile data | As needed |
## Data handling
- Tokens stored in:
- Token encryption:
- Token retention:
- Logging restrictions:
- Revocation process:
- User disconnect process:
## Testing
- Login success:
- Consent flow:
- Invalid redirect rejected:
- Invalid state rejected:
- PKCE verified:
- Expired token handled:
- Revoked access handled:
- Provider outage handled:
- New-user provisioning tested:
- Existing-user login tested:
## Operations
- Secret-renewal owner:
- Renewal reminder date:
- Incident contact:
- Rollback procedure:
- Decommission procedure:
## Approval
- Product owner:
- Engineering owner:
- Security approval:
- Date approved:
```
The most important rule is to treat redirect URIs, scopes, client type, and secret storage as security controls—not merely setup details. Supabase’s current documentation specifically emphasizes redirect allow lists, provider callback URLs, confidential-versus-public clients, and secret expiration management.[2][3][6]
การอ้างอิง:
[1] Social login | Supabase Docs https://supabase.com/docs/guides/auth/social-login
[2] Getting Started with OAuth 2.1 Server | Supabase Docs https://supabase.com/docs/guides/auth/oauth-server/getting-started
[3] Redirect URLs | Supabase Docs https://supabase.com/docs/guides/auth/redirect-urls
[4] Sign in with Google | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-google
[5] Sign in with GitHub | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-github
[6] Sign in with Azure (Microsoft) | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-azure
[7] Build a Supabase Integration https://supabase.com/docs/guides/integrations/build-a-supabase-oauth-integration
[8] Configure social login (OAuth) providers - Self-Hosting - Supabase https://supabase.com/docs/guides/self-hosting/self-hosted-oauth
[9] Managing config and secrets | Supabase Docs https://supabase.com/docs/guides/local-development/managing-config
[10] Sign in with Facebook | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-facebook
[11] Step 5. Add Login Code To... https://supabase.com/docs/guides/auth/social-login/auth-workos
[12] Auth Self-hosting Config | Supabase Docs https://supabase.com/docs/guides/self-hosting/auth/config
[13] Sign in with X / Twitter | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-twitter
[14] Sign in with Keycloak | Supabase Docs https://supabase.com/docs/guides/auth/social-login/auth-keycloak
[15] OAuth 2.1 Server | Supabase Docs https://supabase.com/docs/guides/auth/oauth-server
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Supabase Audit Logs Document Guideline
Supabase Audit Logs Document Guideline
## Supabase audit-log guidelines
Supabase has three distinct audit-log areas. Document them separately rather than combining them into one generic “audit log” record:
| Log type | Purpose | Main scope |
|---|---|---|
| Auth Audit Logs | User authentication and account-security events | Supabase project |
| Platform Audit Logs | Organization-member and dashboard/API administrative actions | Supabase organization |
| PostgreSQL/PGAudit logs | Database statements, schema changes, roles, and selected objects | Supabase database |
Auth events are automatically captured. Platform actions are automatically logged, while database auditing requires explicit configuration such as PGAudit or connection logging.[1][2][3]
## Document-control template
```markdown
# Supabase Audit Logging Standard
## Document control
- Document owner:
- Security owner:
- Supabase organization:
- Project:
- Environment:
- Version:
- Effective date:
- Last reviewed:
- Next review:
- Approval ticket:
## Purpose
Define what Supabase activities are logged, where logs are stored,
who can access them, how long they are retained, and how alerts
and investigations are handled.
## Scope
- Authentication events
- Organization and project administration
- Database activity
- Postgres connection activity
- Edge, API, Storage, and Realtime logs where applicable
- External log destinations
## Systems covered
- Project reference:
- Supabase organization:
- Production:
- Staging:
- Development:
```
## Auth Audit Logs
Supabase Auth Audit Logs capture events such as sign-ups, sign-ins, password changes, password resets, email verification, token refresh, sign-out, invitations, account changes, and MFA operations. The documented action names include `login`, `logout`, `user_signedup`, `user_deleted`, `user_updated_password`, `token_revoked`, `token_refreshed`, `challenge_created`, `verification_attempted`, and factor-management events.[1]
Document the storage decision:
```markdown
## Auth audit-log storage
- Auth logs enabled: Yes / No
- External log storage: Enabled / Disabled
- Database storage: Enabled / Disabled
- Database table: auth.audit_log_entries
- Reason for database-storage decision:
- Query owner:
- Retention policy:
- Export or forwarding method:
```
Supabase provides external log storage and optional PostgreSQL storage in `auth.audit_log_entries`. Database storage is searchable through SQL but consumes database storage, so the choice should be documented as a cost, queryability, and compliance decision.[1]
Example event record:
```json
{
"timestamp": "2026-09-13T14:00:00Z",
"user_id": "uuid",
"action": "login",
"ip_address": "redacted-or-controlled",
"user_agent": "redacted-or-controlled",
"metadata": {
"provider": "email"
}
}
```
Do not copy raw audit events containing personal data into tickets, public documents, or chat channels.
## Platform Audit Logs
Platform Audit Logs record organization-member activity performed through the Supabase Dashboard or Platform API. Examples include creating projects, inviting members, changing project settings, and modifying Edge Functions. Each entry can include the timestamp, actor, IP address, email, token type, action, metadata, response status, and target.[2]
Use this section:
```markdown
## Platform audit logging
- Enabled by plan: Team / Enterprise
- Dashboard location:
- Organization:
- Log-drain status:
- Log destination:
- Destination owner:
- Alerting owner:
- Access reviewers:
- Retention period:
- Export limitation acknowledged: Yes / No
## High-risk actions
Alert or review actions involving:
- Organization-owner changes
- Member invitations or removals
- Project creation or deletion
- Project-setting changes
- Secret or credential changes
- Edge Function deployment or modification
- Database configuration changes
- Audit-log-drain changes
```
Supabase states that Platform Audit Logs are available on Team and Enterprise plans. They can be viewed in the organization dashboard or streamed through Audit Log Drains, while dashboard export is currently limited.[2]
## Database and PGAudit
PGAudit extends PostgreSQL logging so you can selectively track reads, writes, functions, role changes, DDL, or other database activity. It supports session, user, global, and object-level approaches.[3]
Document the configuration precisely:
```markdown
## Database audit configuration
- PGAudit enabled: Yes / No
- Connection logging enabled: Yes / No
- Logging scope: Session / User / Object / Global
- Monitored roles:
- Monitored objects:
- Logged categories:
- Log destination:
- Review frequency:
- Performance owner:
```
Common PGAudit categories are:
| Category | Records |
|---|---|
| `read` | `SELECT` and `COPY` data retrieval |
| `write` | `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and related changes |
| `function` | Function, procedure, and `DO` block execution |
| `role` | User and privilege changes |
| `ddl` | `CREATE`, `ALTER`, and `DROP` schema operations |
| `all` | All supported categories |
Start narrowly. For example, monitor DDL and role changes first, then add targeted write or object logging when the risk assessment justifies it. Global `all` logging can create excessive volume and make important events harder to find.[3]
Example role-scoped configuration:
```sql
alter role "migration_runner"
set pgaudit.log to 'ddl, role';
```
Example object-focused design:
```sql
create role "auth_auditor" noinherit;
grant select on auth.users to "auth_auditor";
grant delete on auth.users to "auth_auditor";
alter role "postgres"
set pgaudit.role to 'auth_auditor';
```
Use object-level logging cautiously, especially around `auth.users` and other sensitive tables. PGAudit records statements, not returned rows by default. Enabling row logging can expose sensitive values and affect performance, so it should require documented approval.[3]
## Connection logging
If your compliance program requires database connection evidence, document whether connection logging is enabled. Supabase can record connection lifecycle events such as connection received, authenticated, and authorized. New projects have connection logging off by default according to the current documentation.[4][5]
```markdown
## PostgreSQL connection logging
- Setting: On / Off
- Reason:
- Events collected:
- Monitoring query:
- Review frequency:
- Privacy assessment:
- Performance assessment:
```
Connection logs should not be treated as a replacement for statement-level PGAudit. They answer different questions:
- Connection logs: who connected and whether the connection was authenticated or authorized.
- PGAudit: what database activity was performed.
## Retention and access
Your document should define:
- Retention period by log type.
- Legal or regulatory requirements.
- Whether logs are immutable.
- Who can view raw events.
- Who can change logging configuration.
- How access is reviewed.
- How sensitive fields are protected.
- How incidents are preserved beyond normal retention.
- Whether logs are copied to an external SIEM.
Supabase’s available log retention depends on plan and product area, so record the actual retention visible for your plan instead of assuming one universal period.[2][6]
```markdown
## Retention matrix
| Log type | Supabase retention | External retention | Owner |
|---|---:|---:|---|
| Auth audit logs | Confirm in dashboard | | |
| Platform audit logs | Confirm by plan | | |
| Postgres logs | Confirm in dashboard | | |
| PGAudit events | Confirm in dashboard | | |
| Connection logs | Confirm in dashboard | | |
```
## Monitoring and review
Define both routine review and alerting:
```markdown
## Review procedure
1. Review high-risk authentication events.
2. Review organization-member administrative activity.
3. Review privileged database activity.
4. Investigate repeated failed sign-ins or MFA failures.
5. Check for unexpected changes to roles, schemas, or audit settings.
6. Record findings in the security review register.
7. Escalate confirmed incidents according to the incident-response plan.
```
Useful review signals include:
- Repeated failed login or verification attempts.
- Password recovery activity on privileged accounts.
- MFA factor enrollment or removal.
- Token revocation or unusual refresh activity.
- New organization members.
- Project deletion or setting changes.
- Unexpected Edge Function changes.
- DDL executed outside an approved change window.
- Privileged role modifications.
- Access to sensitive authentication tables.
- Changes that disable or reduce audit coverage.
Supabase’s unified Logs view supports filtering by time range, log type, level, status, method, path, event message, and—in applicable Auth and Postgres events—user.[7]
## Evidence and investigation
For every investigation, preserve:
```markdown
## Investigation record
- Case ID:
- Detection time:
- Event time range:
- Affected project:
- Affected organization:
- Actor or user:
- Event type:
- Source log:
- Event identifiers:
- Query or filter used:
- Raw evidence location:
- Initial assessment:
- Containment action:
- Root cause:
- Corrective action:
- Reviewer:
- Closure date:
```
Do not rely only on screenshots. Preserve structured event data, timestamps in UTC, the query or filter used, and the exact project or organization context.
## Ready-to-use checklist
```markdown
## Audit readiness checklist
- [ ] Auth Audit Logs are enabled and understood.
- [ ] Database storage for auth logs has a documented rationale.
- [ ] Platform Audit Logs are available for the current plan.
- [ ] Audit Log Drains are configured where required.
- [ ] PostgreSQL connection logging has been assessed.
- [ ] PGAudit scope is documented.
- [ ] Sensitive objects are monitored appropriately.
- [ ] Excessive global logging has been avoided.
- [ ] Retention periods are recorded.
- [ ] Log access is least-privilege.
- [ ] Security alerts have named owners.
- [ ] A review schedule exists.
- [ ] Incident evidence-preservation steps are documented.
- [ ] The configuration is reviewed after schema, auth, or organization changes.
```
The key guideline is to document **what is covered, where it is stored, who can access it, how long it is retained, and how it is reviewed**. Treat Auth Audit Logs, Platform Audit Logs, and database/PGAudit records as separate controls with separate owners and retention decisions.
การอ้างอิง:
[1] Log Actions Reference https://supabase.com/docs/guides/auth/audit-logs
[2] Platform Audit Logs | Supabase Docs https://supabase.com/docs/guides/security/platform-audit-logs
[3] PGAudit: Postgres Auditing | Supabase Docs https://supabase.com/docs/guides/database/extensions/pgaudit
[4] Postgres connection logging | Supabase Docs https://supabase.com/docs/guides/platform/postgres-connection-logging
[5] Customer Responsibilities https://supabase.com/docs/guides/security/soc-2-compliance
[6] Check usage for monthly active users (MAU) - Supabase https://supabase.com/docs/guides/troubleshooting/check-usage-for-monthly-active-users-mau-MwZaBs
[7] Logging | Supabase Docs https://supabase.com/docs/guides/observability/logs
[8] Understanding Postgres Logging Levels and How They Impact Your ... https://supabase.com/docs/guides/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm
[9] Query and filter logs - Docs - Supabase https://supabase.com/docs/guides/observability/advanced-log-filtering
[10] How to Interpret and Explore the Postgres Logs https://supabase.com/docs/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj
[11] Logging | Supabase Docs https://supabase.com/docs/guides/monitoring-and-debugging/logs?queryGroups=product&product=postgres&queryGroups=source&source=edge_logs
[12] Superuser Settings https://supabase.com/docs/guides/database/custom-postgres-config
[13] Auth | Supabase Docs https://supabase.com/docs/guides/auth
[14] General configuration | Supabase Docs https://supabase.com/docs/guides/auth/general-configuration
[15] pgmq: Queues | Supabase Docs https://supabase.com/docs/guides/database/extensions/pgmq
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Supabase Audit Log Drains Document Guidelines ## Audit Log Drains guidelines Supabase uses **Audit Log Drains** to stream organization-level Platform Audit Logs to an external destination for security monitoring, SIEM ingestion, alerting, and long-term retention. Platform Audit Logs include dashboard and Platform API actions such as project creation, member invitations, Edge Function changes, and project-setting changes.[1] Do not confuse these with project Log Drains: project drains export service logs such as Postgres, Auth, Storage, Edge Functions, Realtime, and API Gateway logs. Audit Log Drains are configured at the organization level.[2] ## Document-control template ```markdown # Supabase Audit Log Drain Configuration ## Document control - Document owner: - Security owner: - Supabase organization: - Environment: - Version: - Effective date: - Last reviewed: - Next review: - Approval ticket: ## Purpose Stream Supabase Platform Audit Logs to an approved external destination for centralized monitoring, alerting, investigation, and retention. ## Scope - Organization: - Projects covered: - Organization-member actions: - Dashboard actions: - Platform API actions: - Included action categories: - Excluded events, if any: ## Destination - Destination type: - Destination name: - Endpoint or bucket reference: - Region: - Account or tenant: - Authentication method: - Encryption: - Data owner: - Retention: ``` ## Eligibility and access Confirm the organization’s plan before implementation. Supabase documents Platform Audit Logs and Audit Log Drains as available on Team and Enterprise plans.[1] Record who can: - View audit logs. - Configure or delete drains. - Access the external destination. - Rotate destination credentials. - Approve changes. - Investigate events. Use least privilege. The person who can configure a drain should not automatically have unrestricted access to all exported security logs. ## Supported destinations Supabase’s Log Drains documentation lists these destination types: - Custom HTTP endpoint. - OpenTelemetry over HTTP using Protocol Buffers. - Datadog. - Grafana Loki. - Amazon S3. - Sentry. - Axiom. - Last9. - Syslog over TCP or TLS.[2] Choose the destination based on the operational requirement: | Requirement | Suitable destination | |---|---| | SIEM or custom security pipeline | OTLP or custom HTTP endpoint | | Long-term archive | Amazon S3 | | Existing observability platform | Datadog, Sentry, Axiom, Loki, or Last9 | | Legacy security infrastructure | Syslog with TLS | | Provider-neutral telemetry | OpenTelemetry | ## Destination record Use a destination-specific record instead of storing secrets in prose. ### Custom HTTP ```yaml destination: type: custom_http url_reference: "secret://security/supabase-audit-drain-url" http_version: "HTTP/2" gzip: true authentication: "Bearer token stored in secret manager" request_format: "JSON array" batching: "Up to 250 events or 1 second" signature: "Not available; use TLS and authenticated headers" ``` Supabase sends custom HTTP logs as batched JSON arrays. HTTP/1 and HTTP/2 are supported, and custom headers can be used for authentication or routing. Current documentation states that custom requests are unsigned, so protect the endpoint with HTTPS, authentication headers, network controls, and replay protection on the receiving side.[2] ### OpenTelemetry ```yaml destination: type: otlp_http endpoint_reference: "secret://observability/otlp-endpoint" path: "/v1/logs" protocol: "http/protobuf" gzip: true authentication: "Headers stored in secret manager" content_type: "application/x-protobuf" ``` The receiving endpoint must accept OTLP logs at `/v1/logs` using `application/x-protobuf`. Gzip is recommended to reduce bandwidth.[2] ### Amazon S3 ```yaml destination: type: s3 bucket: "security-audit-archive" region: "ap-southeast-1" prefix: "supabase/platform-audit/" credentials_reference: "secret://aws/supabase-audit-drain" batch_timeout_ms: 3000 encryption: "SSE-KMS" lifecycle_policy: "Defined in AWS" object_lock: "Enabled if required" ``` The bucket must already exist, and the AWS identity must have write permission to it. Prefer a dedicated IAM identity with write-only access to a dedicated prefix; do not use an administrator credential.[2] ### Syslog ```yaml destination: type: syslog host_reference: "secret://security/syslog-host" port: 6514 tls: true mutual_tls: true ca_certificate_reference: "secret://security/syslog-ca" client_certificate_reference: "secret://security/syslog-client-cert" client_key_reference: "secret://security/syslog-client-key" ``` Use TLS for production. Supabase supports CA verification and mutual TLS when the receiver requires client authentication.[2] ## Security requirements - Use HTTPS, OTLP TLS, S3 encryption, or Syslog TLS. - Store API keys, tokens, passwords, access keys, and private keys in a secrets manager. - Never place credentials in the document, source code, tickets, or screenshots. - Use a dedicated destination credential. - Restrict the credential to ingestion only. - Rotate credentials according to the organization’s security policy. - Restrict the receiving endpoint by network policy where possible. - Alert if the drain is deleted, modified, disabled, or stops receiving events. - Treat audit logs as sensitive because they can contain actor emails, IP addresses, token types, routes, response status, and target metadata.[1] ## Event coverage Document the expected audit-event fields: ```markdown ## Expected event fields - Event timestamp - Actor email - Actor IP address - Token type - Action name - Action metadata - Request route - Response status - Action target - Organization or project identifier - Correlation or event identifier, if available ``` The Platform Audit Log view exposes the timestamp, actor details, action name and metadata, and target information.[1] Do not assume that an Audit Log Drain replaces every other logging control. It is intended for Platform Audit Logs; Auth events and project service logs have separate audit and Log Drain mechanisms.[1][2] ## Validation checklist Before production use: ```markdown ## Deployment validation - [ ] Organization plan supports Audit Log Drains. - [ ] Destination exists and is owned by the organization. - [ ] Credentials are stored outside the document. - [ ] TLS or equivalent transport protection is enabled. - [ ] Least-privilege destination permissions are verified. - [ ] A test administrative action generated an event. - [ ] The event arrived at the destination. - [ ] Actor, action, target, timestamp, and status were preserved. - [ ] Destination parsing and field mapping were verified. - [ ] Duplicate handling was tested. - [ ] Delayed delivery was tested. - [ ] Destination outage behavior was documented. - [ ] Alerts for drain failure were configured. - [ ] Retention and deletion policies were approved. - [ ] Security and platform owners approved the change. ``` For custom endpoints, test JSON-array parsing and authentication because the current service does not sign requests. For S3, verify object creation, IAM permissions, encryption, lifecycle, and auditability. For OTLP, verify the `/v1/logs` path, protobuf content type, headers, and gzip handling.[2] ## Operations runbook ```markdown ## Operational procedure ### Daily monitoring - Confirm events are arriving. - Check ingestion errors. - Check destination latency. - Review failed authentication or authorization. - Confirm no unexpected configuration changes. ### Credential rotation 1. Create the replacement credential. 2. Store it in the approved secrets manager. 3. Update the drain during an approved change window. 4. Generate a test audit event. 5. Confirm receipt. 6. Revoke the old credential. 7. Record the change. ### Destination outage 1. Confirm whether Supabase configuration or the destination is failing. 2. Open an incident if security coverage is affected. 3. Preserve locally available audit evidence. 4. Restore delivery or switch to the approved secondary destination. 5. Identify any event gap. 6. Record the incident and corrective action. ### Decommissioning 1. Obtain owner and security approval. 2. Export or preserve required evidence. 3. Disable the drain. 4. Revoke destination credentials. 5. Remove unused IAM permissions. 6. Verify billing and configuration status. 7. Update this document and the change register. ``` ## Cost and retention notes Log drains are separately billed. Supabase documents charges for configured drain hours, exported log events, and egress; Log Drains are not covered by the Spend Cap. Usage can be reviewed from the organization’s usage page.[3] Record these values in the document: ```markdown ## Cost controls - Number of active drains: - Expected events per month: - Expected egress: - Estimated monthly drain-hour cost: - Estimated event cost: - Budget owner: - Usage-alert threshold: - Review frequency: ``` Supabase currently documents a per-drain hourly charge and event-based billing, but pricing can change. Confirm the current organization usage and pricing view before approving a production configuration.[3] ## Recommended final record ```markdown # Supabase Audit Log Drain — Production ## Summary - Organization: - Drain name: - Purpose: - Destination: - Owner: - Status: - Created: - Last tested: - Next review: ## Coverage - Platform Audit Logs: Yes - Organization-member activity: Yes - Dashboard activity: Yes - Platform API activity: Yes - Auth Audit Logs: Separate control - Project service logs: Separate control ## Security - Transport encryption: - Destination authentication: - Credential reference: - IAM or access policy: - Secret-rotation schedule: - Sensitive-data handling: ## Reliability - Batch behavior: - Expected delivery: - Failure alert: - Retry or recovery process: - Secondary destination: ## Compliance - Retention: - Immutability: - Legal hold: - Access review: - Evidence export process: ## Approval - Platform owner: - Security owner: - Compliance reviewer: - Approval date: ``` The central principle is to treat an Audit Log Drain as a **security control with a defined owner, protected destination, tested delivery path, retention policy, and failure response**, not merely as a forwarding URL. การอ้างอิง: [1] Platform Audit Logs | Supabase Docs https://supabase.com/docs/guides/security/platform-audit-logs [2] Log Drains | Supabase Docs https://supabase.com/docs/guides/observability/log-drains [3] Manage Log Drain usage | Supabase Docs https://supabase.com/docs/guides/platform/manage-your-usage/log-drains [4] Manage Logs usage | Supabase Docs https://supabase.com/docs/guides/platform/manage-your-usage/logs [5] sitemap.xml https://supabase.com/docs/sitemap.xml [6] Create log drain | Management API Reference | Supabase Docs https://supabase.com/docs/reference/api/v2-create-log-drain [7] Supabase Docs https://supabase.com/docs [8] Manage Egress usage | Supabase Docs https://supabase.com/docs/guides/platform/manage-your-usage/egress [9] Access Control | Supabase Docs https://supabase.com/docs/guides/platform/access-control [10] Log Drains | Supabase Features https://supabase.com/features/log-drains [11] Introducing Log Drains https://supabase.com/blog/log-drains [12] Releases · supabase/supabase https://github.com/supabase/supabase/releases Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Supabase Feature Request Preview
## Supabase Feature Preview guidelines
Supabase uses **Feature Previews** to expose early features before general availability, gather feedback, and iterate on the product. A preview should be treated as experimental: functionality may change, and it may not have the same stability or support guarantees as a generally available feature.[1][2]
## Feature-state record
Supabase documentation distinguishes feature stages such as:
- Private Alpha.
- Public Alpha.
- Beta.
- Generally Available.
The stage determines how cautiously the feature should be adopted. Supabase’s feature documentation indicates that generally available features are the stable production tier, while alpha and beta features are still evolving.[3]
Use this record:
```yaml
supabase_feature:
name: "Feature name"
product_area: "Database / Auth / Studio / Platform / Storage"
stage: "Private Alpha | Public Alpha | Beta | GA"
preview_enabled: false
project:
name: "Project name"
ref: "project-ref"
environment: "Development"
owner: "Team or person"
purpose: "Why this preview is being evaluated"
enabled_date: "YYYY-MM-DD"
review_date: "YYYY-MM-DD"
rollback_method: "How to disable or revert it"
feedback_url: "Official discussion or issue URL"
production_approved: false
```
## Safe adoption policy
### Development first
Enable a Feature Preview in a development or test project before using it in staging. Do not enable it directly in production unless the feature has been evaluated, the rollback path is known, and the owner has approved the risk.
### Staging validation
Test:
- Existing database schema and migrations.
- Authentication and authorization.
- RLS behavior.
- API responses.
- Performance and query plans.
- Backups and restoration.
- Logs and monitoring.
- CI/CD and branch workflows.
- Integrations and SDK compatibility.
### Production approval
Require explicit approval for:
- Features marked alpha or beta.
- Features that alter database behavior.
- Features that affect authentication or authorization.
- Features that change billing or usage.
- Features that modify networking, backups, branching, or deployment.
- Features without a tested rollback process.
Supabase currently labels dashboard Branching as public alpha and notes that its functionality may change; the documented process requires opting in through Feature Previews.[2]
## Enablement record
Document exactly how the preview was enabled:
```markdown
## Enablement
1. Sign in to the Supabase Dashboard.
2. Open the user menu or profile menu.
3. Select Feature Previews.
4. Select the required feature.
5. Review the warning and description.
6. Click Enable feature.
7. Confirm the feature appears in the project.
8. Run the validation checklist.
```
The location and wording of the menu may change. Record the current dashboard path and capture the official documentation or discussion link rather than relying on screenshots alone. Supabase has historically exposed Feature Previews through the user-avatar menu in Studio.[1][4]
## Risk assessment
```markdown
## Feature Preview risk assessment
### Business impact
- Feature purpose:
- Business process affected:
- User groups affected:
- Revenue or SLA impact:
- Compliance impact:
### Technical impact
- Database changes:
- API changes:
- Auth changes:
- RLS changes:
- Network changes:
- Backup or recovery impact:
- Billing or usage impact:
- External integrations affected:
### Risks
- Known limitations:
- Expected breaking changes:
- Data-loss risk:
- Availability risk:
- Security risk:
- Vendor-support limitation:
### Controls
- Development test completed:
- Staging test completed:
- Monitoring added:
- Rollback tested:
- Owner assigned:
- Approval obtained:
```
## Rollback plan
Every preview should have a written rollback plan before enablement:
```markdown
## Rollback
### Trigger conditions
- Data integrity issue.
- Unexpected permission behavior.
- Error-rate increase.
- Performance regression.
- Incompatible SDK or integration.
- Preview removed or materially changed.
- Security or compliance concern.
### Procedure
1. Disable the Feature Preview if a disable control exists.
2. Revert application configuration or feature flags.
3. Restore the prior migration or deployment if required.
4. Validate authentication, RLS, APIs, and critical workflows.
5. Check logs and audit events.
6. Notify affected owners.
7. Record the incident and final decision.
### Limitations
- Can the feature be disabled without data migration?
- Are created resources backward-compatible?
- Is a database restore required?
- Is vendor support available?
```
Do not assume that disabling a preview reverses schema changes or data migrations. If the preview changes persistent data, treat rollback as a migration or recovery operation.
## Feedback and change tracking
Supabase Feature Previews commonly include a feedback or GitHub Discussion link. Record:
- Feedback URL.
- Date tested.
- Version or dashboard state.
- Reproduction steps.
- Expected behavior.
- Actual behavior.
- Logs or screenshots.
- Impact.
- Workaround.
- Follow-up owner.
Supabase describes Feature Previews as a mechanism for gathering UX/UI feedback and links preview features to discussions for user feedback.[1]
## Ready-to-use document
```markdown
# Supabase Feature Preview Evaluation
## Overview
- Feature:
- Product area:
- Supabase feature stage:
- Official documentation:
- Feedback or issue link:
- Project:
- Project reference:
- Environment:
- Evaluation owner:
- Business owner:
- Security reviewer:
- Start date:
- Review date:
## Purpose
Describe the problem this preview is expected to solve.
## Scope
- Included users:
- Included projects:
- Included environments:
- Excluded production workflows:
- Expected evaluation period:
## Prerequisites
- [ ] Development project available.
- [ ] Staging project available.
- [ ] Backup or recovery plan verified.
- [ ] Logs and monitoring available.
- [ ] Required permissions confirmed.
- [ ] Documentation reviewed.
- [ ] Rollback plan approved.
## Test plan
- [ ] Enablement tested.
- [ ] Existing workflows tested.
- [ ] New feature behavior tested.
- [ ] RLS and permissions tested.
- [ ] API and SDK compatibility tested.
- [ ] Performance tested.
- [ ] Failure behavior tested.
- [ ] Monitoring tested.
- [ ] Rollback tested.
## Results
- Expected behavior:
- Actual behavior:
- Performance:
- Errors:
- Security findings:
- Data-integrity findings:
- User feedback:
- Open issues:
## Decision
- [ ] Do not adopt.
- [ ] Continue evaluation.
- [ ] Use in development only.
- [ ] Use in staging.
- [ ] Approve for production.
- [ ] Remove and roll back.
## Approval
- Engineering:
- Security:
- Operations:
- Product:
- Date:
```
## Preview versus production
| Question | Preview | Production |
|---|---|---|
| Stability | May change | Expected to be stable |
| Feature behavior | May be incomplete | Supported operating behavior |
| API compatibility | May change | Versioned or documented |
| SLA assumption | Do not assume full coverage | Check applicable service terms |
| Rollback | Must be explicitly planned | Required for material changes |
| Data use | Prefer non-production data | Requires formal approval |
| Monitoring | Required before broader use | Continuous monitoring |
## Key rule
Treat a Supabase Feature Preview as a **time-limited experiment with an owner, test scope, feedback path, monitoring, and rollback plan**. Do not promote it to production merely because it works in a simple test; first confirm its security, data, performance, operational, and contractual implications.
การอ้างอิง:
[1] Feature Previews https://supabase.com/blog/studio-introducing-assistant
[2] Branching via the dashboard | Supabase Docs https://supabase.com/docs/guides/deployment/branching/dashboard
[3] supabase/apps/docs/content/guides/getting-started/features.mdx at master · supabase/supabase https://github.com/supabase/supabase/blob/master/apps/docs/content/guides/getting-started/features.mdx
[4] Keeping Tabs on What's New in Supabase Studio https://supabase.com/blog/tabs-dashboard-updates
[5] Changelog https://supabase.com/changelog
[6] The Postgres Development Platform - Supabase https://supabase.com/contribute
[7] Changelog https://supabase.com/changelog?next=Y3Vyc29yOnYyOpK0MjAyNC0wOC0zMFQxNjowMzo0NVrOAGyKbA==&restPage=2
[8] Vercel Integration: Environment variables explained - Supabase https://supabase.com/docs/guides/troubleshooting/vercel-integration-environment-variables-not-syncing-for-persistent-git-branches-b9191e
[9] Supabase Platform | Supabase Docs https://supabase.com/docs/guides/platform
[10] Changelog - Supabase https://supabase.com/changelog?next=Y3Vyc29yOnYyOpK0MjAyNC0wNy0xOFQwOToxODo0NlrOAGoHsA==&restPage=2
[11] Auth Settings Added Option... https://supabase.com/changelog/19827-dashboard-weekly-updates-11th-dec-18th-dec
[12] Supabase Branching https://supabase.com/blog/supabase-branching
[13] github.com-supabase-supabase_-_2021-11-21_09-43-08 https://archive.org/details/github.com-supabase-supabase_-_2021-11-21_09-43-08
[14] Real-time Preview - Newly.app https://docs.newly.app/features/preview
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
…tes (#245) - Add knowledge/README.md — index table, tag index, and conventions - Add knowledge/manifest.yml — machine-readable note index (sha256 per note) - Rename the six notes to kebab-case .md and add YAML front matter - Add knowledge/sync_knowledge_index.py — stdlib-only indexer (6 notes/164 records) Note bodies are unchanged; sha256 of each body matches the original files. Co-authored-by: fig-ai-agent <fig-ai-agent@users.noreply.github.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Four PRs merged on 2026-09-13 were absent from the changelog. Placed in the existing [2026-09-13] section, in the file's own order (PR number descending within each subsection). - **#245** (Added) — knowledge notes gained an index, a manifest and front matter, plus sync_knowledge_index.py to derive the index from the notes - **#240** (Added) — ci-workflow-authoring skill and lint.py; it flagged 9 of the 10 workflows then on main, all for the same unresolvable-ref reason - **#236** (Changed) — README rewritten to describe the tree as it stands - **#243** (Fixed) — auto-compress-manage.yml, failing at `Set up job` on all 781 runs: five action refs pointed at SHAs that do not exist upstream #239 is deliberately not recorded: it is a changelog PR, and this repository does not log its own changelog PRs (zero such entries exist). Surgical anchored inserts, not a regeneration — the file is 370 lines of hand-written prose and rewriting it would lose formatting and drop entries. 43 insertions, 0 deletions; date sections unchanged (6), per-subsection PR numbers verified descending, no duplicate PR refs introduced. Co-authored-by: Fig AI Agent <fig-ai-agent@users.noreply.github.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
…ns tooling (#246) Records the lesson from the SHA-pin audit and closes the gap that let it happen: every automated check in this repo verified the SHAPE of a pin, not its existence, so ten fabricated SHAs passed review. ## knowledge/github-actions-sha-pinning-guidelines.md Why tags are mutable, how to prove a commit exists in the action's own repo, and the workflow-file traps that fail before any job runs (a bare `on:` parsing as boolean `True`, an under-indented heredoc inside `run: |`, pasted prose around a workflow body). 944 words, 12 sources, front matter per knowledge/ conventions. ## knowledge/build_knowledge_readme.py The index was hand-maintained, so counts drifted whenever a note was added — the tag table carries a per-tag note count and member list, and one new note changes several rows at once. Generating it from the files keeps them in step; `--check` verifies it in CI. ## skills/ci-workflow-authoring/verify-pins.py python skills/ci-workflow-authoring/verify-pins.py .github/workflows/*.yml `lint.py` confirms a ref is 40 lowercase hex. That is necessary and not sufficient: a fabricated string satisfies it and still fails at `Set up job` with "Unable to find version". This asks GitHub whether each commit exists in THAT action's repository, and exits non-zero if any does not. Run against this repo's workflows today it reports 6 non-existent pins on `main` (actions/checkout@11bd7190… and @f548e57c…, actions/setup-python@5fda3b9c…, and the three github/codeql-action/*@977e6ce4…). Those are the cause of the red checks every PR currently shows. Two wrong-answer modes are handled explicitly, because a false "fake" verdict sends someone to replace a pin that was already correct: - subdirectory actions (`owner/repo/subdir@sha`) are resolved against `owner/repo` — querying the three-segment path 404s even for a real commit - a network failure is reported as unverifiable, never as fake, and does not fail the run It uses the HTML commit endpoint rather than the REST API: the anonymous API allows 60 requests/hour, which a repo of any size exhausts mid-run. ## Verified - 26 tests pass (9 new), covering owning-repo resolution, which refs count as pins, comment handling, and both wrong-answer modes above - the guideline note passes sync_knowledge_index.py (7 notes, 176 records) - build_knowledge_readme.py is idempotent (`--check` reports up to date) Co-authored-by: Fig AI Agent <fig-ai-agent@users.noreply.github.com>
Agents: Task Master, Result Orchestrator, Milestone Tracker, Blocker Resolver, Handoff Coordinator, Summary Reporter -- runnable modules under knowledge/agents/ with tests (40 passing). Protect: .gitattributes merge strategy, CODEOWNERS, merge_rules.json. Policy: additive only -- no file replacement, history preserved. Note: protect-merge.yml is delivered separately -- the GitHub App for this repo lacks the workflows permission, and a push touching .github/workflows/ is rejected in full at the tree level.
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
…during PR triage (#238) The automated, CI-side form of skills/organize-misplaced-files: same three-condition gate, wrapped in an import probe that makes it safe to run unattended. ## The gate A root file moves only when all three hold: 1. it is not canonical (allow-list in config.py — README, requirements.txt, main.py, Dockerfile, …) 2. no tracked .py imports it as a module — AST-parsed, never grep 3. its name appears in no other tracked text file (.md/.yml/.json/.toml/ Makefile/Dockerfile*) Condition 2 needs parsing, not pattern matching. Python 3 resolves `import auth` inside app/api/auth.py to TOP-LEVEL `auth` — root auth.py — even when a sibling app/api/auth.py exists. Only the import graph tells those apart. Unparseable files are reported (unparseable_py), never silently treated as unused: 23 exist in this repo, 6 of them at root. Condition 3 is what parks a root deployment.yaml named by k8s/kustomization.yaml — it looks like clutter and is not. ## Why the probe exists classify -> probe(before) -> git mv -> probe(after) -> regression? -> roll back The probe imports each entrypoint in a CHILD process, so a poisoned import cannot kill the triage run. Three regression rules, each earned: - FAIL-that-was-already-FAIL is not a regression. This repo's app.main and main currently fail at import (the pydantic `Extra` error fixed separately in #237); blocking on that would make the skill unusable exactly where it is needed. The probe reports it honestly and the move proceeds. - UNKNOWN is never a regression — "the probe could not run" is an environment fact, not evidence about the move. - FAIL -> OK is a fix, not a regression. On a detected regression every git mv is reversed and the run exits 2. ## Verified - 37 tests pass (`python -m pytest skills/pr-triage-automove/tests -q`), covering the AST rule, all three gate conditions, the rollback path, the max_move guard, and probe cleanup. - `--apply` run against a copy of this repo: 112 files moved, git records 112 renames and **0 deletions**, and import health is identical before/after (app.main FAIL, main FAIL, app.core.main FAIL — all pre-existing). - Dry-run is the default; `--apply` is the only way anything moves. - The workflow YAML parses and every `uses:` is pinned to a full 40-char SHA, resolved against the GitHub API. It lives in examples/ rather than .github/workflows/ because pushing there needs the `workflows` permission. ## Safety properties Nothing is ever deleted — `git mv` only, so history and rename detection hold. The archive layout routes by suffix (scripts/manifests/exports/html/assets/ notes). The probe is repo-configurable via .pr-triage-automove.json, and a malformed config falls back to defaults rather than disabling the gate. Co-authored-by: Fig AI Agent <fig-ai-agent@users.noreply.github.com>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
…s first run (#281) README #269/#274/#276 cited a fact-check script that lived only in the author's workspace, so the evidence in those PRs could not be re-run. This adds it as a real deliverable. docs-verify checks the repository's own documentation against the tree: counts the README declares, backticked paths, workflow parse state, the SHA-pin split, the LICENSE holder, and the structural health of PROBLEMS.md (unique ids, unique and descending date sections). Read-only, no network, standard library only; PyYAML is optional and reports skip, not fail. Counts are compared against what the README itself declares rather than a frozen number, so the checks survive the tree legitimately changing and fail only on real drift. Both numeral and spelled-out forms are parsed ('Five of the eleven workflow files'). On its first run against main it caught two live drifts from concurrent merges: deliverables 25 -> 26 and docs 32 -> 34. Both are corrected here. The remaining failure is the known P-001 defect (5 of 11 workflows do not parse) — the tool reporting a real problem, not a false positive. 17 tests over synthetic fixture trees, so the suite cannot start failing because an unrelated merge moved a count. Co-authored-by: Fig Agent <nattapong@zyntro.ai>
Co-authored-by: Fig Agent <nattapong@zyntro.ai>
…iene) (#283) The work merged today -- README rewrite, LICENSE holder, package.json license, PROBLEMS.md repair, docs-verify -- had no task record, so it left no trace in the repo's own process. This adds it under inprogress/. Steps and acceptance criteria are all met and every PR is merged; the task is not moved to done/ because the out-of-scope items (P-001 workflow repair, .env rotation, branch pruning) need the owner's call on whether they fold in or split out. validation table records actual commands and results, including the one docs-verify check that fails on main -- P-001, the five unparseable workflows -- so the failure is recorded rather than glossed. Co-authored-by: Fig Agent <nattapong@zyntro.ai>
Co-authored-by: Fig Agent <nattapong@zyntro.ai>
Signed-off-by: Zyntro-Agents <zyntro.ai.studio@gmail.com>
Four stdlib-only tools for the points where automated GitHub work goes wrong: perm-checker decides a push will be accepted before it is attempted, ci-workflow audits workflows for unpinned actions and parse failures, approval-doc turns a permission block into a grantable request, pr-helper builds a PR body whose Definition-of-Done gaps are visible. 25 tests.
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Comment on lines
+66
to
+70
| "`workflows` is an **App-installation** permission. It is separate from " | ||
| "`contents: write`, and a repository-level write grant cannot supply it — " | ||
| "no token carries it unless the App installation was granted it " | ||
| "explicitly. Without it, GitHub rejects a push that creates or updates " | ||
| "**any** file under `.github/workflows/`:", |
Comment on lines
+98
to
+99
| "- Every file is reviewable in the pull request — nothing is pushed to the " | ||
| "default branch directly; the grant only allows preparing a branch and PR.", |
Comment on lines
+101
to
+102
| "- If you would rather not grant it, no grant is needed: the same change can be " | ||
| "delivered as a `.patch` file applied by a maintainer locally.", |
|
|
||
| from __future__ import annotations | ||
|
|
||
| import re |
This was
linked to
issues
Sep 15, 2026
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
zyntromedia
added
dependencies
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
deliverables/dev-helpers/— four small stdlib-only tools for the frictionpoints in automated GitHub work. Each answers one question the agent currently
learns the hard way, and each is tested.
perm_checkerci_workflowapproval_docpr_helperBehaviour worth noting
normalize_pathavoids thestr.lstrip("./")trap —lstriptakes a set ofcharacters, not a prefix, so it eats the leading dot of
.github/and makes ablocked push report as a pass. A test asserts the wrong answer to prevent
reintroduction.
check_pushsurfaces this explicitly.workflows: writeis an App-installation permission and cannot be supplied by arepo-level grant;
approval_docsays so and states the no-grant alternative.parse_statealways reports which engine decided (pyyamlvsstructural), soa lenient fallback is never mistaken for a thorough check.
checklistdefaults an unmentioned DoD item to unchecked, not asserted.Changes
deliverables/dev-helpers/dev_helpers/— 4 modules +__init__.pydeliverables/dev-helpers/dev_helpers/tests/test_dev_helpers.py— 25 testsdeliverables/dev-helpers/{README.md,SKILL.md,manifest.json,GUIDE.md,GUIDE.en.md}CHANGELOG.md— entry for 2026-09-15deliverables/README.md,docs/README.md— index rowsVerification
The patch was also applied to a fresh clone of
mainand re-tested there:git apply --checkclean, 25/25 passing.Definition of Done
Notes
No
.github/workflows/file is touched by this change set, so noworkflowsscope is required to push it.