Skip to main content

3. Share and Audit

On this page, you give the practice project the GitHub Integration Connection of another project, and you save a token as a secret. You learn what service accounts and API credentials can do today. Then you read the audit trail and find the calls that you allowed and rejected on page 2.

Step 1: Share an Integration Connection​

A GitHub organization can be connected one time only. To use it in the practice project, share it from the project that owns it. You must be a Project Admin in both projects.

  1. Share it from the owning project

    In the project that has the GitHub Integration Connection, go to Settings → GENERAL → Integrations, open GitHub, and select the Sharing tab. Click Share on the Integration Connection's row.

  2. Pick the projects

    Select Specific projects, and select the practice project. Do not keep All projects, because that also includes projects that people make later. Click Share.

  3. Import it into the practice project

    In the practice project, go to Settings → ACCESS → Shared resources, and select Imported from other projects. Under Available to import, click Import next to the Integration Connection. Keep the proposed name or type another, and click Import.

Open the practice project's Settings → GENERAL → Integrations. Check that the imported Integration Connection shows there, with the name of the project that it comes from.

The practice project now uses the owning project's credentials. Agents in the practice project can do with GitHub what those credentials allow. Code in the sandbox can also read the token. If the Integration Connection can write to production repositories, connect a second GitHub with read-only permissions for practice instead.

Step 2: Save a secret​

When an agent needs an API token, save the token as a secret. Do not put it in agent.yaml or in the instructions.

  1. Create the secret

    Go to Settings → PLATFORM → Secrets, and click New secret. In ID, type status_token. Paste the token in Value, and click Create.

  2. Use it in an agent

    Add the secret to the agent's environment in agent.yaml:

    YAML
    env:
    - name: STATUS_TOKEN
    value: ${{ secrets.status_token }}

    Commands in the agent's sandbox read it as $STATUS_TOKEN.

Check that the secret shows in the list with its ID. Nobody can read the value again, also not a Project Admin. Secrets belong to one project. The organization has no secrets that all projects share.

Step 3: Give automation its own identity​

A script or a CI job must not use a person's login. Give it a service account. A service account has its own roles and its own API keys, and the audit records show its name.

  • A Project Admin creates one in Settings → ACCESS → Service accounts → New service account, with its roles in the project. Its page has New key. Autoheal shows the key one time.
  • An Org Admin creates organization service accounts in the organization's Settings → Service accounts.
  • Each person can also make a personal access token from their avatar menu. It has the same access as that person.
A key cannot run agents yet

Put a service-account key or a personal access token in AUTOHEAL_TOKEN. It reaches chat, alerts, the Context Graph, integrations and agent policies. It cannot reach projects, agents, runs or triggers yet. These need a person's autoheal login. A CI job cannot start an agent run with a key.

Step 4: Read the audit trail​

The audit trail records every tool call of every agent in the project. For each call, it shows the tool, the Integration Connection, the arguments, the output, and who approved it.

  1. Open the audit trail

    In the practice project, go to Settings → PLATFORM → Audit trail.

  2. Find the calls from page 2

    Type github_list_repositories in the search box. Search matches the tool name only.

  3. Read the decisions

    Check that one call shows Success with your name under Approvers. Check that one call shows Rejected. Open the rejected call. Check that it names the policy and the note that you typed.

The audit trail does not show changes to access. To see who gave or took away a role, use the access log. Read it through the API with GET /api/v1/rbac/audit-events.

What to know​

  • Each project that imports a shared Integration Connection gets its own copy, with its own webhook URL. Events sent to that URL start that project's triggers only.
  • The owning project keeps the credentials. If it stops sharing the Integration Connection or deletes it, the copies stop working.
  • The audit trail stores arguments and output without masking. Everyone with a role on the project, also Read-only, can read them. Give roles on a project only to people who may see its activity.
  • The page shows the last 30 days and hides built-in tools by default. Show built-in shows them. Download JSON exports up to 5,000 rows.
  • A Member can create, replace and delete secrets. To use a secret, an agent must name it in agent.yaml or in a trigger's with.

From the CLI​

BASH
autoheal api GET /api/v1/runtime/calls --project practice --query exclude_builtin=true --query limit=3
autoheal api GET /api/v1/rbac/audit-events --query limit=1

The first command lists the newest tool calls in the project, as the audit trail shows them. Each row has tool_name, integrations and decided_by. The second command lists the newest change to access in the organization. Both need your autoheal login. A service-account key cannot call /api/v1/runtime/calls.

See Sharing Integrations, Secrets, API Credentials and Audit Trail.