Skip to content

Commit 6b1b980

Browse files
ltagliaferriamouat
ltagliaferri
and
amouat
authored
add octo sts tutorials (#2861)
This adds tutorials and documentation for octo sts based on the octo sts org Preview of the section: https://deploy-preview-2861--ornate-narwhal-088216.netlify.app/open-source/octo-sts/ --------- Signed-off-by: ltagliaferri <[email protected]> Signed-off-by: Adrian Mouat <[email protected]> Co-authored-by: Adrian Mouat <[email protected]>
1 parent a9107b9 commit 6b1b980

File tree

5 files changed

+464
-0
lines changed

5 files changed

+464
-0
lines changed

‎content/open-source/octo-sts/_index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: "Octo STS"
3+
lead: "ecurity token service for GitHub that enables OIDC-based federation"
4+
type: "article"
5+
date: 2025-12-20T08:49:15+00:00
6+
lastmod: 2025-12-30T08:49:15+00:00
7+
draft: false
8+
images: []
9+
weight: 20
10+
---
11+
12+
Octo STS is a Security Token Service for GitHub that eliminates the need for long-lived Personal Access Tokens by enabling OIDC-based federation for GitHub API access.

‎content/open-source/octo-sts/faq.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
title: "Octo STS FAQ"
3+
linktitle: "FAQ"
4+
type: "article"
5+
lead: "Frequently asked questions about Octo STS, including troubleshooting, security considerations, and common use cases"
6+
description: "Learn about Octo STS for GitHub token federation, including setup issues, security best practices, and integration patterns"
7+
date: 2025-12-22T15:04:05+01:00
8+
lastmod: 2025-12-22T15:04:05+01:00
9+
tags: ["octo-sts", "FAQ"]
10+
draft: false
11+
images: []
12+
menu:
13+
docs:
14+
parent: "octo-sts"
15+
weight: 60
16+
toc: true
17+
---
18+
19+
This page answers frequently asked questions about Octo STS, including setup, security, troubleshooting, and common use cases.
20+
21+
## General Questions
22+
23+
### What is Octo STS?
24+
25+
Octo STS is a GitHub App developed by Chainguard that acts as a Security Token Service for GitHub. It allows workloads with OIDC tokens from various identity providers (GitHub Actions, cloud providers, Kubernetes, etc.) to exchange those tokens for short-lived GitHub access tokens. The primary goal is to eliminate the need for long-lived Personal Access Tokens (PATs).
26+
27+
### Why should I use Octo STS instead of Personal Access Tokens?
28+
29+
Personal Access Tokens pose security risks as they allow provide persistent access to resources and are not tied to a given workload. Attackers regularly abuse leaked PATs to gain access to systems and resources.
30+
31+
By comparison, Octo STS tokens are short-lived (1 hour) and typically tightly scoped to the workload in question. This vastly reduces the scope for abuse.
32+
33+
### How does Octo STS compare to GitHub's built-in GITHUB\_TOKEN?
34+
35+
GitHub Actions provides a `GITHUB_TOKEN` automatically, but it has limitations:
36+
- Cannot update workflow files
37+
- Cannot trigger other workflows
38+
- Limited to a fixed set of permissions
39+
40+
Octo STS tokens can:
41+
- Update workflow files (useful for Renovate)
42+
- Have any permissions defined in your trust policy
43+
- Work consistently across all automation platforms, not just GitHub Actions
44+
45+
### Is Octo STS free to use?
46+
47+
Yes, Octo STS is open source and the hosted service at octo-sts.dev is free to use. You can also self-host Octo STS if you prefer.
48+
49+
### Can I self-host Octo STS?
50+
51+
Yes, Octo STS is open source and can be self-hosted. See the [Octo STS repository](https://github.com/octo-sts/app) for deployment instructions.
52+
53+
## Setup and Configuration
54+
55+
### How do I install Octo STS?
56+
57+
Install the GitHub App:
58+
1. Visit [https://github.com/apps/octo-sts](https://github.com/apps/octo-sts)
59+
2. Click **Install**
60+
3. Select the organization or user account
61+
4. Choose which repositories to grant access
62+
5. Approve the permissions
63+
64+
Then create trust policies in your repositories at `.github/chainguard/{name}.sts.yaml`.
65+
66+
### Why does Octo STS request so many permissions?
67+
68+
Octo STS requests a superset of permissions to support a large range of use cases. However, it only creates tokens with the specific permissions defined in your trust policies. The app needs `contents: read` to read trust policy files, but all other permissions are only granted based on your policies.
69+
70+
### What happens if I don't create any trust policies?
71+
72+
If you install Octo STS but don't create trust policies, the app cannot issue any tokens. Trust policies are required to specify which identities are trusted and what permissions to grant them.
73+
74+
### Can I use Octo STS with private repositories?
75+
76+
Yes, Octo STS works with both public and private repositories. The app needs access to read the repository's trust policy files.
77+
78+
### How do I update trust policy permissions?
79+
80+
Edit the trust policy file in your repository, commit, and push the changes. The new permissions take effect immediately for subsequent token exchanges. Existing tokens retain their original permissions until they expire.
81+
82+
### Can I have multiple trust policies in one repository?
83+
84+
Yes, you can create multiple policy files with different names:
85+
- `.github/chainguard/renovate.sts.yaml`
86+
- `.github/chainguard/deploy.sts.yaml`
87+
- `.github/chainguard/ci.sts.yaml`
88+
89+
Each policy can have different identity requirements and permissions. Specify which policy to use via the `identity` parameter when exchanging tokens.
90+
91+
## Security
92+
93+
### Are Octo STS tokens safe?
94+
95+
Octo STS tokens are as safe as the trust policies you create. They're short-lived (1 hour), reducing the window of opportunity if compromised.
96+
97+
### Can Octo STS tokens bypass branch protection?
98+
99+
No. Branch protection rules are enforced by GitHub regardless of the token type. Even with `contents: write` permission, Octo STS tokens must follow branch protection requirements like pull request reviews and status checks.
100+
101+
### Should I use pattern matching or exact subjects?
102+
103+
Prefer exact subject matching when possible:
104+
105+
```yaml
106+
# Better: Exact match
107+
subject: repo:org/repo:ref:refs/heads/main
108+
```
109+
110+
Use pattern matching only when you need flexibility:
111+
112+
```yaml
113+
# When necessary: Pattern match
114+
subject_pattern: "repo:org/repo:ref:refs/heads/.*"
115+
```
116+
117+
Exact matching is more secure because it's harder to accidentally grant broader access than intended.
118+
119+
## Integration
120+
121+
### Can I use Octo STS from a CI/CD system other than GitHub Actions?
122+
123+
Yes, Octo STS works with any system that can:
124+
1. Obtain OIDC tokens (Jenkins, GitLab CI, CircleCI, etc.)
125+
2. Make HTTP requests to exchange tokens
126+
3. Use the resulting GitHub token
127+
128+
The key is having an OIDC identity provider that Octo STS can validate.
129+
130+
### How do I use Octo STS with Terraform?
131+
132+
Use Terraform's `external` data source to exchange tokens:
133+
134+
```hcl
135+
data "external" "github_token" {
136+
program = ["bash", "-c", <<-EOT
137+
OIDC_TOKEN=$(get_oidc_token)
138+
RESPONSE=$(curl -s -H "Authorization: Bearer $OIDC_TOKEN" \
139+
"https://octo-sts.dev/sts/exchange?scope=org/repo&identity=terraform")
140+
echo $RESPONSE | jq '{token: .access_token}'
141+
EOT
142+
]
143+
}
144+
145+
provider "github" {
146+
token = data.external.github_token.result.token
147+
}
148+
```
149+
150+
### Can I use Octo STS to access multiple repositories?
151+
152+
Yes, use organization trust policies with a `repositories` field:
153+
154+
```yaml
155+
issuer: https://token.actions.githubusercontent.com
156+
subject: repo:org/automation-repo:ref:refs/heads/main
157+
158+
permissions:
159+
contents: read
160+
161+
repositories:
162+
- org/repo-one
163+
- org/repo-two
164+
- org/repo-three
165+
```
166+
167+
The resulting token can access all listed repositories.
168+
169+
## Troubleshooting
170+
171+
### Token exchange fails
172+
173+
Common causes:
174+
- **Trust policy doesn't exist**: Verify the file exists at `.github/chainguard/{identity}.sts.yaml`
175+
- **OIDC token doesn't match policy**: Check that issuer and subject match your OIDC token
176+
- **App not installed**: Ensure Octo STS is installed and has access to the repository
177+
- **Wrong branch**: Trust policies are typically read from the default branch (main/master)
178+
- **Invalid permissions**: The policy requests permissions that don't exist or can't be granted by the app
179+
180+
## Operational Questions
181+
182+
### How long do Octo STS tokens last?
183+
184+
By default, tokens expire after 1 hour.
185+
186+
### Can I refresh Octo STS tokens?
187+
188+
No, Octo STS tokens cannot be refreshed. When a token expires, exchange a new OIDC token with Octo STS to obtain a new GitHub token. This is intentional - short-lived tokens should be regularly renewed.
189+
190+
### What happens when Octo STS permissions are updated?
191+
192+
Octo STS periodically adds or removes GitHub permissions to support new use cases. When this happens:
193+
- An issue is created in the Octo STS repository explaining the changes
194+
- You'll receive a notification to approve the updated permissions in your GitHub App installation
195+
- Updates are applied quarterly, with exceptions for critical changes
196+
197+
## Migration
198+
199+
### How do I migrate from PATs to Octo STS?
200+
201+
1. Identify where PATs are currently used
202+
2. Determine if those systems can provide OIDC tokens
203+
3. Create appropriate trust policies for each use case
204+
4. Update automation to exchange OIDC tokens instead of using PATs
205+
5. Test thoroughly in a non-production environment
206+
6. Revoke PATs once Octo STS is working
207+
208+
### Can I use both PATs and Octo STS during migration?
209+
210+
Yes, you can use both during a transition period. This allows gradual migration and rollback capability if issues arise.
211+
212+
## Getting Help
213+
214+
### Where can I report bugs?
215+
216+
Report bugs in the [Octo STS GitHub repository](https://github.com/octo-sts/app/issues).
217+
218+
### Where can I ask questions?
219+
220+
- GitHub Discussions in the [Octo STS repository](https://github.com/octo-sts/app/discussions)
221+
- Open an issue for specific problems
222+
- Review existing FAQ and documentation
223+
224+
### How can I contribute to Octo STS?
225+
226+
Octo STS is open source. Contributions are welcome:
227+
- Report bugs and request features
228+
- Improve documentation
229+
- Submit pull requests for code changes
230+
- Share your use cases and integration patterns
231+
232+
See the [repository](https://github.com/octo-sts/app) for contribution guidelines.
233+
234+
## Next Steps
235+
236+
- [Getting Started with Octo STS](/open-source/octo-sts/getting-started-with-octo-sts/) - Set up octo-sts for the first time
237+
- [Trust Policy Reference](/open-source/octo-sts/trust-policy-reference/) - Detailed trust policy documentation
238+
- [GitHub Actions Integration](/open-source/octo-sts/how-to-use-octo-sts-with-github-actions/) - Use octo-sts with GitHub Actions

‎content/open-source/octo-sts/octo-arch.webp‎

31.9 KB
Loading

‎content/open-source/octo-sts/overview.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: "Octo STS Overview"
3+
linktitle: "Overview"
4+
type: "article"
5+
lead: "A security token service that eliminates the need for GitHub Personal Access Tokens by enabling OIDC-based federation for GitHub API access"
6+
description: "Learn about Octo STS, an open source security token service for GitHub that uses OIDC federation to eliminate long-lived Personal Access Tokens"
7+
date: 2025-12-23T15:04:05+01:00
8+
lastmod: 2025-12-24T15:04:05+01:00
9+
tags: ["octo-sts", "Overview", "OIDC", "Security"]
10+
draft: false
11+
images: []
12+
menu:
13+
docs:
14+
parent: "open-source"
15+
weight: 001
16+
toc: true
17+
---
18+
19+
Octo STS is a GitHub App developed by Chainguard that acts as a Security Token Service (STS) for the GitHub API. It enables workloads running anywhere that can produce OIDC tokens to federate with GitHub, exchanging those tokens for short-lived GitHub access tokens. The primary goal is to eliminate the need for GitHub Personal Access Tokens (PATs), which are long-lived credentials that pose significant security risks.
20+
21+
## Why Octo STS Matters
22+
23+
Long-lived access tokens are a common target in security incidents. When attackers gain access to a PAT, they can exploit it to access repositories, make changes, and pivot to other resources. These tokens often have broad permissions and no expiration date, making them particularly dangerous if compromised.
24+
25+
Octo STS addresses this problem by:
26+
27+
- **Eliminating long-lived credentials**: No more PATs that sit around indefinitely
28+
- **Enabling OIDC federation**: Leverage existing identity providers to authenticate workloads
29+
- **Providing short-lived tokens**: Generated tokens expire automatically
30+
- **Implementing fine-grained access control**: Grant only the permissions needed for specific tasks
31+
- **Supporting multiple identity providers**: Works with GitHub Actions, cloud providers (AWS, GCP, Azure), Kubernetes, and any OIDC-compliant system
32+
33+
## How Octo STS Works
34+
35+
Octo STS operates through a trust policy model. The steps to install and use Octo STS are:
36+
37+
1. **Install the GitHub App**: Add the [octo-sts](https://github.com/apps/octo-sts) GitHub App to your organization or repositories
38+
2. **Define trust policies**: Create policy files (`.github/chainguard/{name}.sts.yaml`) that specify which identities can access which resources
39+
3. **Exchange tokens**: Workloads present OIDC tokens to Octo STS
40+
4. **Receive GitHub tokens**: If the identity matches the trust policy, Octo STS issues a short-lived GitHub token with specified permissions
41+
42+
The Octo STS app needs to request a large number of permissions. This set of permissions is reviewed on a quarterly basis to ensure it meets common use cases without being overly broad.
43+
44+
### The Token Exchange Process
45+
46+
This sequence diagram outlines the token exchange process in Octo STS:
47+
48+
<center><img src="octo-arch.webp" alt="Octo STS sequence diagram showing order of network requests" style="width:950px;"></center>
49+
50+
## Common Use Cases
51+
52+
- Developing Actions that create Pull Requests (a PAT is required to trigger presubmit GitHub Actions)
53+
54+
- Developing Actions that interact across repositories (unsupported by built-in permissions)
55+
56+
- Developing Actions that interact with the GitHub organization level
57+
58+
- Providing external services (e.g. clouds) with access to repositories
59+
60+
## Learn More
61+
62+
- [Getting Started with Octo STS](/open-source/octo-sts/getting-started-with-octo-sts/) - Set up Octo STS and create your first trust policy
63+
- [Using Octo STS with GitHub Actions](/open-source/octo-sts/how-to-use-octo-sts-with-github-actions/) - Integrate Octo STS into GitHub Actions workflows
64+
- [Using Octo STS with Kubernetes](/open-source/octo-sts/how-to-use-octo-sts-with-kubernetes/) - Federate Kubernetes workload identities with GitHub
65+
- [Using Octo STS with Cloud Providers](/open-source/octo-sts/how-to-use-octo-sts-with-cloud-providers/) - Connect AWS, GCP, and Azure workloads to GitHub
66+
- [Trust Policy Reference](/open-source/octo-sts/trust-policy-reference/) - Complete trust policy syntax and options
67+
- [FAQ](/open-source/octo-sts/faq/) - Frequently asked questions and troubleshooting
68+
69+
## Resources
70+
71+
- [Octo STS GitHub Repository](https://github.com/octo-sts/app)
72+
- [Original Blog Post](https://www.chainguard.dev/unchained/the-end-of-github-pats-you-cant-leak-what-you-dont-have)
73+
- [Trust Policy JSON Schema](https://raw.githubusercontent.com/octo-sts/app/refs/heads/main/pkg/octosts/octosts.TrustPolicy.json)

0 commit comments

Comments
 (0)