Skip to main content
Mapagam

Managing Workflow Permissions

1. Setting Workflow Permissions

Permission Description Default Level Required Scope
actions Read and write access to GitHub Actions workflows, runs, and artifacts. read workflow
contents Read and write access to repository contents, including branches, tags, and commits. read contents
deployments Read and write access to deployments and deployment environments. read deployment
discussions Read and write access to repository discussions. read discussion
issues Read and write access to issues and issue comments. read issues
packages Read and write access to packages published to GitHub Packages. read packages
pages Read and write access to repository pages settings. read pages
pull-requests Read and write access to pull requests and their comments. read pull-requests
repository-projects Read and write access to repository projects. read project
security-events Read and write access to security alerts and related data. read security-events
statuses Read and write access to commit statuses. read status

Example: Setting Workflow Permissions

name: Example Workflow
on:
  push:
    branches:
      - main

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Example step
        run: echo "Hello, world!"

2. Using Read-Only Permissions

Permission Description Usage
contents: read Reads repository contents, commits, branches, tags, and pull requests For workflows that only need to read repository data
actions: read Reads workflow runs, jobs, and logs For workflows that only need to read action metadata
checks: read Reads checks and check runs For workflows that only need to read check data
deployments: read Reads deployments and deployment statuses For workflows that only need to read deployment data
issues: read Reads issues and issue comments For workflows that only need to read issue data
packages: read Reads packages in the repository For workflows that only need to read package data
pull-requests: read Reads pull requests and comments For workflows that only need to read PR data
repository-projects: read Reads repository projects For workflows that only need to read project data
security-events: read Reads security alerts and related data For workflows that only need to read security data
statuses: read Reads commit statuses and deployment statuses For workflows that only need to read status data

Example: Using Read-Only Permissions

name: Read-Only Workflow
on:
  push:
    branches: [ main ]

jobs:
  read-only-job:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: List files
        run: |
          ls -la
Note: Setting permissions to read ensures that workflows can only read data and cannot make changes.

3. Using Write Permissions

Permission Description Usage
contents Read and write access to repository contents permissions: { contents: 'write' }
actions Read and write access to workflow runs permissions: { actions: 'write' }
checks Read and write access to checks permissions: { checks: 'write' }
deployments Read and write access to deployments permissions: { deployments: 'write' }
discussions Read and write access to discussions permissions: { discussions: 'write' }
issues Read and write access to issues permissions: { issues: 'write' }
packages Read and write access to packages permissions: { packages: 'write' }
pages Read and write access to pages permissions: { pages: 'write' }
pull_requests Read and write access to pull requests permissions: { pull_requests: 'write' }
repository_hooks Read and write access to repository hooks permissions: { repository_hooks: 'write' }
repository_projects Read and write access to repository projects permissions: { repository_projects: 'write' }
security_events Read and write access to security events permissions: { security_events: 'write' }
statuses Read and write access to statuses permissions: { statuses: 'write' }

Example: Setting Write Permissions

name: Example Workflow
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      actions: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy
        run: |
          echo "Deploying..."
Note: Setting permissions to write grants the workflow the ability to make changes to the repository or related resources. Be cautious when granting write permissions, especially in public repositories.

4. Disabling All Permissions

Example: Disabling all permissions

permissions: {}
Permission Value Description
actions read Read access to GitHub Actions workflows
checks read Read access to checks
contents read Read access to repository contents
deployments read Read access to deployments
discussions read Read access to discussions
issues read Read access to issues
packages read Read access to packages
pages read Read access to Pages
pull-requests read Read access to pull requests
repository-projects read Read access to repository projects
security-events read Read access to security events
statuses read Read access to statuses
Note: Setting permissions: {} disables all permissions for the workflow. This is useful when you want to ensure no permissions are granted by default.

5. Setting Token Permissions

Permission Description Default Scope Required for
actions Read and write workflow runs and artifacts read Workflow execution, artifact management
checks Read and write checks for a repository read Check runs, status checks
contents Read and write repository contents, commits, branches, tags, and notes read Pushing code, reading repository files
deployments Read and write deployments and deployment statuses read Deployment management, status updates
discussions Read and write discussions in a repository read Managing GitHub Discussions
environments Read and write environments read Environment variables, secrets
issues Read and write issues in a repository read Issue creation, updates, comments
packages Read and write packages in a repository read Publishing or downloading packages
pages Read and write Pages deployments read Managing GitHub Pages
pull_requests Read and write pull requests in a repository read Pull request management, reviews
repository_hooks Read and write repository hooks read Managing webhooks
repository_projects Read and write repository projects read Project board management
security_events Read and write security events in a repository read Security scanning, alerts
statuses Read and write commit statuses in a repository read Commit status updates, checks
team_discussions Read and write team discussions in a repository read Team communication, discussions
vulnerability_alerts Read and write vulnerability alerts in a repository read Security vulnerability notifications

Example: Setting permissions in a workflow

name: Example Workflow
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
Note: By default, GitHub Actions workflows have limited permissions. You must explicitly grant the necessary permissions using the permissions key in your workflow file.
Warning: Granting excessive permissions can pose security risks. Always follow the principle of least privilege when setting permissions.

6. Configuring Contents Permission

Permission Values Description
contents read | write | none Controls access to repository contents, including files and branches

Example: Setting Contents Permission

permissions:
  contents: write
Note: The contents permission is required for workflows that need to read or modify repository files, such as when pushing changes or checking out code.

7. Configuring Pull Request Permission

Permission Description Usage
pull-requests Read and write access to pull requests permissions:
contents: read
pull-requests: write

Example: Setting PR Permissions

name: PR Permission Example
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  pr-check:
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
Note: Setting pull-requests: write allows the workflow to update pull request status, comments, and labels.

8. Configuring Issues Permission

Permission Description Usage
issues Read and write access to issues and pull requests issues: write
issues.read Read-only access to issues and pull requests issues: read
issues.none No access to issues or pull requests issues: none

Example: Setting Issues Permission in Workflow

permissions:
  issues: write
Note: The issues permission is required to create, update, or delete issues in a repository.

9. Configuring Packages Permission

Permission Description Default Access Required Scope
packages.read Read access to packages None read
packages.write Write access to packages None write
packages.delete Delete access to packages None delete

Example: Setting Package Permissions in Workflow

name: Package Permissions
on:
  push:
    branches: [ main ]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - name: Publish Package
        run: npm publish
Note: The packages scope must be explicitly granted in the workflow permissions to allow publishing or managing packages.

10. Configuring Deployments Permission

Permission Description Default Value Notes
contents Read and write access to repository contents read Required for most deployment workflows
deployments Read and write access to deployments read Used for managing deployment environments
id-token Read and write access to OIDC tokens read Needed for GitHub OIDC integration

Example: Setting Deployments Permission

permissions:
  contents: write
  deployments: write
  id-token: write
Note: Setting deployments to write allows the workflow to create and update deployment environments.

11. Setting Job-Level Permissions

Permission Description Default Required for
contents Read and write access to repository contents DEPRECATED Workflow runs, artifact uploads, and pull request creation
actions Read and write access to workflow runs Read Workflow triggers, job status updates
checks Read and write access to checks Read Check run creation, updates
deployments Read and write access to deployments Read Deployment creation, status updates
discussions Read and write access to discussions Read Discussion creation, updates
issues Read and write access to issues Read Issue creation, updates, comments
packages Read and write access to packages Read Package publishing, downloads
pages Read and write access to Pages Read Pages deployment, configuration
pull-requests Read and write access to pull requests Read PR creation, updates, reviews
repository-projects Read and write access to repository projects Read Project creation, updates, cards
security-events Read and write access to security events Read Security alert creation, updates
statuses Read and write access to commit statuses Read Status updates, creation

Example: Setting job-level permissions

jobs:
  build:
    permissions:
      contents: read
      actions: write
      checks: write
Note: The contents permission is deprecated as of GitHub Actions v2. It's recommended to use more granular permissions like actions, checks, and pull-requests.

12. Using Minimal Permissions

Permission Description Usage Required for
actions:read Read access to workflow runs and artifacts permissions: { actions: 'read' } Reading workflow logs, artifacts
actions:write Write access to workflow runs and artifacts permissions: { actions: 'write' } Creating artifacts, triggering workflows
contents:read Read access to repository contents permissions: { contents: 'read' } Checking out code, reading files
contents:write Write access to repository contents permissions: { contents: 'write' } Committing changes, pushing to branches
deployments:read Read access to deployments permissions: { deployments: 'read' } Viewing deployment status
deployments:write Write access to deployments permissions: { deployments: 'write' } Creating or updating deployments
issues:read Read access to issues and pull requests permissions: { issues: 'read' } Reading issue comments
issues:write Write access to issues and pull requests permissions: { issues: 'write' } Creating or commenting on issues
packages:read Read access to packages permissions: { packages: 'read' } Downloading packages
packages:write Write access to packages permissions: { packages: 'write' } Uploading packages
pull-requests:read Read access to pull requests permissions: { pullRequests: 'read' } Viewing PRs
pull-requests:write Write access to pull requests permissions: { pullRequests: 'write' } Merging PRs, commenting on PRs
repository-projects:read Read access to repository projects permissions: { repositoryProjects: 'read' } Viewing project boards
repository-projects:write Write access to repository projects permissions: { repositoryProjects: 'write' } Creating or updating project boards
security-events:read Read access to security events permissions: { securityEvents: 'read' } Viewing security alerts
security-events:write Write access to security events permissions: { securityEvents: 'write' } Updating security alerts
statuses:read Read access to commit statuses permissions: { statuses: 'read' } Viewing commit status
statuses:write Write access to commit statuses permissions: { statuses: 'write' } Setting commit status

Example: Setting minimal permissions in a workflow

name: Minimal Permissions Example
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run build
        run: |
          echo "Building..."
Note: By default, GitHub Actions workflows have contents: read and actions: read permissions. If you don't explicitly set permissions, workflows will have access to more than needed.

Was this article helpful?

Related Cheat Sheets