DOCSEARCHbyAlgolia
Submit Docs

Portainer Documentation

website·Indexed 32 days ago

https://portainer-deploy.cssnr.com

Documentation for Portainer, including guides on relative path support and the Portainer Stack Deploy Action for GitHub Actions, detailing input parameters such as name, url, token, and prune.

Tokens
5.3K
Snippets
20
Records
39
Agent score
50%

What's inside Portainer

  1. Understand GitHub organization accounts

    GitHub organizations are shared accounts that act as containers for shared work, providing a unique name and brand for businesses or open-source projects. They allow multiple personal accounts to collaborate on projects. Access is managed by organization owners who can assign roles to members to control access to the organization's resources, repositories, projects, and apps. To simplify management, organizations support nested teams with cascading permissions.

  2. Understand GitHub Actions workflow basics

    A GitHub Actions workflow is a configurable automated process defined by a YAML file located in the .github/workflows directory of a repository. A workflow consists of three primary components:

    1. Events: Triggers that start the workflow.
    2. Jobs: Execution units that run on a runner machine. Each job contains one or more steps.
    3. Steps: Individual tasks within a job that either execute a custom script or a reusable action.

  3. Set up a basic Portainer deployment workflow

    To deploy a stack to Portainer, create a workflow file in .github/workflows. Ensure that sensitive credentials like the Portainer token are stored in GitHub Actions Secrets to prevent them from appearing in logs.

  5. View workflow run logs to diagnose failures

    When a GitHub Actions workflow run fails, you can identify the specific failed step and review its build logs. GitHub automatically expands failed steps in the log view. You can also copy a permalink to a specific line in the log file by clicking the line number.

    Note that every job includes two automatic steps: 'Set up job' (which records runner image details and preinstalled tools for GitHub-hosted runners) and 'Complete job'.

    Steps to view logs:

    1. Navigate to the repository main page and click the Actions tab.
    2. Select the specific workflow from the left sidebar.
    3. Click the name of the specific workflow run to see the summary.
    4. Click the desired job under Jobs or within the visualization graph.
    5. Review the expanded failed steps.

  6. Download workflow run log archives

    You can download the complete log files for a workflow job as an archive. Read access to the repository is required.

    Steps to download logs:

    1. Navigate to the repository main page and click the Actions tab.
    2. Select the workflow from the left sidebar.
    3. Click the name of the workflow run to see the summary.
    4. Click the job you wish to download logs for.
    5. Click the gear icon (options menu) in the upper-right corner of the log view.
    6. Select Download log archive.

  7. Use secrets in a GitHub Actions workflow

    Access secrets using the secrets context. Secrets can be passed as action inputs or as environment variables. If a secret is not set, the expression returns an empty string.

    Important Constraints:

    • Secrets (except GITHUB_TOKEN) are not passed to runners when a workflow is triggered from a forked repository.
    • Secrets are not automatically passed to reusable workflows.
    • Secrets are not available to workflows triggered by Dependabot events.
    • Secrets cannot be directly referenced in if: conditionals; instead, set them as job-level environment variables and reference those variables in the conditional.
    steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

  8. Delete workflow run logs via the GitHub web interface

    To delete logs for a specific workflow run using the browser, you must have write access to the repository. Navigate to the repository's Actions tab, select the specific workflow from the sidebar, click on the name of the desired run to open the summary, and select Delete all logs from the kebab (three-dot) menu in the upper-right corner.

  9. Pass secrets to shell commands securely

    Avoid passing secrets directly as command-line arguments to prevent them from being visible in process lists (e.g., ps command) or security audits. Instead, map the secret to an environment variable and reference that variable using the shell's specific quoting rules to handle special characters.
    # Bash example
steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

# PowerShell example
steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

# Cmd.exe example
steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

  10. Search for specific terms in workflow run logs

    You can search for specific text within the build logs of a workflow job. Note that the search only includes logs from steps that are currently expanded in the UI. Read access to the repository is required.

    Steps to search logs:

    1. Navigate to the repository main page and click the Actions tab.
    2. Select the workflow from the left sidebar.
    3. Click the name of the workflow run to see the summary.
    4. Click the job you wish to inspect.
    5. Use the Search logs search box in the upper-right corner of the log output to enter your query.

  11. Connect Portainer to GitHub Container Registry (GHCR)

    To allow Portainer to pull private images from GHCR, you must add GHCR as a custom registry in the Portainer UI using a GitHub Personal Access Token (PAT).

    Configure the following in Portainer > Registries > + Add registry:

    KeyValueDescription
    Nameghcr.ioDisplay name
    Registry URLghcr.ioAuthentication URL
    AuthenticationTrueEnable credentials
    UsernameusernameGitHub Username
    PasswordPATGitHub Personal Access Token

  12. Use relative path volumes for Git-based stacks in Portainer

    Relative path volumes allow you to reference files and directories stored within a Git repository alongside your compose file without knowing the absolute path on the host. This feature is exclusive to Portainer Business Edition and must be enabled during stack deployment from Git.

    When enabled, Portainer clones the Git repository to a specified local or network filesystem path and sets the working directory to the location of the compose file. This allows the use of relative paths (starting with ./ or ../) in the volumes section of the docker-compose file.

    version: '3.1'
services:
  webapp:
    image: nginx:latest
    volumes:
      - ./static:/usr/share/nginx/html # Relative to the compose file