Working with GitHub Token
1. Using GITHUB_TOKEN
| Property | Value | Description |
|---|---|---|
| GITHUB_TOKEN | ${{ secrets.GITHUB_TOKEN }} |
Automatic token provided by GitHub Actions for authentication |
Example: Using GITHUB_TOKEN to push changes
name: Push Changes
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Configure Git
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
- name: Push changes
run: |
echo "Deploying to production"
git add .
git commit -m "Deploy from GitHub Actions" || echo "No changes to commit"
git push origin main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note: The
GITHUB_TOKEN is automatically created and managed by GitHub, so you don't need to manually create or store it.
Warning: The
GITHUB_TOKEN has limited permissions by default. You may need to adjust permissions in your workflow file or repository settings for specific actions.
2. Authenticating API Requests
| Method | Token Source | Usage | Notes |
|---|---|---|---|
| GITHUB_TOKEN | github.token |
curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/user |
Automatically provided by GitHub Actions; no setup required |
| Personal Access Token (PAT) | Manual setup in GitHub Settings | curl -H "Authorization: Bearer ${{ secrets.PAT }}" https://api.github.com/user |
Must be stored as a secret in the repository or organization |
Example: Using GITHUB_TOKEN to access GitHub API
name: API Example
on:
push:
branches: [ main ]
jobs:
api-call:
runs-on: ubuntu-latest
steps:
- name: Fetch User Info
run: |
curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/user
Note: The
GITHUB_TOKEN has scopes based on the workflow's permissions. By default, it includes read access to repository contents and metadata.
Warning: Avoid exposing
GITHUB_TOKEN in logs or outputs. Use set-output carefully to prevent token leakage.
| Permission | Scope | Description |
|---|---|---|
| contents | Read/Write | Access repository contents, including branches and tags |
| actions | Read/Write | Manage workflow runs and artifacts |
| deployments | Read/Write | Manage deployment environments and statuses |
| issues | Read/Write | Manage issues and pull requests |
| packages | Read/Write | Manage packages in the GitHub Container Registry |
| pull-requests | Read/Write | Manage pull requests |
| repository-projects | Read/Write | Manage repository projects |
| security-events | Read/Write | Manage security alerts |
| statuses | Read/Write | Manage commit statuses |
3. Cloning Private Repositories
| Option | Values | Notes |
|---|---|---|
| GITHUB_TOKEN | github.token |
Automatically provided by GitHub Actions |
| permissions | contents: read |
Required for cloning private repos |
Example: Cloning a Private Repo
name: Clone Private Repo
on:
push:
branches: [ main ]
jobs:
clone:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout private repo
uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
repository: owner/private-repo
path: ./cloned-repo
Note: The
GITHUB_TOKEN has read access to the contents of the repository where the workflow is running.
Warning: Ensure that the
GITHUB_TOKEN has appropriate permissions to access the private repository.
4. Pushing Changes
| Permission | Description | Usage |
|---|---|---|
| contents: write | Allows pushing changes to the repository | |
Example: Pushing Changes with GitHub CLI
gh repo set-default owner/repo
git add .
git commit -m "Update docs"
git push origin main
Note: The
GITHUB_TOKEN must have contents: write permission to push changes.
5. Creating Pull Requests
| Option | Values | Notes |
|---|---|---|
| github.token | ${{ secrets.GITHUB_TOKEN }} |
Automatically provided by GitHub Actions |
| pull_request.title | Update README.md |
Title of the new pull request |
| pull_request.body | Automated update from GitHub Actions workflow |
Description for the pull request |
| pull_request.base | main |
Branch to merge changes into |
| pull_request.head | feature-branch |
Branch containing changes to merge |
Example: Create a Pull Request
name: Create Pull Request
on:
workflow_dispatch:
jobs:
create-pr:
runs-on: ubuntu-latest
steps:
- name: Create PR
uses: peter-evans/create-pull-request@v5
with:
token: ${{ secrets.GITHUB_TOKEN }}
title: "Update README.md"
body: "Automated update from GitHub Actions workflow"
branch: "feature-branch"
base: "main"
Note: The
GITHUB_TOKEN has contents: write permissions by default, allowing creation of pull requests.6. Creating Issues
| Property | Value | Description |
|---|---|---|
| github.token | ${{ secrets.GITHUB_TOKEN }} |
Token with read/write permissions for the repository |
| issue.title | string |
Title of the new issue |
| issue.body | string |
Body content of the issue (optional) |
| issue.assignees | array |
List of usernames to assign the issue to (optional) |
| issue.labels | array |
List of labels to apply to the issue (optional) |
Example: Create an issue with labels and assignees
name: Create Issue
on:
workflow_dispatch: {}
jobs:
create-issue:
runs-on: ubuntu-latest
steps:
- name: Create Issue
uses: actions/github-script@v7
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const result = await github.rest.issues.create({
owner: context.repo.owner,
repo: context.repo.repo,
title: 'Automated Issue from Workflow',
body: 'This issue was created automatically by a GitHub Action.',
labels: ['automation', 'bug'],
assignees: ['octocat']
});
console.log('Created issue:', result.data.number);
Note: The
GITHUB_TOKEN has limited permissions by default. For creating issues in private repositories or with extended permissions, you may need to use a personal access token (PAT) with appropriate scopes.
7. Commenting on PRs
| Property | Description | Example |
|---|---|---|
| github.event.pull_request.number | The PR number from the event payload | 123 |
| github.token | Token with write permissions to comment on PRs | ${{ secrets.GITHUB_TOKEN }} |
Example: Comment on PR
name: Comment on PR
on:
pull_request:
types: [opened]
jobs:
comment:
runs-on: ubuntu-latest
steps:
- name: Add Comment
uses: actions/github-script@v7
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const { data: comments } = await github.rest.issues.listComments({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number
});
if (comments.length === 0) {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: "Hello, this PR is ready for review!"
});
}
Note: The
GITHUB_TOKEN has write permissions to the repository and can be used to comment on PRs.
8. Creating Releases
| Property | Description | Example |
|---|---|---|
| github.token | Token used for authentication with GitHub API | secrets.GITHUB_TOKEN |
| release.name | Name of the release to be created | Release v1.0.0 |
| release.tag_name | Tag name for the release (must match existing tag) | v1.0.0 |
| release.body | Body content for the release notes | Release notes for version 1.0.0 |
| release.draft | Whether to create a draft release (default: false) | true |
| release.prerelease | Whether to mark the release as a pre-release (default: false) | false |
Example: Create Release with GitHub Actions
name: Create Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Create Release
uses: actions/create-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ github.ref }}
body: Release notes for ${{ github.ref }}
draft: false
prerelease: false
Note: The
GITHUB_TOKEN is automatically provided by GitHub Actions and has read/write permissions for the repository.
Warning: Ensure that tags are properly formatted and match the expected versioning scheme to avoid errors during release creation.
9. Managing Packages
| Package | Description | Access Level | Usage |
|---|---|---|---|
| npm | Node Package Manager for JavaScript/TypeScript packages | NEW Public or Private | Install with npm install |
| Maven | Java package manager for Maven Central and custom repositories | Public or Private | Use in pom.xml |
| NuGet | .NET package manager for NuGet.org and private feeds | Public or Private | Install with dotnet add package |
| PyPI | Python package index for distribution of Python packages | NEW Public or Private | Install with pip install |
| RubyGems | Ruby package manager for gems from RubyGems.org | Public or Private | Install with gem install |
Example: Publishing to npm
const { execSync } = require("child_process");
execSync("npm publish", { stdio: "inherit" });
Note: Ensure
NODE_AUTH_TOKEN is set in your GitHub Actions secrets for publishing to npm.
Warning: Avoid committing package lock files (e.g.,
package-lock.json) to version control if they contain sensitive tokens.
Managing Packages Summary
- Use
npm publish,mvn deploy, ordotnet packto publish packages - Set up secrets in GitHub repository settings for authentication
- Use
npm cioryarn install --frozen-lockfilefor reproducible builds - Securely manage tokens with
GITHUB_TOKENor personal access tokens
10. Using Token in Actions
| Property | Value | Description |
|---|---|---|
| github.token | ${{ secrets.GITHUB_TOKEN }} |
Automatic token provided by GitHub Actions for authentication |
Example: Using GITHUB_TOKEN to authenticate with GitHub API
name: GitHub API Example
on:
push:
branches: [ main ]
jobs:
api-call:
runs-on: ubuntu-latest
steps:
- name: Call GitHub API
run: |
curl -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
https://api.github.com/user
Note: The
GITHUB_TOKEN is automatically created and managed by GitHub Actions. It has limited scopes and permissions based on the workflow's trigger and repository settings.
11. Understanding Token Scope
| Scope | Description | Access Level | Usage |
|---|---|---|---|
| repo | Full access to repositories | Read/Write | Push, pull, create branches, manage releases |
| public_repo | Read access to public repositories | Read Only | Clone, read issues, pull requests |
| workflow | Read and write access to workflows | Read/Write | Trigger, edit, delete workflows |
| contents | Read and write access to repository contents | Read/Write | Commit, push, modify files |
| deployments | Read and write access to deployments | Read/Write | Create, update deployment statuses |
| issues | Read and write access to issues | Read/Write | Open, close, comment on issues |
| packages | Read and write access to packages | Read/Write | Publish, update, delete packages |
| pull_requests | Read and write access to pull requests | Read/Write | Review, approve, merge PRs |
| statuses | Read and write access to commit statuses | Read/Write | Update status of commits |
| write:packages | Write access to packages | Write Only | Publish new packages |
Example: Using repo scope in workflow
name: Example Workflow
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Deploy to server
run: |
echo "Deploying..."
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
12. Token Expiration
| Token Type | Expiration Time | Notes |
|---|---|---|
| GITHUB_TOKEN | 1 hour |
Automatically generated for each workflow run |
| Personal Access Token (PAT) | 90 days |
Configurable by user; can be set to never expire |
| Deployment Token | 30 days |
Used for deploying to GitHub Pages or other services |
Note: The
GITHUB_TOKEN is automatically rotated every hour and is valid only for the duration of a workflow run.Warning: Tokens with longer expiration times increase security risk if compromised.