Skip to main content

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
permissions:
  contents: write

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, or dotnet pack to publish packages
  • Set up secrets in GitHub repository settings for authentication
  • Use npm ci or yarn install --frozen-lockfile for reproducible builds
  • Securely manage tokens with GITHUB_TOKEN or 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.

Was this article helpful?