⚙️ setup-p4

GitHub Action for running Perforce Helix Core P4 CLI commands.

The perforce/setup-p4 action is a JavaScript Action that sets up Perforce Helix Core P4 CLI in your GitHub Actions workflow, allowing you to easily create interactions between your repository and your Perforce server.

In addition, the Action includes the following features:

• This Action supports all GitHub Hosted and Self-Hosted Runner Operating Systems
• Defaults to latest version of P4 CLI but can be set to a specific version
• All P4 CLI commands can be run from the Action
• Adds p4 to PATH for easy access to P4 CLI
• Optionally use GitHub Action Inputs to simplify setting up P4 CLI workflows
• Connection details and credentials can be securely stored in the GitHub Action secrets

More features to come!

• Usage
  • Quickstart
  • Inputs
    • command
    • global_options
    • arguments
    • working_directory
    • spec
    • p4_version
  • Configuration
    • Environment Variables
    • Secrets
  • Outputs
    • Output Usage
  • Versioning
  • Helpers
  • Command Structure
    • p4 login
    • STDIN required
    • Everything Else
• Example GitHub Action Workflows
• Detailed logs
• Limitations
  • Network Connectivity
  • Available Disk Space
• Author Information
• Support
• Code of Conduct
• License
• Contributor's Guide
  • Issues
  • Discussions
  • act
    • .actrc
    • my.secrets

Usage

Quickstart

Start by creating GitHub Secrets for the following values. We will use these values later to connect to your Helix Core server.

• P4PORT
• P4USER
• P4PASSWD

Example:

P4PORT="ssl:helixcore.example.com:1666"
P4USER="ci"
P4PASSWD="mysecurepassword"

Add the setup-p4 GitHub Action to your GitHub Workflow like so:

Define a job with environment variables that will be available for all steps:

jobs:
  quickstart:
    runs-on: ubuntu-latest
    name: quickstart

    env:
      P4PORT: ${{ secrets.P4PORT }}
      P4USER: ${{ secrets.P4USER }}
      P4PASSWD: ${{ secrets.P4PASSWD }}

Add a step that uses perforce/setup-p4@v1:

steps:
  - uses: perforce/setup-p4@v1
    with:
      command: login
      p4_version: 21.2

The above step will do the following:

• based on p4_version, download, install, and add the P4 CLI to PATH. (Note: omitting this line will default to the latest version of the P4 CLI)
• execute p4 login utilizing a GitHub Secret for the password with your

Now add a simple step that verifies authentication by running the p4 depots command:

steps:
  - uses: perforce/setup-p4@v1
    with:
      command: depots

Review the quickstart.yml for an example workflow that:

• install p4 CLI
• logs into Helix Core
• creates a workspace (client)
• pulls down assets from Helix Core

Inputs

Name	Description	Required	Default
command	p4 CLI command to execute	yes
global_options	p4 CLI global options that are supplied on the command line before the command	no
arguments	arguments specific to the P4 command being used	no
working_directory	directory to change into before running p4 command	no	.
spec	spec content that is fed into p4 stdin to create/update resources	no
p4_version	version of p4 CLI to download and cache	no	21.2

command

command supports all P4 CLI commands.

global_options

global_options supports all P4 global options.

Common global_options you may want to set would include

• P4PORT by including -p ssl:helixcore.example.com:1666 in global_options
• P4USER by including -u joe in global_options

arguments

arguments supports all P4 Command arguments. To find available arguments first find the command documentation and then look under the Options section.

working_directory

The Action will change directory to what is provided in working_directory. Note that the specified directory must exist.

spec

If spec is provided the contents of spec will be passed to the STDIN of the p4 command. In arguments include the option -i so that p4 reads from STDIN instead of opening your P4EDITOR. (See p4 client in quickstart.yml for an example.)

p4_version

p4_version defines the version of the p4 binary that will be downloaded and cached. p4_version should only be specified in a setup GitHub Action Step. In this step the it will check if the specified version is already present, if it is not it will be loaded, cached, and added to the $PATH. All subsequent steps will be able to use the p4 found in the $PATH.

See our CI workflows for examples.

Configuration

Environment Variables

The P4 CLI can utilize environment variables to get configuration and the same applies to p4 in GitHub Actions. GitHub Actions allows you to set environment variables at multiple levels:

• Workflow
• Job
• Step

Note: Because workflows are visible to other users, you should use secrets to store sensitive information such as passwords.

- name: p4 sync
  uses: perforce/setup-p4@v1
  env:
  	P4CLIENT: sdp-dev-pipeline
  with:
    command: sync
    arguments: -f

Reference the quickstart.yml Workflow file in this repository for examples of setting environment variables at each level.

Secrets

All p4 commands will require valid authentication to your Helix Core server. Most Workflows will start with a p4 login like the following:

- name: p4 login
  uses: perforce/setup-p4@v1
  with:
    command: login
    global_options: '-p helixcore.example.com:1666 -u joe'
    env:
    	P4PASSWD: ${{ secrets.P4PASSWD }}

To use the above step your GitHub Repository will need to have a Secret named P4PASSWD and the contents will need to be the Helix Core password of the user you want to authenticate as.

You can name your GitHub Repository Secret anything you would like but the Action expects you to set the environment variable P4PASSWD to your user's Helix Core password.

Outputs

When using the provided helpers this action creates three outputs for all p4 commands: stdout, stderr, and exit_code. The following outputs are available for subsequent steps:

• stdout - The STDOUT stream of the call to the p4 CLI.
• stderr - The STDERR stream of the call to the p4 CLI.
• exit_code - The exit code of the call to the p4 CLI.

Output Usage

The following is an example of how to use each of the outputs from this action:

- name: p4 depots
  id: depots
  uses: perforce/setup-p4@v1
  with:
    command: depots

- name: echo outputs from previous step
  run: |
    echo "this will print the outputs from the depots command in the previous step"
    echo "stdout was: ${{ steps.depots.outputs.stdout }}"   
    echo "stderr was: ${{ steps.depots.outputs.stderr }}"
    echo "exit code was: ${{ steps.depots.outputs.exit_code }}"

Versioning

We recommend pinning to the latest available major version:

- uses: perforce/setup-p4@v1

This action follows semantic versioning, but we're human and sometimes make mistakes. To prevent accidental breaking changes, you can also pin to a specific version:

- uses: perforce/[email protected]

However, you will not get automatic security updates or new features without explicitly updating your version number.

Helpers

After running the setup routine, subsequent steps in the same job can run arbitrary P4 CLI commands using the GitHub Actions run syntax. This allows most P4 CLI commands to work exactly like they do on your local command line. Take a look at setup-only.yml for an example of what this looks like.

Alternatively to running P4 CLI commands using the GitHub Actions run syntax you can use helpers that are provided by the setup-p4 action.

Benefits to using the helpers:

• you don't have to worry about passing complex spec as stdin to the p4 command (example)
• stdout, stderr, and exit_code are captured for you and stored as GitHub Outputs
• Bad p4 commands, bad p4 arguments, bad p4 spec, and pipefail errors are all caught and will fail the GitHub Step to prevent false positives in your pipelines

Command Structure

1. Installs the p4 CLI
2. Builds up a p4 command based on your inputs. There are three scenarios that define how the command is built up
   1. p4 login
   2. STDIN required
   3. everything else

This is how the command gets built up:

COMMAND="p4 $GLOBAL_OPTIONS $COMMAND $ARGUMENTS"

p4 login

The p4 login command will read the user password from STDIN so $P4PASSWD gets echoed into $COMMAND.

echo "${P4PASSWD}" | ${COMMAND}

STDIN required

This command format is used whenever a p4 resource must be created or updated. The contents of your spec are passed to STDIN of p4 command.

echo "${SPEC}" | ${COMMAND}

Everything Else

${COMMAND}

Example GitHub Action Workflows

You can find some example workflows that use setup-p4 in the examples directory.

Name	Description
Quickstart	Basic example that performs a p4 login, creates a workspaces, and sync files down from Helix Core.
Setup Only	This example performs the same steps as the Quickstart example but does not utilize any of the Action helper inputs
Action Outputs	Echos the stdout, stderr, and exit code

Additionally here are example projects that use setup-p4

• setup-p4-example-build-template - An example workflow that syncs content from Helix Core and publishes it to GitHub Pages.
• More to come!

Detailed logs

To enable debug logging, create a GitHub Repository Secret named ACTIONS_STEP_DEBUG with the value true. See here for more information. Run your workflow again and review the new debug logging.

Limitations

Network Connectivity

GitHub Hosted Actions run in Azure so the list of Azure IPv4 addresses must be able to reach your Helix Core instance. To test if your Helix Core server is reachable from GitHub Hosted Actions create a workflow with the following content and run it:

on:
  workflow_dispatch:

name: Network Connectivity Test

jobs:

  network:
    runs-on: ubuntu-latest
    steps:
    - run: nc -vz ${your helix core public IP} 1666

If your Helix Core server is reachable you will see output like the following:

Run nc -vz public.perforce.com 1666
Connection to public.perforce.com 1666 port [tcp/*] succeeded!

and if it is not reachable you will get an error like the following:

Run nc -vz public.perforce.com 1666
nc: connect to public.perforce.com port 1666 (tcp) failed: Connection timed out
Error: Process completed with exit code 1.

Available Disk Space

GitHub Hosted Actions provide ~30GB of disk space to your workflow. Depending on your P4 Client Depot mapping you may run out of disk space. Your options are to update your Depot mapping to reduce what data is pulled down or switching to Self Hosted GitHub Actions.

Author Information

This module is maintained by the contributors listed on GitHub.

Development of this module is sponsored by Perforce.

Support

setup-p4 is a community supported project. Pull requests and issues are the responsibility of the project's moderator(s); this may be a vetted individual or team with members outside of the Perforce organization. All issues should be reported and managed via GitHub (not via Perforce's standard support process).

Code of Conduct

See CODE_OF_CONDUCT.md

License

See LICENSE

Contributor's Guide

Issues

Please create an issue for all bug or security vulnerability reports.

Discussions

To discuss feature requests, use cases, or to ask general questions please start a discussion.

Here are the steps for contributing:

1. fork the project
2. clone your fork to your workstation
3. run npm ci to install all the dependencies
4. run npm run build to package the action
5. create a .actrc and act.secrets file for testing locally (examples below)
6. run act --job unit , act --job smoke, and act --job integration before submitting a PR
   1. Note that the integration tests will require a running Helix Core server.
7. commit changes and submit PR

act

act can be used to test GitHub Actions locally before having to commit any code.

.actrc

The .actrc can be used to provide default configuration to act. Example .actrc file to have act use the act.secrets file

--secret-file act.secrets

my.secrets

Create a my.secrets file (ignored via .gitignore file) that will allow the Action to authenticate to your Helix Core.

P4PASSWD=""
P4PORT=""
P4USER=""